Darkmind / Issue 041

Make Every Tool Argument Point Back to Evidence

Require an agent to attach an allowed evidence reference to every consequential tool argument, then have code construct the final payload from those references instead of trusting reconstructed values.

Nov 17, 20265 min readAgent reliability

A tool call can have valid JSON, a real target ID, and an unsafe detail. Imagine an agent reads an invoice, then calls issue_refund. It uses the correct invoice ID but rounds the amount from prose, supplies a currency it inferred from another record, or writes a reason that was never approved. Input-schema validation accepts the shape. Identifier validation confirms the invoice. Neither check answers the remaining question: where did each consequential value come from?

The practical move is to require argument provenance. For every tool field that can change scope, money, recipients, permissions, publication, or a durable record, the agent must name an allowed evidence reference—not merely copy a value into its proposed call. Trusted code then resolves the referenced field from the current evidence artifact or approved proposal, checks that it is still usable, and constructs the execution payload itself.

Tool schemas matter, but they are a format boundary. OpenAI describes function tools as JSON-schema-defined functions through which a model passes data to application code, where the application can take the suggested action.[1] MCP likewise defines tools with metadata and an input schema.[2] Detailed parameter descriptions help a model select and fill those fields, and Anthropic recommends explaining what each parameter means and how it affects tool behavior.[3] But a schema can establish that amount is a number; it cannot establish that this particular number was present in the invoice the agent was authorized to use.

Separate a value from its proof

Treat a model-generated value as a claim about a value, not yet as an executable argument. The model may point to a field in a validated tool result, a named source excerpt, an approved proposal, or a system-owned default. It must not turn a remembered sentence, an unbounded search result, or a plausible calculation into a consequential value without declaring that source.

For a refund, invoice_id may point to a record selected from an authorized list. amount_minor may point to the invoice’s unpaid balance field. currency may point to the same current invoice record. reason_code may point to a small allowlisted enum chosen by the agent, with no source claim required because it is a bounded classification rather than copied business data. The executor should reject a request that says amount_minor: 5000 without also saying which approved artifact and field produced it.

This does not mean every harmless display preference needs a citation. Match the requirement to consequence. A sort_order for a local read can be an ordinary validated option. A recipient address, account ID, price, effective date, publication slug, destination path, or permission role deserves a source handle or an explicit policy-owned default.

Copy this argument-provenance card

Put this between agent reasoning and any tool that can create, update, send, publish, charge, export, or change access. The references should resolve only inside the task’s authorized evidence store.

PROPOSED CALL (model may submit)
{
  "tool": "issue_refund",
  "argument_refs": {
    "invoice_id": {"from": "validated_record:invoice-17", "field": "id"},
    "amount_minor": {"from": "validated_record:invoice-17", "field": "unpaid_balance_minor"},
    "currency": {"from": "validated_record:invoice-17", "field": "currency"},
    "reason_code": {"literal": "duplicate_charge", "allowed_by": "refund-v3"}
  },
  "purpose": "Refund the documented duplicate charge",
  "proposal_id": "prop_..."
}

TRUSTED ARGUMENT BUILDER
1. Allow only the named tool and fields for this proposal.
2. Resolve each `from` reference from an authorized, typed artifact.
3. Reject missing, expired, partial, cross-scope, or ambiguous references.
4. Check the source record version and proposal binding where required.
5. Permit literals only for a field's explicit enum, constant, or policy default.
6. Build the final payload in code; do not execute model-supplied duplicate values.
7. Store {argument, source_ref, source_field, value_digest} in the call receipt.

RETURN
- ready: constructed payload + provenance receipt
- needs_reread: volatile source changed or expired
- needs_approval: a requested value is not bound to the approved proposal
- rejected_argument: no allowed provenance path

The most useful design choice is to keep the value out of the agent’s final payload when code can resolve it. A reference such as validated_record:invoice-17.unpaid_balance_minor is easier to check than a copied number that happens to match today. It also makes review shorter: a reviewer can see which arguments were derived from the current record, which came from approval, and which are constrained literals.

Let current state decide whether old evidence still works

Provenance is not a license to reuse stale data. A field from an earlier read may be correct as history and unusable as an execution input. If amount_minor or a recipient list can change, bind the reference to a record version or short expiry. Resolve it again at the write boundary. If the value differs, return needs_reread or mark the proposal stale; do not preserve an old amount merely because the agent had a citation for it.

Keep the evidence classes narrow. A retrieved web page may support a draft explanation but should not usually provide a payment amount. An approved proposal may authorize one named recipient but not a new address extracted from a message. A tool result from another tenant should fail before field resolution, even if the field name is identical. Provenance answers “where did this value come from?”; authorization still answers “may this workflow use it here?”

Failure mode: provenance theater

A system can defeat this pattern by accepting a free-form source_note such as “from the invoice” or by letting the agent cite an artifact ID that the executor never checks. That is only a more decorated model assertion. References must be typed, scope-bound, and resolved by code against the actual artifact. The receipt should preserve the reference and a safe value digest, not rely on prose about what the model says it saw.

Do not overfit the scheme into an internal citation engine for every field. Start with the values that could cause an irreversible or externally visible error. Test the builder with a valid current reference, a missing field, a cross-scope record, a stale version, an enum literal outside the allowlist, and a model attempt to supply both a reference and a different raw value. Each case should produce one bounded outcome before the external tool runs.

The habit to keep

when an AI proposes a consequential tool call, make every material argument show its allowed origin. Let the model identify evidence; let trusted code re-resolve that evidence into the only payload that can act.

Sources

  1. OpenAI, “Function calling”
  2. Model Context Protocol, “Tools”
  3. Anthropic, “Define tools”