The reading room · Digna Legi
Your Agent Isn't Dumb. Your Tools Are.
/100
80–100: high value. 70–79: worth the time. Below 70: below the usual publication threshold.
Evidence-reviewed score based on available publisher text. The evidence appears to contain the full text, though it also includes some sponsor and promotional sections.
Scores reflect one reader’s profile, not an objective quality rating. Best is a separate personal selection.
How scoring works →This brief · about 3 min with detail
Why read this
Agent failures blamed on prompts may actually come from vague tool contracts that force guessing before execution.
AI brief · Checked against source text
The main idea
The central claim is that many agent failures blamed on prompts are really API-design failures in tool definitions. Because the model sees names, descriptions, schemas, examples, and returned errors rather than source code, each tool contract becomes the behavioral surface: narrow tools, typed inputs, bounded outputs, and actionable errors reduce guessing before execution.
Some background helpful. Basic familiarity with APIs, schemas, and AI agent tool calling.
Go a little deeper
Descriptions should route, not merely describe
The author’s useful distinction is that a tool description is not passive documentation. It is selection guidance for a model choosing among neighboring options. A good description says what the tool does, when it should win, when it should not be used, and which alternative handles that excluded case. That negative boundary is treated as a design test: if two tools cannot state non-overlapping exclusions, their responsibilities are probably muddled.
Schemas move correction earlier
Strict parameter schemas do more than reject invalid calls after the fact. They shape the model’s choice space before the call is made: enums show allowed values, forbidden extra fields close off improvisation, and examples cover constraints that types cannot express, such as paired fields or identifier formats. The author’s mechanism is cost avoidance: fewer parse failures, retries, and token-consuming repairs because bad options are less available at selection time.
Returns are part of the dialogue
Tool output is not just application plumbing; it becomes the model’s next input. That makes vague failures actively harmful: a stack trace or bare error flag gives the model no usable next move. The proposed pattern is a typed error code, a plain explanation, and retry guidance, so deterministic systems can count failure modes while the model receives enough information to choose a different valid action.
Tool count is an accuracy and context cost
The piece treats tool sprawl like dependency sprawl: every available tool becomes another candidate to compare and another chunk of prompt context. The recommended response is not merely deletion, but active shaping of the tool surface: merge near-duplicates, separate rare admin operations, defer long-tail tools, and use search to load only what matters for the current turn. A wide domain may indicate multiple agents, not one larger toolbox.
A case from the article
A destructive refund should be split before money moves
The source’s clearest safety example is a two-step destructive action. Instead of letting an agent directly execute a refund, a preparation call returns a summary and confirmation token; only a second call with that single-use, short-lived token moves money. The point is not bureaucracy. It creates a reversible checkpoint, limits replay risk, and gives humans or deterministic code a final place to verify the action.
How the case is made
The case is made through practitioner observation, API analogies, concrete expense-tool examples, and cited benchmark figures from Anthropic.
Where the idea has limits
The argument is strongest for agents that choose among external tools; it does not claim prompts are irrelevant, only that tool design is often the overlooked failure point.
A question to take away · from Digna Legi
Where is your agent being asked to decide something deterministic code could decide after a smaller structured choice?
What the original adds
The original gives seven concrete design rules, including strict schemas, negative routing guidance, pagination, idempotency keys, two-step destructive actions, and deferred tool loading with tool search.
About this brief
AI-written, then separately checked for source support, useful detail and clarity. The author’s claims and our editorial question are kept separate. The original remains the author’s work. How we select and summarise →
How was this brief?
Rate this summary, separately from the author’s article.
Optional. Saved in this browser; shared only if you allow analytics.
How was the original article?
Rate the author’s original after reading it.
Optional. Saved in this browser; shared only if you allow analytics.
Digna legi. Worth reading.