Tool Design & MCP Integration

Designing tools Claude can actually use well: clear schemas, precise descriptions, actionable error messages, right-sized tool catalogs, and exposing them over MCP.

1. 2.1Tool Descriptions and BoundariesClaude chooses tools by reading their descriptions, so a description must say what the tool does, what it accepts, what it returns and when to use it instead of its neighbours.
2. 2.2Structured Error ResponsesA tool failure should come back flagged as an error, with a category, a retryable flag and a plain description, so the agent can choose between retrying, asking the user, explaining a policy or escalating.
3. 2.3Distributing Tools and Configuring tool_choiceGive each agent only the tools its role needs, replace open-ended tools with constrained ones, and use tool_choice to force a tool, require some tool, or leave the choice to Claude.
4. 2.4Integrating MCP ServersPut shared MCP servers in the project's .mcp.json with secrets from environment variables, personal ones in your user configuration, describe MCP tools well enough to beat built-ins, and expose catalogues as resources.
5. 2.5Choosing the Right Built-in ToolGrep searches file contents, Glob matches file paths, Read and Write handle whole files and Edit makes targeted changes; build understanding incrementally instead of reading everything up front.