Tools and MCPs

Tools and MCPs carries 10.6% of CCDV-F, about six items of 53. That is more than Security and Safety and several times Claude Code, but it is a third of what Applications and Integration is worth, so give it an evening rather than a week, and spend that evening on mechanics instead of philosophy.

The items are implementation items. Expect to be shown a tool definition and asked why the model never calls it, shown a broken turn sequence and asked what the API rejects, asked how a failing tool should report back, or asked which MCP primitive fits a given piece of context. Being able to name the parts of an MCP server, the two transports and the discovery handshake covers most of the protocol questions.

The idea that unlocks the domain: a tool is a prompt with a schema attached, and the loop is strictly turn-based. Claude never executes anything. It emits a tool_use block, your code runs the work, and you send a tool_result carrying the matching tool_use_id in the next user turn. Errors are results, not exceptions. Everything else here is a variation on that one cycle.

• A custom tool is three things: name, a description, and an input_schema that is a JSON Schema object with properties and required. Everything else is your code.
• The description is the highest-leverage field in the whole domain. Say what the tool does, when to use it, what it returns, and what it must not be used for. Three or four sentences beats three words.
• Tool definitions are sent as input tokens on every request. Ship a few well-described tools, not a catalog of thin ones.
• Constrain inputs in the schema: types, enum for closed sets, required for what you cannot default. A loose schema is an invitation for the model to invent arguments.
• The cycle: you send tools with the request, Claude returns stop_reason of tool_use plus a tool_use block holding id, name and input, your code executes it, and you continue the conversation.
• Append the assistant's tool-use turn to the message history verbatim, then add a user message whose content includes a tool_result block with tool_use_id set to that block's id.
• Every tool_use in a turn must be answered. Put all the tool_result blocks in a single user message, before any other content in that message.
• Use tool choice to steer: let Claude decide, force it to call some tool, force one named tool, or turn tools off. Forcing a named tool is the standard trick for guaranteed structured output.
• Parallel calls arrive as several tool_use blocks in one assistant turn. Execute them concurrently when they are side-effect free, and return every result together in the next user message. The tool-choice object carries a flag to switch parallel use off when ordering matters.
• Prefer a built-in tool over a hand-rolled one. Server-side built-ins such as web search run on Anthropic's infrastructure and need no client implementation; custom tools and client-executed built-ins always run in your process.
• Keep looping request and result until stop_reason is end_turn, and enforce your own iteration ceiling so a stuck agent stops.
• MCP is a client and server protocol over JSON-RPC. A server offers tools the model calls, resources the application supplies as URI-addressed context, and prompts the user invokes as templates; a client discovers all three with list calls after the initialize handshake.

• A tool_use with no matching tool_result, or a tool_result whose tool_use_id matches nothing, is a malformed conversation and the API rejects the request. Never quietly skip a tool you failed to run.
• Never let a tool exception escape into your loop. Catch it and return a tool_result marked as an error with a short plain-language reason, so Claude can retry with different arguments or tell the user.
• Word the error so the model can act on it. Say which field was wrong and what was expected, and make clear whether the failure is retryable, such as a timeout or rate limit, or terminal, such as a record that does not exist.
• Error text is model-visible and often user-visible. No stack traces, no secrets, no connection strings, no internal file paths.
• If the response hits the output token limit mid tool call, the input JSON is truncated. Raise the limit or retry; do not try to repair partial JSON. When streaming, accumulate the partial-JSON deltas and parse only once the block is complete.
• Watch for the agent calling the same tool with the same arguments repeatedly. Cap iterations, then return a result that says the loop was cut off rather than silently stopping.
• Fat tool results are the quiet cost killer. Return identifiers and summaries, paginate, and let the model ask for detail instead of dumping a whole payload into context.
• Parallel execution is genuinely concurrent, so writes can interleave. Make handlers idempotent or disable parallel use for tools with side effects.
• Renaming or reshaping a shipped tool breaks everything that referenced it: saved prompts, permission rules, and any client caching the old schema. Add fields optionally, deprecate names, do not repurpose them.
• Two MCP servers exposing the same tool name collide unless the client namespaces them by server, which is why MCP tool identifiers in a client are qualified with the server name.
• Transport mismatch is a classic setup failure. A stdio server is a local subprocess the client launches and talks to over standard input and output; a remote server is reached over HTTP. A remote URL configured as a launch command simply never starts.
• Version an MCP server like a package: it reports its name and version and negotiates the protocol version during initialize, capabilities are declared up front, and changes to the tool list should be announced with a change notification rather than swapped in silently.

MEDIATE — a tool mediates between the model and your systems, in this order.

• M — Match. Match the need to a built-in tool first; define a custom tool only when nothing built in covers it.
• E — Enumerate. Enumerate the contract: name, description, input_schema. The description is the prompt; the schema is the guardrail.
• D — Detect. Send the tools array and detect the reply: stop_reason of tool_use plus a block carrying id, name and input.
• I — Invoke. Your code executes the tool; the API never runs a custom tool for you, and several calls can arrive in one turn.
• A — Answer. Answer with a user message containing a tool_result for every call, each with its matching tool_use_id.
• T — Trap. Trap failures and return them as error-flagged results with an actionable message, never as exceptions, so the model can recover.
• E — Expose. When other clients need the same capability, expose it as an MCP server of tools, resources and prompts over stdio or HTTP, and version it like a library.