Tool calls: validate intent and arguments before an external effect

Last updated: 5 Oct 20268 min read

tutorial

A tool schema constrains argument shape, but it does not grant authority. The executor must check the signed-in user's permission, resource ownership, allowed operation, idempotency key, and expected side effect. Separate read tools from write tools and use confirmation where the action's risk calls for it. Tool results are lower-trust data on return, even if they came from an authorized API. A prompt can tell the model to ask for a tool only when needed, but enforcement must live outside the prompt in application code.

Decision in practice

A billing assistant may read invoice INV-2837 and suggest a refund. The customer says to reverse the charge, but the active agent identity has only read permission. The model proposes issue_refund with invoice_id and amount. The executor rejects the call before sending it because the user lacks refund authority. For an authorized finance operator, it also verifies the invoice belongs to the intended account, the amount is within the remaining refundable balance, and an idempotency key is present. A tool result that says approved cannot override the local authorization check.

Proposed action: issue_refund(invoice_id=INV-2837, amount=47.00).
Executor checks: actor role, account match, refundable balance, idempotency key.
Read-only actor: deny without sending the action.
Authorized actor: execute once; record receipt and reconcile outcome.

Performance and operating cost

Authorization checks add a database or policy lookup per proposed effect, but the cost is bounded and necessary. Retries need a stable idempotency key or an uncertain network response can create duplicate effects. Log the decision and receipt without exposing payment secrets. Measure rejected unauthorized calls, duplicate attempts, and requests needing human review. A model's explanation of why a call is allowed is useful context for an operator, never a replacement for the executor's policy decision.