Your Agent's Tool Layer Is a Public API. Design It Like One.
The first agent I put in front of real users had eleven tools and a system prompt that said "ask for confirmation before doing anything destructive." It worked in staging for six weeks. On day two in production it issued the same refund three times because the payment API returned a 502, the model decided to retry, and my wrapper happily forwarded the retry. Nothing about that failure was an LLM…
The success of an agent lies in its tool layer, which should be designed like a public API. This includes considerations for versioning, timeouts, idempotency, scoped credentials, and rate limits. However, the crucial difference is that the caller for an agent is adversarial by accident, not by intent. Therefore, tools should be classified based on their side effects rather than their domain.
When classifying tools, they can be categorized as read (no external state change), write (creates or mutates state, but can be made idempotent), or destructive (deletes, revokes, sends to a human, moves money). Idempotent keys belong to the caller, not the tool. Failure to classify a tool correctly into one of these three categories indicates a lack of understanding and the tool should not be exposed.
To ensure idempotency, derive keys yourself from the run and arguments, and pass them downstream. This approach applies the principles of a public API to the tool layer, ensuring robustness and predictability in the agent's interactions.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.