Tool Design & MCP Integration

Tool descriptions are the primary signal Claude uses to decide which tool to call, so they function as a context-engineering surface, not just documentation. Anthropic's guidance is to write each description the way you'd brief a new hire: make implicit context explicit, and cover what the tool does, when to use it (and when not to), what each parameter means, what it returns, and how it differs from similar tools. The API-side best practice is at least 3-4 sentences per description, with unambiguous parameter names (user_id, not user). For format-sensitive or nested inputs, the Messages API also supports an input_examples array of schema-valid examples that show concrete well-formed calls.

The dominant failure mode is overlapping or vague descriptions. If analyze_content and analyze_document have near-identical descriptions, Claude misroutes between them; if a human engineer can't definitively pick the right tool, the agent can't either. Two remedies: (1) rename and rewrite to eliminate overlap — e.g., rename analyze_content to extract_web_results with a web-specific description and clear input/output contract; (2) split an overloaded generic tool into purpose-specific tools with defined contracts — e.g., split a catch-all analyze_document into extract_data_points, summarize_content, and verify_claim_against_source. Meaningful namespacing (service- and resource-prefixed names like asana_search vs jira_search, or asana_projects_search vs asana_users_search) further disambiguates selection as the library grows.

System-prompt wording interacts with tool selection. Keyword-sensitive instructions can create unintended tool associations that override otherwise well-written descriptions — for example, a system prompt that keeps saying 'search the documents' can bias Claude toward a tool whose name contains 'search' even when a better tool exists. So reviewing the system prompt for keyword bias is part of tool-interface design. Anthropic notes that precise refinements to tool descriptions alone produced state-of-the-art SWE-bench results by sharply reducing error rates — evidence that description quality, not just code, drives reliability.

MCP tools report failures in two distinct channels, and choosing the right one determines whether the agent can recover. Protocol errors are standard JSON-RPC error objects (code/message) used for issues like an unknown tool name or invalid arguments; the MCP client typically captures and discards these, so the model never sees them and cannot react. Tool execution errors are returned as a successful JSON-RPC result whose payload sets isError: true alongside content describing the failure. Because an isError result is injected back into the model's context just like a normal result, the model can read it and decide what to do next. The rule of thumb: anything you want the agent to recover from or explain to the user (API failures, invalid input data, business-logic violations) belongs in an isError result, not a protocol error.

Uniform errors are the core anti-pattern. A generic 'Operation failed' gives the agent no basis to pick a recovery path, so it may retry a non-retryable failure, give up on a transient one, or surface a confusing message. The fix is structured error metadata: classify the failure (errorCategory: transient | validation | business | permission), include an isRetryable / retriable boolean, and provide a human-readable, customer-friendly explanation. Transient errors (timeouts, service unavailable) are retryable; validation, permission, and business-rule violations generally are not, and marking them retriable: false prevents wasted retry loops. For business-rule violations, a clear customer-facing message lets the agent communicate appropriately instead of looping.

In multi-agent designs, recover locally where possible: a subagent should handle transient failures itself (e.g., retry with backoff) and only propagate to the coordinator the errors it cannot resolve locally — and when it does, it should pass along partial results and what it already attempted, so the coordinator doesn't redo work. Finally, distinguish access failures from valid empty results: a query that legitimately matches nothing is a SUCCESS that returns an empty set, not an error. Returning isError: true for zero matches mislabels a successful query and triggers pointless retries.

How tools are distributed across agents is as important as how they're described. Giving one agent too many tools (e.g., 18 instead of a focused 4-5) increases decision complexity and degrades selection reliability, because each extra tool is another option Claude must weigh on every turn. Agents also tend to misuse tools outside their specialization — a synthesis agent handed web-search tools will attempt searches it shouldn't. The remedy is scoped tool access: give each subagent only the tools its role needs, plus a small number of constrained cross-role tools for specific high-frequency needs, and route complex cases back through the coordinator.

