Tool Design & MCP Integration

Tool descriptions are the primary mechanism the model uses to pick a tool. When get_customer says "Retrieves customer information" and lookup_order says "Retrieves order details", and both accept similar identifier formats, misrouting is not a model defect — it is the only outcome the descriptions support.

A good description carries input formats, example queries, edge cases, and an explicit boundary against the tools it could be confused with. Expanding descriptions is the low-effort, high-leverage first move; few-shot examples add token overhead without touching the root cause, and a routing layer throws away the language understanding you are paying for.

Where overlap is genuine rather than merely underdescribed, rename and re-scope. analyze_content and analyze_document with near-identical descriptions is a naming problem: make one extract_web_results with a web-specific description. And a generic analyze_document is often three tools wearing a coat — extract_data_points, summarize_content, verify_claim_against_source, each with a defined contract.

One more place to look: the system prompt. Keyword-sensitive instructions there can create tool associations that override a well-written description.

MCP communicates failure with the isError flag, but the flag alone tells the agent almost nothing. A uniform "Operation failed" leaves it unable to choose between retrying, rephrasing, explaining to the user, or escalating — so it guesses.

Categorise. Transient errors (timeouts, service unavailability) may resolve on retry. Validation errors mean the input was wrong. Business errors mean policy forbade it. Permission errors mean the caller cannot do this at all. Return errorCategory, an isRetryable boolean, and a human-readable description, and the agent's next move becomes derivable rather than guessed.

For business rule violations, add retriable: false and a customer-friendly explanation so the agent can communicate the outcome instead of hammering the tool. Inside a subagent, recover from transient failures locally and propagate only what you could not resolve — along with partial results and what was attempted.

Keep one distinction sharp: an access failure is not an empty result. A search that timed out and a search that succeeded and found nothing require opposite responses.

Tool selection reliability degrades as the tool count rises. Eighteen tools where four or five would do is not flexibility, it is decision complexity, and the model pays for it in misrouting. Give each agent the tools its role needs and nothing else — a synthesis agent with web search tools will eventually run a web search.

Where a cross-role need is high-frequency, scope a narrow tool rather than opening the whole set. If 85% of the synthesis agent's verification needs are simple fact-checks, give it verify_fact and keep the complex 15% routing through the coordinator. That is least privilege applied to tools. Similarly, replace an open fetch_url with a load_document that validates document URLs.

tool_choice controls whether and which. "auto" lets the model return text instead of calling anything. "any" forces a tool call but leaves the choice open. Forced selection — {"type": "tool", "name": "extract_metadata"} — pins a specific tool, which is how you guarantee metadata extraction runs before enrichment; the subsequent steps happen in follow-up turns.

Scope decides who gets the server. Project-level .mcp.json is committed and shared with the team; user-level ~/.claude.json is personal and experimental. Credentials go in through environment variable expansion — ${GITHUB_TOKEN} in .mcp.json — so the config is committable and the secret is not.

Tools from every configured server are discovered at connection time and are all available to the agent simultaneously. That makes description quality matter more, not less: an MCP tool with a thin description loses to a built-in like Grep even when it is more capable. Say what it does and what it returns.

MCP resources are the underused half of the protocol. Exposing a content catalogue — issue summaries, documentation hierarchies, database schemas — gives the agent visibility into what exists without a round of exploratory tool calls to find out.

For standard integrations like Jira, prefer an existing community server. Reserve custom servers for workflows that are actually specific to your team.

Grep searches file contents — function names, error messages, import statements. Glob matches file paths — **/*.test.tsx and similar. Read and Write are whole-file operations; Edit makes targeted modifications by matching unique text. When Edit cannot find a unique anchor, Read the file and Write it back rather than fighting the match.

The exam's real interest is exploration strategy. Understanding a codebase is incremental: Grep to find entry points, Read to follow imports and trace flows. Reading every file up front burns context on material you will not need and leaves none for the part you do.

Tracing usage across wrapper modules has a shape worth remembering: identify all exported names first, then search for each name across the codebase. Searching for the original symbol alone misses everything that re-exports it.