StableAI Engineeringtool-design

Tool Design — What the Agent Reaches For

Operationalizes the design of a tool an agent calls. The governing idea: a tool built for a human is not automatically a good tool for an agent. A person calling an API brings a docs tab, a memory of last week, a colleague to ask, and a willingness to read the stack trace; an agent brings a name, a description, a schema, and whatever came back last time. Naming, description, input shape, response shape, and blast-radius limits are therefore not packaging around the real capability — they are the capability, as far as the agent is concerned. A good agent tool reduces ambiguity to the point where the right call is obvious without a trial, and returns enough evidence for the agent to verify the result itself rather than take "OK" on faith.

tool-designagent-toolstool-descriptionsstructured-inputsstructured-outputserror-design

Principios

· Aplica los principios documentados en el pack tool-design.

Patrones

· Verb plus object, always. cancel_subscription beats subscription and beats manage_billing. If the name isn't a verb, the agent has to infer the effect from the description alone.
· Name the effect, not the endpoint. Wrapping POST /v2/records:batchMutate as records_batch_mutate exports your implementation as the agent's vocabulary.
· Read your two most similar names side by side. If you need the descriptions to tell them apart, so will the agent, and it only reads them under time pressure.
· Namespace by source. Three servers each offering search is three ways to be wrong.
· Avoid names that could describe a read or a write. update_index — does it fetch the index or rebuild it? Pick a verb that can only mean one of the two.

Riesgos

· Ver anti-patrones específicos del dominio en el pack.

Checklist

[ ] ★ No tool performs several independently-failing side effects behind one name; effects that must happen together commit atomically. (TDE12, TDE13)
[ ] ★ Partial failure across multiple entities is reported per entity, not collapsed into one aggregate error. (TDE16)
[ ] ★ No tool silently performs a side effect its name and description do not mention. (TDE14)
[ ] ★ Every operation whose scope depends on unseen state exposes a dry-run mode. (TDE51)
[ ] ★ Destructive and irreversible operations require an explicit confirmation parameter with no default. (TDE54)
[ ] ★ Every side-effecting tool is idempotent, accepts an idempotency key, or states that it is not repeat-safe. (TDE45, TDE46, TDE48)

Fuentes

En la bibliografía AKOS

Este pack cita las siguientes fuentes registradas en el índice bibliográfico:

Explorar todas las fuentes →