Tools and interfaces
Make tools easier to choose and use
For teams that give agents tools, an API or written instructions, and want the agent to pick the right one and use it well.
An agent picks a tool from its name, its description and its schema, and that text is most of what it has to go on. These guides cover writing descriptions an agent can act on, keeping a tool catalogue small enough to choose from, and opening up a very large API without one tool per endpoint. They also cover run views that show a person the next decision, and keeping files like AGENTS.md true as the product changes. Read them if an agent keeps choosing the wrong tool, or calls the right one badly.
The guides, in order
Write tool descriptions an agent can act on
The text around a tool affects whether an agent can find it, choose it, and use it well.
8 min read
Agent tool catalogues need a pruning strategy
A small, clearly separated catalogue is usually easier to choose from than a long list of overlapping actions.
8 min read
An agent dashboard should show the next decision
A run view should tell an operator whether to approve, retry, stop or escalate, and why.
7 min read
How to expose a 3,000-operation API to agents
Seven patterns for large API surfaces: search first, schema on demand, rehearsal, truthful exits, an escape hatch, curated descriptions and a context budget.
14 min read
Keep agent instructions true
How to catch drift between what AGENTS.md, llms.txt, skills and MCP instructions say and what production does.
10 min read
Rules on these topics
Missing description
A tool, operation, command or skill has no description, so an agent has nothing to choose it by.
Does not say when to use it
The description never says when this is the right choice, for example with "Use this when ...".
Does not say when not to use it
The description never says when this is the wrong choice, so near-miss tasks select it too.
Placeholder description
The description is a placeholder such as "TODO", "N/A", "description" or a repeated word like "ai ai".
Description only restates the name
Every meaningful word in the description already appears in the name, so the description adds nothing an agent can use.
No neighbouring tool named
In a catalogue with more than one entry, the description does not name any other entry to use instead.
Evidence on these topics
Skill selection precision collapses as the skill pool grows
A preprint reports that as the pool of available skills grew from 5 to 100, the precision with which agents actually used the right skill fell from 29.6% to 3.3%.
Praise and list order move tool selection
A preregistered preprint with two small OpenAI models found that stacked praise in a tool description raised its pick rate by about 43 percentage points, and that with identical listings the first-listed tool was picked about 72 points more often.
Skill rules that name a command or path change what agents do
A study of 3,159 skills (preprint) found that adding a checkable rule raised the rate at which four coding agents took the required action by +0.23 on average, with the gain coming mainly from rules naming a command or path the old skill did not mention.
An enum in the schema ends silent failures from example-only vocabularies
SilentProbe (preprint) reports that a vocabulary a parameter description only exemplified ("e.g.") was missed on 88 of 88 attempts across twelve models, and that promoting it into the schema cut the failure to 0 of 89.
Hiding tools is not enforcing permissions
Across 2,160 attempts with four frontier models (preprint), a server with only in-body permission checks exposed forbidden tools in 152 of 720 trials and permission-aware visibility cut that to 0 of 720, yet models named a hidden tool in up to 94% of settings when it was inferable from the prompt.
A capable agent skipped the index and guessed the page
A preregistered ablation on a 709-page Markdown wiki (preprint) found that a capable tool-using agent never loaded the compact catalogue index, inferring page paths from the question instead, while retrieval-based access kept answer quality non-inferior and cut cost by about a third to over half.