Designing tool inputs and outputs
The cluster of design rules the exam tests most heavily.
6 min read · Lesson 4 of 10 in this domain
Most tool-design rules on this exam come from one principle: the model reasons over text, so give it text that is unambiguous and stable. Natural-language keys like a team nickname or a loosely formatted date are ambiguous by construction, so separate discovery from mutation — one tool resolves messy input to an id, and the mutating tool accepts only that id. Bounded value sets belong in enums so resolution happens before execution rather than after a failed call. And outputs should carry what the next call needs: identifiers, not URLs; a total count and cursor, not a silent truncation.
- Machine identifiers over natural language. Ambiguous attributes (team nicknames, free-text dates) fail. Separate discovery from mutation: a lookup tool resolves messy input to an unambiguous id, and the mutating tool accepts only that id.
- Enums over freeform strings for bounded value sets. An enum makes the model map natural language to an exact backend value before execution, rather than failing at runtime or fuzzy-matching downstream.
- Return structured data for chaining. If downstream tools need a
document_id, return it explicitly — not a URL, not prose, not a title. - Pagination with metadata. Return the first page plus total count and a cursor, so the agent knows whether more exists. Silent truncation is dangerous: the agent cannot distinguish a complete set from a truncated one.
- Normalise heterogeneous outputs. Multiple carrier APIs with different shapes should be normalised into one schema by code, not translated by prompt instructions.
- Remove needless hops. If a tool exists only to convert an id to a string that the next tool needs, internalise that lookup — it removes a round trip, its tokens, and its failure mode.
Silent truncation is worse than an error. A search tool returns thousands of rows, so you cap it at the top five to protect the context window. The agent receives five results with nothing to indicate more exist, concludes it has seen everything, and confidently reports that only five records match. No error is raised and the answer is wrong. Returning the same five alongside total: 1,240 and a cursor costs a few tokens and turns a false conclusion into an informed decision about whether to page further.
"Silently cap at the top five results" — the agent then reasons as if it saw everything.
A search tool feeds share_document(document_id). What should it return?
Downstream tools need machine-usable identifiers, not strings to parse.
Results are too many for the context window. Best design?
Silent truncation is indistinguishable from a complete result set, so the agent reasons as if it saw everything.
Practise this domain with 18%%-weighted questions in the study app.
Open in study appSource: Claude Docs — Tool use overview · Independent study aid, not affiliated with or endorsed by Anthropic.