What MCP is and how to write tools Claude picks correctly

The more tools an agent has available, the more the outcome depends on how they were named and described — not just on the schema. This page explains MCP (Model Context Protocol) and the practices that decide whether Claude picks the right tool or gets it wrong because of ambiguity.

What MCP actually standardizes

MCP is a protocol that standardizes how an agent connects to external sources of data and action. In the protocol's vocabulary, Claude Code acts as the host; tools are model-controlled, meaning the model decides when to call each one; resources are application-controlled; and prompts are user-controlled. Each primitive has a different owner of the decision about when it's used — confusing the three is the most common source of misunderstanding about what MCP does.

That matters in practice: an MCP server can expose all three primitives at once, and not every integration requires the same transport — the choice between running locally and exposing it over remote HTTP depends on where the server runs and who needs to authorize access.

Why two tools with the same name break selection

When the tool library grows across several services, it's common for two different modules of the same agent to expose a tool with an identical name — two `get_user` tools, one from the auth service and another from billing, for example. Claude has to choose between them before it even fills in any parameter, and an identical name gives no information for that choice — selection becomes luck.

The documented fix is naming with a namespace per service: `auth_get_user`, `billing_get_user`. An extra parameter to disambiguate afterward doesn't solve it, because the ambiguity happens a step earlier — at tool selection, not at filling it in — and a prefix solves it without touching any schema.

The description is the main signal channel, not the name

Given an unambiguous name, what most affects whether Claude picks correctly is the description: what the tool does, when to use it, and the exact format of each parameter. A vague description ("manages transactions") leaves the decision to inference; a description that's specific about when to use it reduces that to nearly zero.

The same care applies to the return value: on error, the tool should return `is_error: true` with an actionable message, not generic text. And when several related operations make sense together, consolidating into fewer tools that return only high-signal information tends to work better than a tiny tool for every single operation.

tool_choice: when the choice can't depend on the model

There are moments when the choice can't depend on the model's interpretation — for example, forcing an identity check to happen before any other action. For that, `tool_choice` lets you force a specific named tool on that turn, instead of trusting that the description will be enough.

It's the same pattern from the permissions domain applied to tools: a good description raises the odds of getting it right; a structured API parameter guarantees the behavior when getting it right can't be optional.

Two tool calls in the same turn shouldn't always run in parallel

The Messages API allows Claude to return more than one tool_use block in the same turn, but that doesn't mean the application should execute both calls at the same time. When one operation depends on the other's result, or when both have a side effect on the same resource, running them in parallel can apply one out of order, or apply both even when the first one should have blocked the second.

It's the application's job, not the model's, to decide the real execution order of the tool calls it receives — Claude's role is deciding which ones to call; the role of the code that processes the response is deciding how and when to run them safely.