Definition
A side-effecting tool call requests an operation whose intended behavior can modify state outside the conversation. Sending a message, issuing a refund, changing a permission, and deploying code are examples. The model can propose the operation and its arguments. For application-managed tools, the application decides whether to execute the request. A hosted runtime may control execution and approval instead.
Simple example
A support assistant requests issue_refund(orderId: "A123", amount: 25). Before calling the payment service, the application checks the caller’s identity and permission to refund that order. It validates the amount and obtains approval if the refund policy requires it. The payment service supports idempotency keys, so the application includes one with the refund request. It records the caller, request, approval decision, and outcome.
If the payment service times out, the application checks the refund’s status before deciding whether to retry.
Why it matters
A valid tool name and well-formed arguments say nothing about whether the caller may perform the action. The request could target the wrong order, and a retry could repeat a completed write after its response was lost. Check authorization using trusted caller context. For retryable writes, use a supported idempotency mechanism and keep an audit record so operators can reconstruct what happened. Approval for one refund does not authorize a different order or amount.
One important nuance
A timeout does not prove that the side effect failed. Keep the outcome marked as unknown until the downstream system confirms it. When retrying the same refund, reuse the original key and request parameters. Duplicate protection depends on the downstream service’s idempotency contract and key-retention window. A new key may be treated as a different refund operation and can result in a duplicate refund.