Agent Interface Design

Agent interface design

Examples teach one path and quietly fence off the others: shown three ways to call a tool, a model tends to produce those three. A well-designed interface teaches the whole space at once. The parameters say what is possible, the description says what is expected, and there is very little left to write.

Steps

• Find out how the tool is actually being misused before redesigning it. Read transcripts, logs, or the user's complaint. Misuse is an interface symptom first and a documentation symptom second, and the fix is usually a rename or a type, not a paragraph.
• Push meaning into the parameters:
• Enumerate instead of accepting free text. A status of pending | in_progress | completed teaches the whole state machine without a sentence of prose.
• Name for intent rather than implementation, so the right call is the one that reads correctly.
• Make invalid states unrepresentable wherever the type system allows it. A parameter that cannot express a mistake needs no warning about that mistake.
• Put behavioral instruction in the tool's own description, at the point of use, and only there. The same guidance restated in a global preamble is how a codebase grows contradictions.
• Treat the urge to add a usage example as a diagnostic: it usually means a parameter is underspecified. Fix the interface first. Keep an example only for a format that genuinely cannot be guessed, such as a bespoke query syntax.
• Decide what is resident and what is discoverable. Tools needed on most turns belong in context; tools needed rarely should be findable on demand so they cost nothing until they're wanted.
• Finish by naming the mistake the design still permits, and say whether it is cheap enough to live with or needs an explicit guardrail.

Guardrails

• A description that has to explain what a parameter means is a parameter that needs a better name.
• Irreversible and high-stakes operations are the exception to all of the above: there, explicit constraint and confirmation beat elegance.
• Never redesign a signature without first finding every existing caller.
• Terseness is not the goal; expressiveness is. Cutting a description that carried real behavior is a worse outcome than a description that ran long.