AI Agent Tool Design: What Works and What Doesn't(machinelearningmastery.com)

Most-improved-tool advice ignores that the model's own training is the variable. We rewrote a tool's description three times chasing reliability before realizing the issue was passing 40 fields back when the agent needed 6; cutting the response schema fixed what no prompt wording could. Design the payload the agent reads, not just the call it makes.

most of that "30% faster" came from the boilerplate we shouldn't have been writing anyway

most of my agent failures were schema gaps, not prompting

Agents fail loudest when a tool returns a wall of JSON the model has to parse mid-reasoning. We cut our internal agent's error rate by maybe a third just by having each tool return a short natural-language summary plus the raw payload behind a key it only fetches when needed.

Our "agent" started as one Python script with five tools. The retrieval tool returned 40 chunks per call and the model kept picking the wrong one, so I cut it to 5 and added a one-line description to each tool name. Hallucinated tool calls dropped enough that I stopped manually fixing JSON every afternoon. The boring fix (fewer tools, clearer names) beat the three days I spent trying to prompt-engineer my way around it.

We rolled out an internal agent for our procurement team, 12 people. First build let it call the SAP write API directly and it duplicated three POs in a week. We changed it to draft the PO and drop it in a human approval queue, and the errors went to zero while it still saved each buyer about an hour a day. Read-only by default, writes behind a person, has been the rule that actually stuck.

Spent three weeks building a custom retry-and-tool-router around the Anthropic SDK before realizing half of it vanished once I gave each tool a tighter JSON schema and a one-line "when to use this" description. Bad tool descriptions caused more failed runs for us than model choice ever did. We went from a 9-tool god-agent to four scoped agents and the wrong-tool-call rate dropped from maybe 30% to single digits. The thing nobody tells you: every tool you add makes the other tools harder to pick correctly.

Two clients killed my retainer in March and moved blog drafts to an in-house Claude setup, dropping me from 12 regular accounts to 7. What survives is the work where I sit between the agent and the brand: feeding it the messy interview notes, killing the three confident-but-wrong claims it invents per 1000 words, and rewriting the parts that read like every other agent did them.

Half my "workflow" is now writing prompts that explain why the last prompt failed.

Half my "AI tools" turned out to be a chatbot that confidently tells eighth graders the Civil War ended in 1875.

Tool descriptions that survive contact with a confused model beat clever ones. We renamed `search_docs` to `find_in_documentation` and cut hallucinated calls on our 12-person team roughly in half.

Which specific tool had the worst schema-to-adoption ratio, and did renaming its parameters actually move usage?

Tool descriptions that survive a handoff beat clever ones. Watched an agent burn six turns retrying a `search_files` call because the error just said "invalid argument" instead of "glob pattern required, got regex" : the model can't recover from feedback it can't read.

Half the tool descriptions I test would confuse a human intern, yet we expect a model to infer the missing preconditions.