Tool Design & MCP Integration

1. 2.1Tool interfaces and descriptionsWrite tool descriptions that state purpose, inputs, examples, edge cases, and boundaries, and rename or split tools so Claude can tell similar ones apart.
2. 2.2Structured error responsesReturn tool failures with the isError flag, an error category, a retryable flag, and a readable message so the agent can retry, fix input, explain policy, or escalate.
3. 2.3Tool distribution and tool_choiceGive each agent only the tools its role needs, swap generic tools for constrained ones, and use tool_choice to require or force a tool call.
4. 2.4MCP servers in Claude Code and agentsConfigure shared servers in .mcp.json and personal ones in ~/.claude.json, reference secrets through environment variables, and expose catalogs as resources.
5. 2.5Built-in toolsPick Grep for file contents, Glob for file paths, Read and Write for whole files, and Edit for unique-text changes, exploring codebases incrementally from entry points.

• Fix wrong tool choices by improving the descriptions first: purpose, inputs, an example, edge cases and when not to use it.
• Split a tool that does too many things, and rename tools that are easy to confuse.
• Return failures with isError plus a category, whether to retry, and a readable message.
• Give each agent only the tools its role needs; a long tool list makes selection worse.
• Use tool_choice to force a specific first call, or "any" to require some tool call.
• Put team MCP servers in the project's .mcp.json, personal ones in user config, and secrets in environment variables.
• Expose browsable catalogs as MCP resources and actions as MCP tools.
• Search file contents with Grep, find files by name with Glob, and change unique text with Edit.

• Adding few-shot examples or a routing classifier before fixing a one-line tool description.
• Returning an empty success when a lookup actually failed.
• Ending the whole workflow on one transient error that a retry would fix.
• Handing every agent every tool "just in case".
• Literal API keys in a shared .mcp.json file.

You get 4 of the 6 scenarios at random, so practice this domain in each of them. All six scenarios.

1. Write two similar tools, test them with ambiguous requests, then rewrite the descriptions until selection is reliable.
2. Make one tool return each error type: transient, invalid input, business rule and permission.
3. Configure a project MCP server with an environment variable for its key and check it loads for a teammate.
4. Explore an unfamiliar repo using only Grep, Glob and Read, starting from an entry point.