Domain 2 · 18% of exam
Tool Design & MCP Integration glossary
64 terms drawn from this domain’s 6 lessons and the sources they cite. A term that matters in more than one domain appears on each of their pages.
The full glossary is searchable across all five domains, and the domain curriculum explains where each term is used.
- --allowedTools
- The CLI flag listing tools, in permission-rule syntax, that run without a permission prompt. It pre-approves rather than restricts — to restrict which tools exist at all, use `--tools`. code.claude.com › cli-reference
- --disallowedTools
- The CLI flag with two behaviours: a bare tool name such as `"Edit"` (or `"*"`) removes the tool from Claude's context entirely, while a scoped rule such as `Bash(rm *)` leaves the tool available and denies only matching calls. code.claude.com › permissions
- --tools
- The CLI flag that restricts which tools are available to the agent at all, as opposed to `--allowedTools`, which only skips the permission prompt. In the SDK the equivalent `tools` option keeps only the listed built-ins, and `tools: []` removes every built-in while leaving MCP tools unaffected. code.claude.com › overview
- .mcp.json
- The project-scope MCP configuration file in the repository root. It is checked into version control and shared with every teammate, which is why credentials belong in `${VAR}` references rather than literal values. code.claude.com › mcp
- ~/.claude.json
- The personal, non-version-controlled file storing both local-scoped MCP servers (nested under the project's path) and user-scoped ones. It is a different thing entirely from `.claude/settings.local.json`, which holds local settings inside the project directory. code.claude.com › mcp
- 2KB description limit
- Claude Code truncates tool descriptions and MCP server instructions at 2KB each. Keep them concise and put critical details — especially boundary statements — near the start, or they may never reach the model. code.claude.com › mcp
- Access failure vs valid empty result
- An access failure means the tool could not reach the data source, so it is `isError: true` and a retry candidate. A valid empty result means the tool reached the source and found nothing, so it is `isError: false` with `resultCount: 0` and is the answer, not a failure. Confusing the two causes wasted retries and wrong escalations.
- Agent tool
- The built-in tool that spawns subagents, renamed from `Task` in Claude Code v2.1.63 and emitted as `Agent` in `tool_use` blocks. Include `Agent` in `allowedTools` to auto-approve subagent invocations without a permission prompt. code.claude.com › subagents
- Bash prefix matching
- Bash permission rules match on a command prefix, and the trailing space is load-bearing: `Bash(git diff *)` matches any command starting with `git diff`, whereas `Bash(git diff*)` would also wrongly match `git diff-index`. code.claude.com › permissions
- Bloated tool sets
- Anthropic's named failure mode: tool sets covering too much functionality or creating ambiguous decision points about which tool to use. Each extra overlapping tool costs both decision complexity and context budget, making tool scoping a context-engineering discipline as well as a routing one. anthropic.com › effective-context-engineering-for-ai-agents
- Build-vs-use decision
- Evaluate maintained community MCP servers first for standard integrations such as Jira, GitHub, Slack, Linear, or Notion; build a custom server only for team-specific workflows, custom business logic in the tool layer, or proprietary internal systems with no community equivalent.
- Built-in tools
- The tools Claude Code ships with. This task statement names six — Read, Write, Edit, Bash, Grep, Glob — while the documented roster is larger: `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent`, "and others". code.claude.com › overview
- claude mcp add
- The CLI command with two shapes: `claude mcp add --transport http <name> <url>` for a remote server, and `claude mcp add [options] <name> -- <command> [args...]` for a local stdio server, where the `--` separator is required so everything after it reaches the server process untouched. `claude mcp add-json <name> '<json>'` adds one from a JSON blob. code.claude.com › mcp
- Constrained tool alternative
- Least privilege applied to tool design: give a subagent `load_document`, which validates document URLs only, rather than a generic `fetch_url`. The narrower tool prevents misuse, clarifies purpose, and reduces unintended side effects.
- disable_parallel_tool_use
- The boolean that restricts Claude to a single tool call per response. It lives **inside** the `tool_choice` object, not at the top level: with `auto` it means at most one tool call, with `any` or `tool` exactly one. platform.claude.com › parallel-tool-use
- disallowed_tools
- The deny lever with two distinct forms: a bare entry such as `"Bash"` removes the tool definition from the request entirely so Claude cannot see or attempt it, while a scoped entry such as `"Bash(rm *)"` keeps the tool visible and denies only matching calls, in every permission mode. code.claude.com › permissions
- Edit
- The built-in tool for targeted file modification via a unique `old_string` match. It fails when the anchor text is not unique — a safety mechanism, not a bug — and Read + Write is the last-resort fallback only when the anchor cannot be disambiguated.
- Forced tool_choice and extended thinking
- Manual extended thinking (`thinking: {type: "enabled"}`) supports only `tool_choice` `auto` and `none`; `any` and `tool` return an error. Adaptive thinking, including on models where thinking is on by default, does support forced tool use. platform.claude.com › define-tools
- Forced-selection prefill
- With `tool_choice` set to `any` or `tool`, the API prefills the assistant message to force a tool call, so the model emits no natural-language response or explanation before the `tool_use` blocks even if explicitly asked. Any field logging Claude's pre-call reasoning will be empty. platform.claude.com › define-tools
- Four error categories
- Every tool failure falls into one of four categories, each with its own recovery: transient (timeouts, unavailability, rate limits — retry after a delay), validation (bad input format or missing fields — fix the input and retry), business (policy violations and limit exceedances — never retry, escalate or take an alternative workflow), and permission (access denied or insufficient credentials — escalate or use different credentials).
- Glob
- The built-in tool that matches file **paths** by naming pattern, such as `**/*.test.tsx` or `**/config.*`. It finds files by their names; it cannot find what files contain.
- Grep
- The built-in tool that searches file **contents** for patterns — function callers, error messages, import statements. It is the right tool whenever you are looking for what is inside files.
- Incremental discovery
- The documented exploration order: Grep for entry points, Read to trace flows and follow imports, Grep again for wrapper or barrel names, and Read only what the previous step justified. Reading every file up front is the costliest exploration mistake.
- input_schema
- The JSON Schema object on a Messages API tool definition that describes the tool's expected parameters. It is one of three required client-tool fields alongside `name` and `description`, with `input_examples` optional. platform.claude.com › define-tools
- is_error
- The optional boolean on a `tool_result` block that signals a client-tool execution failure; return the error text as `content` with `"is_error": true` and Claude incorporates it into its response. Server-tool errors are handled transparently by Anthropic's infrastructure and are not your responsibility. platform.claude.com › handle-tool-calls
- isError
- The MCP flag returned inside an otherwise-successful tool result to signal that tool execution failed, so the model reasons about recovery instead of treating the text as a normal result. It maps directly onto `is_error` in a Messages API `tool_result` and `mcp_tool_result`. modelcontextprotocol.io › tools
- isRetryable
- The structured error field answering one question: can a retry ever succeed? It is `true` for transient and validation errors and `false` for business and permission errors. Read it first, then read `errorCategory` to learn how — resend, self-correct, escalate, or take an alternative route.
- Local recovery with selective propagation
- The multi-agent error pattern: subagents retry transient failures themselves, propagate only what they cannot resolve, and include partial results plus what was attempted. It prevents both silent suppression and terminating a whole workflow on one failure.
- Malformed-call retry
- Claude's own model-level behaviour: when its tool call is invalid or missing required parameters, it retries 2-3 times with corrections before apologising to the user. This is a separate mechanism from `isRetryable`, which applies after your tool has run and failed. platform.claude.com › handle-tool-calls
- MAX_MCP_OUTPUT_TOKENS
- The setting that raises Claude Code's MCP tool output ceiling. By default Claude Code warns above 10,000 tokens of tool output and caps it at 25,000. code.claude.com › mcp
- MCP (Model Context Protocol)
- The protocol by which servers extend Claude's capabilities with external systems — databases, APIs, development tools, issue trackers — exposing tools, resources, and prompts. All tools from all configured servers are discovered at connection time and available simultaneously, with no manual activation step. code.claude.com › mcp
- MCP annotations
- Optional properties describing tool behaviour, used to disclose which tools need open-world access or make destructive changes. The spec warns that clients MUST treat annotations as untrusted unless they come from trusted servers. modelcontextprotocol.io › tools
- MCP environment variable expansion
- `.mcp.json` supports `${VAR}`, which expands to the environment variable's value, and `${VAR:-default}`, which falls back when unset. Expansion works in `command`, `args`, `env`, `url`, and `headers`, keeping credentials out of version control. code.claude.com › mcp
- MCP error mechanisms
- MCP separates two channels: protocol errors, which are standard JSON-RPC errors for unknown tools, invalid arguments, and server faults; and tool execution errors, reported inside a successful result with `isError: true`. All four error categories are tool execution errors, never protocol errors. modelcontextprotocol.io › tools
- MCP human-in-the-loop principle
- The specification's guidance that there SHOULD always be a human in the loop with the ability to deny tool invocations. It is the protocol-level reason permission errors are treated as escalate-only rather than something to route around. modelcontextprotocol.io › tools
- MCP prompt slash command
- A prompt exposed by a connected MCP server becomes a slash command in the form `/mcp__servername__promptname`, taking space-separated arguments; its result is injected directly into the conversation. code.claude.com › mcp
- MCP resources
- Content catalogues an MCP server exposes so an agent knows what data exists without exploratory tool calls — issue summaries, documentation hierarchies, database schemas. Reference one with `@server:protocol://resource/path` and it is fetched and attached automatically. Resources show what data is available; tools act on it. code.claude.com › mcp
- MCP scope precedence
- When a server name appears at more than one scope, Claude Code uses the whole entry from the highest-precedence source and does not merge fields: local, then project, then user, then plugin-provided servers, then claude.ai connectors. code.claude.com › mcp
- MCP server management commands
- `claude mcp list`, `claude mcp get <name>`, and `claude mcp remove <name>` manage configured servers; `/mcp` checks status in-session and starts OAuth 2.0 authentication for remote servers (as does `claude mcp login <name>`), with tokens stored and refreshed automatically. Project-scoped servers are approved before first use, cleared with `claude mcp reset-project-choices`. `claude mcp serve` runs Claude Code itself as a stdio MCP server. code.claude.com › mcp
- MCP server scopes
- Three scopes, not two: local (the default — current project only, private, stored in `~/.claude.json` under that project's path), project (team-shared via `.mcp.json`), and user (all your projects, private, in `~/.claude.json`). Older versions called local "project" and user "global". code.claude.com › mcp
- MCP tool definition
- An MCP tool carries `name`, `description`, and `inputSchema`, plus optional `title`, `outputSchema`, and `annotations`. Clients discover tools with `tools/list` and execute them with `tools/call`. Where the Messages API constrains only the input, MCP lets you pin the output structure too. modelcontextprotocol.io › tools
- MCP transports
- The specification defines two standard transports: stdio, where the client launches the server as a subprocess and exchanges JSON-RPC over stdin/stdout (clients SHOULD support it wherever possible), and Streamable HTTP, for servers running independently and serving multiple clients over HTTP POST/GET with optional SSE streaming. The standalone SSE transport is deprecated in Claude Code, and `streamable-http` is a configuration alias for `http`. modelcontextprotocol.io › transports
- mcp__ naming pattern
- MCP tools are addressed as `mcp__<server-name>__<tool-name>` — for example `mcp__github__list_issues`. Permission rules can target a whole server (`mcp__server`), every tool on it (`mcp__server__*`), or a single tool (`mcp__server__tool`). code.claude.com › permissions
- Mistake-proofing the schema
- Designing the tool interface so the error is impossible rather than merely discouraged: naming parameters unambiguously (`user_id`, not `user`) and, in Anthropic's own example, always requiring absolute filepaths so relative-path errors disappear entirely. anthropic.com › writing-tools-for-agents
- Optimal tools per agent
- 4-5 tools, scoped to the agent's role. Selection reliability degrades as the toolkit grows — 18 tools on one agent is the exam's illustration — and relevance matters as much as count: a synthesis agent given web search will run its own searches instead of using results already handed to it.
- outputSchema
- The optional MCP field declaring the expected output structure. Once declared, the server MUST provide structured results conforming to it and the client SHOULD validate against it — which is how you guarantee every error response actually carries its error fields. modelcontextprotocol.io › tools
- Parallel tool use
- Claude may call several tools in a single response, and Claude 4 and later do so by default when it helps. Return one `tool_result` per `tool_use` block, all in one user message with no text before them; splitting results across messages teaches the model to stop calling tools in parallel. platform.claude.com › parallel-tool-use
- replace_all
- The Edit option that replaces every occurrence of a non-unique `old_string`. Together with widening the anchor, it is the documented response to a non-unique match — jumping straight to Read + Write burns a file's worth of tokens on a one-line change.
- Scoped cross-role tool
- A constrained version of another role's capability given directly to the agent that needs it, so the high-frequency simple case is handled locally while complex cases still route through the coordinator. It avoids the 2-3 round trips a coordinator hop would add to every request.
- structuredContent
- The MCP result field carrying a JSON object of structured tool output, the first-class place for fields such as `errorCategory` and `isRetryable`. For backwards compatibility, serialise the same JSON into a text block alongside it. modelcontextprotocol.io › tools
- Task tool
- The exam guide's name for the mechanism a coordinator uses to spawn subagents; `"Task"` must appear in the coordinator's `allowedTools` or it cannot invoke subagents at all. Current Claude Code renamed it `Agent`, though `Task` still appears in the `system:init` tools list. code.claude.com › subagents
- Tool description
- The free-text field on a tool definition and the primary mechanism an LLM uses for tool selection — Anthropic calls it by far the most important factor in tool performance. A production-grade one states what the tool does, its inputs with formats, example queries, edge cases and limits, and explicit boundaries against similar tools. When misrouting occurs, expanding descriptions is the first fix. platform.claude.com › define-tools
- Tool misrouting
- The failure where two tools with overlapping or near-identical descriptions cause the model to select the wrong one — for example routing an order query to `get_customer`. The root cause is description quality, not model capability.
- Tool name regex
- A Messages API tool `name` must match `^[a-zA-Z0-9_-]{1,64}$`. platform.claude.com › define-tools
- Tool namespacing
- Delineating tools that must coexist by prefixing or suffixing them, either by service (`asana_search`, `jira_search`) or by resource (`asana_projects_search`). Anthropic found the choice between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations. anthropic.com › writing-tools-for-agents
- Tool search
- The Claude Code behaviour, enabled by default, that defers MCP tool definitions rather than loading them all into context up front; Claude searches for relevant tools and only those it uses enter context. Because the search is text-driven, server instructions should describe what category of tasks the tools handle. code.claude.com › mcp
- Tool splitting
- Replacing a generic tool with broad responsibilities (`analyze_document`) with purpose-specific tools that each have one narrow job and a defined input/output contract (`extract_data_points`, `summarize_content`, `verify_claim_against_source`).
- tool_choice
- The parameter controlling how the model interacts with tools, with four documented types: `auto` (model decides; default when `tools` are provided), `any` (must call some tool, chooses which), `tool` (must call the named tool), and `none` (may not call any tool; default when no `tools` are provided). platform.claude.com › messages
- tool_choice and prompt caching
- Changing `tool_choice` between turns invalidates cached message blocks; tool definitions and system prompts stay cached but message content must be reprocessed. It is the hidden cost of a forced-then-auto workflow. platform.claude.com › define-tools
- tool_result block
- The block that returns a tool's output to Claude, carrying `tool_use_id` (matching the request's `id`), optional `content`, and optional `is_error`. It is sent in a **user**-role message — there is no `tool` or `function` role in the Messages API. platform.claude.com › handle-tool-calls
- tool_use block
- The assistant-role content block in which Claude requests a tool call. It carries three fields: `id` (unique, used to match the result later), `name`, and `input` conforming to the tool's `input_schema`. platform.claude.com › handle-tool-calls
- tool_use_id
- The field on a `tool_result` block that matches it to the `id` of the originating `tool_use` block. Results are matched by this ID, which is what makes parallel tool calls in one iteration unambiguous. platform.claude.com › handle-tool-calls
- WebFetch domain rule
- WebFetch uses its own permission-rule shape, a `domain:` prefix matched against the hostname. `WebFetch(domain:example.com)` matches that host; `WebFetch(domain:*.example.com)` matches subdomains at any depth but not the apex domain. code.claude.com › permissions
- Workflow tools
- Tools built around a high-impact user workflow rather than wrapping an API endpoint — `schedule_event` instead of `list_users`/`list_events`/`create_event`, `get_customer_context` instead of three separate lookups, `search_logs` instead of `read_logs`. Merely wrapping existing endpoints is a named common error. anthropic.com › writing-tools-for-agents