Most AI agent failures stem from poor tool design, not model limitations. Based on production experience shipping and debugging dozens of agents, the key principles are: use precise verb-object tool names, write descriptions that cover what the tool does, when to use it, when not to use it, and what it returns. Treat JSON schemas as strict contracts using enums, format hints, and min/max constraints. Return structured errors with hint fields so agents can self-correct. Keep tool granularity at the level of one human-recognizable step (8–15 tools is a healthy range). Make mutating tools idempotent, keep auth server-side, and include worked examples in every tool description. Version tool specs like APIs and monitor per-tool call rates. A well-designed tool surface outperforms prompt engineering and survives model upgrades.
Table of contents
The Mental Model: Tools Are A Public API For The ModelNaming Is Most Of The JobDescriptions: Write Like You Are Onboarding A New EngineerParameter Schemas Are A Contract, Not A HintError Returns Are Where The Agent Recovers Or SpinsTool Granularity: The Goldilocks ProblemAuthentication, Idempotency, And The Boring Things That Save YouDocumentation By ExampleVersioning And Change ManagementWhat This Looks Like When It WorksWhere This Is GoingSort: