Effect Classifiers for Tool Calls: Read, Write, Money

The table has one row per tool and exactly one effect value. The router reads it at call time to decide auto-run, auto-run with logging, or pause for approval. The audit reads the same rows after the fact to confirm that every money-class call had an approval record. Two readers, one source, no drift.

Three rules keep the table honest.

First, effect is assigned by the team that owns the downstream system, not by the agent developer who wants fewer pauses. A CRM field update feels like a write, but if it triggers a contract workflow and a scheduled call, the traversal makes it money-class. One governance writeup describes exactly that scope creep: an agent asked to update a single property decided the account was ready to advance and touched status, which fired a chain of downstream workflows runtime enforcement.

Second, reversibility is separate from effect. A refund can be clawed back, an email cannot be unsent. Both are money-class when they spend or commit resources, but the reversibility field tells the approver how much friction to apply.

Third, a tool absent from the table does not run. That default resolves the hardest question in agent governance, which is not "what is this agent allowed to use" but "should this specific invocation, with these arguments, execute right now." Tool attachment during development "just in case" widens the breach radius, and a table with a deny-by-default fallback is the cheapest way to shrink it AI agent tool call security.

Here is the classifier for a small support and billing agent. Numbers are illustrative, not measured.

Two entries deserve argument. send_email is classified money even though no money moves in the call. The reason is that irreversibility plus audit obligation makes it behave like a spend: once it leaves, revoking the credentials afterward is forensic, not protective, and an auditor asking "did a human authorize this specific operation" cannot be satisfied by an OAuth scope granted weeks earlier human-in-the-loop approval gates. If your organization insists email is a write, keep it in the write row but log the full rendered body, recipients and message ID, because the before and after state is what protects you when someone disputes what was sent.

cancel_subscription is money because a cancel that turns out to be wrong costs a win-back and often a refund. Compare that with update_ticket_tags, where the before state is recoverable from the log with one API call.

The table also answers a question that trips up reviewers: how many tools an agent actually needs. A support agent that summarizes the queue does not need send_email at all. Removing the row from that agent's scope is stronger than approving every call, and it takes one line in the per-agent allowlist.

The effect decides the path. Write the router so the path is a function of the table row plus the call arguments, never of the tool name string matched inside the model output.

Read. Validate the tool name against the table, check the arguments against the JSON schema, execute, return the result. Reads never pause. If a read fails validation, return a schema error to the model so it can correct the call, which is the intended loop: the model proposes, the runtime validates and executes what is tool calling.

Write. Execute immediately, but capture before and after state in the same record as the call ID. The log entry needs a run ID, the caller fixture or user identity, the tool, the arguments, the prior state, the resulting state, and a cleanup rule when the test ran in a sandbox sandbox side effects. A write without before and after state is untraceable, and untraceable writes are the ones that generate support tickets.

Money. Three steps, in order, and none may be skipped:

1. Create an approval request that freezes the exact arguments, hashed, and stores the hash next to the request.
2. Route it to the named approver role from the table. Pause the workflow.
3. On approval, mint a single-use token bound to the argument hash, with a short expiry. The executor runs the tool once with that token and refuses any call whose arguments no longer hash to the frozen value.

That last constraint is what separates a real gate from a rubber stamp. A queue-then-execute model decouples approval latency from agent latency, and the credential that was valid at pause time may not be valid at resume time, which is the failure most approval implementations skip approval gates. Microsoft's agent framework exposes the same shape: wrap the function so the run returns a ToolApprovalRequestContent carrying the function name and arguments, then create a response with true or false and pass it back in a new run framework approvals.

Low-code runtimes make the pause explicit too: the workflow sends an approval request over a chosen channel showing which tool and which parameters, and on approve the tool executes with the AI-specified input n8n human in the loop. Audit the parameters in that message. If the reviewer sees only the tool name, they are approving an intent, not an amount.

A gate you can read in ten lines

on_tool_call(tool, args, run_id):
  row = table[tool]
  if row is null: return refuse("unknown tool")
  if row.effect == "read": return execute(tool, args)
  if row.effect == "write": return execute_and_log(tool, args, before_after=True)
  h = sha256(canonical_json(args))
  req = approvals.create(run_id, tool, h, approver=row.approver_role)
  approvals.pause(run_id, req)
  return pending(req.id)

on_approval(req_id, decision, approver):
  req = approvals.get(req_id)
  if approver != req.approver_role: return refuse
  if decision == "deny": return cancelled(req)
  token = tokens.mint(req.arg_hash, ttl_seconds=300, single_use=True)
  return execute_once(req.tool, req.args, token)

Classification decides whether a call should happen. Idempotency decides whether a retried call can happen twice. You need both, and the classifier tells you where to spend the effort.

Generate one operation key when the workflow decides what should happen, not when the retry occurs. A run ID, trace ID or tool-call ID changes on every retry and must never serve as the identity of the business effect idempotent tool calls. Store the key with a payload hash, a status, a lease and the result behind a uniqueness constraint. A duplicate with the same payload returns the stored result; the same key with different arguments is rejected. Postgres INSERT ... ON CONFLICT is a working arbiter for the claim.

The record needs a needs_reconciliation state, distinct from failed. Collapsing "safe to try" and "unknown whether it happened" into one bucket is how duplicate effects get created, because a timeout means the client does not know what happened, not that the operation failed the double-charge trap. On the money path, needs_reconciliation should page the approver, not retry the charge.

Pass the same key to the downstream provider. A local database row alone cannot make a card charge, an email or a deployment exactly once, because the second call still leaves the process. The provider has to deduplicate on a key derived from your operation key, or you reconcile against the provider's state before retrying idempotent tools.

Worked example. A refund step creates refund:invoice_842:approval_17 when the approver clicks approve. The tool writes a row with that key, status in_progress, a 30 second lease, and the payload hash of the amount and currency. It calls the provider with the key. The worker dies before writing the result. On restart the workflow regenerates the same key from the durable approval record, finds in_progress with an expired lease, calls the provider with the same key, receives the original charge object, and stores it. One refund, two attempts, one effect.

Test the gate, not the transcript. A passing conversation is evidence that the agent said the right thing. It is not proof that the workflow succeeded or that no unauthorized call ran sandbox side effects.

The crash test is the one most suites omit, and it is the one that reproduces the reported failures. Kill the process at exactly that seam and count the effects at the receiver. Then repeat with the keyed path and confirm the count stays at one.

The audit scan is worth writing as a scheduled query rather than a test, because it also catches a table edit that reclassified a tool without updating the router. If money-class call counts and approval-record counts diverge, something is wrong, and the divergence is visible in one query.

Run the whole suite against fixtures in an isolated environment, assert the final record state rather than the response body, and clean up by run ID so a failed test cannot poison the next one sandbox side effects. For a broader view of where these gates sit between the agent and the API gateway, the runtime enforcement model is a useful reference ai runtime enforcement.

Once the gate holds, the next question is what the agent uses to reason across the many model calls inside a single workflow. Routing every model through one endpoint keeps credentials, cost and logging in a single place; Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI-compatible key, which makes the classifier's own model calls as auditable as the money path they guard (https://quantaintelligence.ai/inference).