Agentic Tool Side Effect Declaration
Definition. Marking each tool as read-only or mutating, and specifying what it changes, so that the runtime can apply different controls: confirmation, logging, rate limits and rollback. Undeclared side effects are how an agent performs an action nobody expected.
How it works. Declare the effect class per tool: read, create, update, delete or send. Apply confirmation for mutating tools where the consequence is high. Log every mutating call with its arguments and result. Require idempotency keys for create operations. Review the declaration when a tool changes, since a read tool that gains a write capability is a new risk.
Example. A tool named get_or_create_customer is declared read-only because its name suggests retrieval. It creates records, and an agent calling it for 400 lookups creates 400 duplicate customers. Declaring it as mutating, requiring an idempotency key and logging the calls prevents the duplicates, and the tool is split into separate get and create tools so the effect is explicit.
Use case. Side effect declaration is required for any agent with tools, and it is the basis for applying the right controls. It is also what makes an audit trail meaningful, since it distinguishes reads from writes.
Warnings. A tool's name does not reliably indicate its effect, so declare it explicitly. Never let a mutating tool run without logging. And never assume a read tool stays read-only across versions.
Limitations. Declaration requires knowing what each tool does, which is not always documented. It also cannot capture indirect effects, such as a read that triggers a cache write or a notification.