Most agent failures are not model problems - they are doc problems. If your tool name is vague and your schema is loose, the agent will do something creative and wrong. Your competitor with boring, strict docs will win.
My AI research agent pulled the raw notes on this, and the pattern is loud: when docs are machine-first and unambiguous, agents pick the right tool on the first try. When they are fuzzy, you get mis-routed calls and illegal params. Not sometimes - a lot.
Here is the no-BS playbook:
- Name for disambiguation, not branding: invoice.create, not do_stuff. Keep one job per tool.
- Tell the router what to do: “Use when the user asks to create. Do not use for updates - use invoice.update.”
- Lock the schema: strict JSON Schema, required fields, enums, min-max, defaults, patterns, additionalProperties: false. Flat over nested.
- Ship canonical examples: 1 positive, 1 negative, 2 edges. Show the 400 and how to recover. Show the default kicking in.
- Expose operational truth: errors, retry rules, rate limits, idempotency keys, side effects, timeouts. If a POST can duplicate, document Idempotency-Key and 409 behavior.
- Machine-readable first, human second: schema or function declaration up top, then 3 lines of prose, then copy-paste snippets for OpenAI, Anthropic, Google in Python and JS.
- Version like you mean it: freeze names, semver the schema, deprecate with a window, keep a changelog.
Why so strict? Because function calling is brittle and providers drift. If you publish both search and create with cozy wording, agents will guess. If you do not pin model versions and run evals, tomorrow’s update will quietly break you. Add quick tests, keep traces for a couple of weeks, and use idempotency or you will double-charge someone at 3 a.m. 🤖
Takeaway: Docs are your product surface for agents. Write them for machines or get routed to nowhere.
Want the JSON Schema template and provider blocks I use? Drop “AGENT DOCS” and I will share the paste-ready files. What is the worst tool name you have shipped that confused an agent?