DESIGNING GOOD TOOLS

IDEMPOTENCY Idempotency, pronounced eye-dem-POH-ten-see, means a tool can be safely called more than once with the same effect as calling it once. An elevator button is idempotent: pressing the Floor 5 button five times does the same thing as pressing it once. Dropping a coin into a vending machine is not: each coin changes the balance. Why does this matter so much for agents? Because agents retry. A tool call may time out after the work was actually completed, leaving the agent unsure whether it happened. The agent or harness then retries, and a non-idempotent tool performs the work twice: two emails, two charges, two copies of a report. Consider the contrast between "set_status_to_shipped" and "increment_ship_count." Calling set_status_to_shipped twice leaves the order shipped, exactly as before. Calling increment_ship_count twice makes the count wrong. Several techniques make a tool idempotent. Use set operations instead of increment operations, saying "make the value equal to 5" rather than "add 1." Check before writing: look to see whether the thing already exists and skip creation if so. Use an idempotency key, a unique label the caller attaches to the request; the tool remembers keys it has seen and, on a repeat, returns the previous result instead of doing the work again. Make writes replace rather than append when appropriate, such as writing a report to a file name based on the job identifier, so a second write overwrites the first instead of creating a duplicate. Note that read-only tools are naturally idempotent, which is one reason they are safer.