Tool descriptions are the primary mechanism for tool selection — minimal or overlapping ones misroute. First fix: expand each description with input formats, example queries, edge cases, and boundaries vs. similar tools.

State its purpose, expected inputs, outputs, and when to use it versus similar alternatives — plus input formats, example queries, edge cases, and boundary explanations.

Rename to eliminate overlap (analyze_content → extract_web_results); or split a generic tool into purpose-specific tools with defined I/O contracts (analyze_document → extract_data_points, summarize_content, verify_claim_against_source).

The system prompt. Keyword-sensitive instructions can create unintended tool associations that override even a well-written description. Review and remove that wording.

The isError flag marks the tool result as a failure. A uniform generic "Operation failed" prevents the agent from making appropriate recovery decisions — attach structured metadata instead.

errorCategory (transient / validation / permission), an isRetryable boolean, and a human-readable description. Structured metadata prevents wasted retry attempts.

• transient (timeouts, service unavailable) → retry
• validation (invalid input) → fix input
• business (policy violation) → explain
• permission (access denied) → escalate

With retriable: false plus a customer-friendly explanation, so the agent communicates appropriately — not a raw error and not a pointless retry.

Recover transient failures locally; propagate to the coordinator only errors that can't be resolved locally — with partial results and what was attempted. And distinguish an access failure (needs a retry decision) from a valid empty result (success, no matches).

More tools increase decision complexity and degrade tool selection reliability. Restrict each subagent's tool set to its role to prevent cross-specialization misuse.

An agent given off-role tools tends to misuse them (a synthesis agent attempting web searches). Apply scoped tool access: give each agent only the tools its role needs, with limited cross-role tools for specific high-frequency needs.

Give it a scoped cross-role verify_fact tool for simple lookups, while complex verifications keep routing through the coordinator. Don't hand it all web-search tools.

• "auto" — model decides whether to call a tool
• "any" — must call some tool (no conversational text)
• {"type":"tool","name":"…"} — forces one specific tool

Use forced tool_choice ({"type":"tool","name":"extract_metadata"}) to call it first, then process subsequent steps in follow-up turns. (Also: replace a generic fetch_url with a constrained load_document that validates URLs.)

Shared team tooling → project-level .mcp.json (committed to the repo). Personal/experimental servers → user-level ~/.claude.json.

Use environment-variable expansion in .mcp.json — e.g. ${GITHUB_TOKEN} — instead of committing the literal token.

At connection time — tools from all configured MCP servers are discovered and available to the agent simultaneously.

The MCP tool's description is too thin. Enhance MCP tool descriptions to explain capabilities and outputs in detail so the agent prefers the more capable MCP tool. (And choose a community server, e.g. Jira, over a custom one for standard integrations.)

A mechanism to expose content catalogs — issue summaries, documentation hierarchies, database schemas. They give agents visibility into available data without requiring exploratory tool calls.

Grep searches file contents for patterns (function names, error messages, import statements). Glob matches file paths by name/extension pattern (e.g. **/*.test.tsx).

Read/Write = whole-file operations; Edit = targeted change via unique text match. When the anchor text isn't unique and Edit fails, fall back to Read + Write.

Incrementally: start with Grep to find entry points, then Read to follow imports and trace flows — rather than reading all files upfront.

First identify all the exported names, then Grep each name across the codebase.