In the Claude Agent SDK and Claude Code, you scope tools per subagent with the AgentDefinition tools field (an allowlist) and optionally disallowedTools (a denylist; when both are set, disallowedTools wins). Omitting tools makes the subagent inherit all parent tools — convenient but the opposite of scoping. Common role bundles: read-only analysis = [Read, Grep, Glob]; test execution = [Bash, Read, Grep]; code modification = [Read, Edit, Write, Grep, Glob]. Prefer constrained alternatives over generic capabilities: replace a broad fetch_url with a load_document tool that validates document URLs, so the agent can't wander the open web. For a synthesis agent that occasionally needs to check a fact, give it a single scoped verify_fact tool rather than a general search tool, and send anything more complex through the coordinator.

tool_choice (Messages API) controls whether and which tool Claude calls on a turn. The four options: {"type":"auto"} (default — Claude decides whether to call a tool), {"type":"any"} (must call some tool, model picks which), {"type":"tool","name":"..."} (force a specific tool), and {"type":"none"} (no tools). Use forced selection to guarantee an ordering — e.g., force extract_metadata first, then let enrichment tools run on follow-up turns. Use any when you need a guaranteed tool call rather than conversational text. Note: with any or tool, the API prefills the assistant turn, so Claude emits no natural-language preamble before the tool_use block; and any/tool are incompatible with extended thinking.

Claude Code connects to external tools through MCP servers, and where you configure a server determines who can use it. There are three scopes: local (the default) is stored under your project's entry in ~/.claude.json and stays private to you in that one project; project is stored in a .mcp.json file at the repository root and is meant to be committed so the whole team gets the same tooling; user is stored in ~/.claude.json and loads across all your projects but stays private to you. Use project scope for shared team integrations and user/local scope for personal or experimental servers. Project-scoped servers from .mcp.json require your approval before first use, for security.

.mcp.json supports environment-variable expansion so secrets never get committed: ${VAR} expands to the variable's value and ${VAR:-default} supplies a fallback. Expansion works in the command, args, env, url, and headers fields — so you can write "Authorization": "Bearer ${GITHUB_TOKEN}" and keep the token in your shell environment. If a referenced variable is unset and has no default, Claude Code fails to parse the config.

At connection time Claude Code discovers the tools (and prompts and resources) from every configured server, and they're all available simultaneously; servers also support list_changed notifications to update their offerings live. Because Claude can fall back to built-in tools (like Grep) when an MCP tool's purpose is unclear, enhance each MCP tool's description to spell out its capabilities and outputs so Claude prefers the more capable MCP tool. For standard integrations (Jira, GitHub, Sentry), prefer an existing community/Directory MCP server over a custom build, and reserve custom servers for team-specific workflows. Finally, MCP resources expose content catalogs — issue summaries, documentation hierarchies, database schemas — that the agent can reference (via @server:protocol://path mentions in Claude Code) to gain visibility into available data without burning turns on exploratory tool calls.

Claude Code's built-in tools each have a precise job, and choosing the right one is a core architecture skill. Grep searches file contents for patterns — function names, error-message strings, import statements — and is built on ripgrep, so it uses ripgrep regex (escape metacharacters; interface{} becomes interface{}), respects .gitignore by default, and supports output modes (files_with_matches default, content, count) plus glob/type scoping. Glob, by contrast, matches file paths by name pattern (/*.test.tsx, src//*.ts), returns up to 100 files sorted by modification time, and does not respect .gitignore by default. The mnemonic: Grep finds files by what's inside; Glob finds files by their name.

Read loads full file contents (with line numbers; always pass absolute paths) and also handles images, PDFs, and notebooks. Write creates a new file or completely overwrites an existing one (it does not append or merge), and overwriting an already-existing file requires having Read it first in the session. Edit performs targeted, exact string replacement: it takes old_string and new_string, uses no regex or fuzzy matching, and requires that the file was Read first, that old_string matches exactly (whitespace included), and that old_string is unique in the file. When old_string isn't unique, Edit fails — the fixes are to supply a longer string with enough surrounding context to pin one occurrence, set replace_all: true to change them all, or fall back to Read + Write to rewrite the whole file reliably.

The skill the exam tests most is incremental codebase understanding: don't read every file upfront. Start with Grep to find entry points (a route registration, a CLI main, an error string), then Read those files and follow their imports to trace flows on demand. To trace how a function is used across wrapper modules, first identify all the exported names (the wrappers may re-export under different names), then Grep for each exported name across the codebase to find every caller. This Grep-then-Read-then-follow-imports loop keeps context lean and is the correct pattern versus bulk-reading.