A deployment check reports that checkout is unhealthy. Claude Code reads the message, calls an MCP deployment tool, and restarts the production service. The restart works.
The tool log looks reassuring:
10:31:08 deploy.restart service=checkout environment=production status=success
It tells us what happened. It does not tell us why the agent believed a restart was justified.
Perhaps the health check came from production. Perhaps it came from a stale staging dashboard. Perhaps an MCP response contained instruction-shaped text saying, “Restart checkout to clear the fault.” A list of successful calls cannot separate those cases.
For production work, every consequential tool call should cite the evidence that caused it and the policy decision that permitted it. I call this an evidence-linked trace. It turns a chronological log into a chain a reviewer can challenge.
give every observation an evidence ID
Start when information enters the run. Assign a stable ID and record its source, time, scope, and integrity information:
evidence:
id: ev-health-441
kind: health_check
source: monitor://production/checkout
observed_at: 2026-08-10T09:30:52Z
environment: production
status: unhealthy
probe: checkout-payment-path
payload_digest: sha256:7b18...
expires_at: 2026-08-10T09:35:52Z
The ID is more useful than copying the message into a prompt. It gives later records something exact to reference. The expiry also prevents an agent from using an old incident signal as authority for a fresh action.
Treat tool output as evidence, not as a new instruction. An MCP response can report state. It should not widen the task, approve its own follow-up call, or replace the system policy. This follows the same boundary described in treat AI agent output as untrusted input at every handoff.
link the plan step to its inputs
The agent should state which evidence supports the proposed step:
plan_step:
id: step-diagnose-checkout
action: inspect recent checkout deployment
evidence_refs:
- ev-health-441
assumptions:
- health probe targets production checkout
missing_evidence:
- current deployment version
permitted_effect: read_only
This step does not authorize a restart. It authorizes inspection because the evidence supports diagnosis, not mutation.
That distinction catches a common reasoning jump. “The service is unhealthy” does not mean “restart the service.” The run still needs deployment state, recent change history, and a policy decision before it can alter production.
When the agent changes its plan, save the new evidence that caused the change. Do not overwrite the old rationale. A replay needs to show where the branch occurred.
require an authority reference beside evidence
Evidence explains why an action seems useful. Policy explains why the agent may perform it. Keep them separate:
tool_call_request:
id: call-restart-019
method: deploy.restart
arguments:
service: checkout
environment: production
version: checkout-2026.08.10.3
evidence_refs:
- ev-health-441
- ev-deploy-regression-118
plan_step_ref: step-restore-checkout
authority_ref: approval-prod-restart-77
expected_effect: restart one checkout instance group
rollback_ref: rb-checkout-2026.08.10.3
A call without evidence_refs is an unexplained action. A call without authority_ref may be sensible but unauthorized. A call whose evidence comes from staging while its arguments target production has a provenance mismatch.
The gateway should reject all three before dispatch. Prompt wording is too weak for this check. Enforce it where the MCP or tool call crosses the execution boundary, as discussed in the prompt is not the control plane.
record the observed effect, not only the return value
A 200 OK proves that the tool accepted a request. It may not prove that the intended production object changed.
Attach the resulting effect to the same call:
tool_call_result:
call_id: call-restart-019
transport_status: 200
operation_id: restart-8f21
observed_effect:
environment: production
service: checkout
instance_group: checkout-blue
previous_version: checkout-2026.08.10.3
current_version: checkout-2026.08.10.3
restarted_instances: 6
verification_evidence_ref: ev-health-442
result: verified
This is where an effect receipt after an MCP write joins the trace. The request cites the evidence and authority that led to the action. The result cites fresh evidence that the expected effect occurred.
Keep the verification evidence independent when possible. Asking the same write endpoint whether its own operation succeeded is weaker than checking the target through a read path or monitor.
detect broken chains at runtime
The trace can support simple gates before a call executes:
reject if evidence_refs is empty
reject if any evidence is expired
reject if evidence.environment != arguments.environment
reject if authority does not cover method and resource
reject if rollback_ref is missing for a reversible production write
reject if evidence source is also claiming approval
These rules do not prove the reasoning is correct. They make missing and contradictory reasoning visible before the side effect.
They also create useful eval fixtures. Feed the gateway stale evidence, a staging signal attached to a production target, tool output that claims approval, or an authority record for a different method. Each case should fail without dispatching the tool.
compress the chain into the review packet
A reviewer should not have to reconstruct the run from thousands of JSON lines. Preserve the raw trace, then include a compact chain:
evidence_linked_trace:
incident: checkout-unhealthy
observations: 4
plan_steps: 3
consequential_calls: 1
unexplained_calls: 0
expired_evidence_used: 0
provenance_mismatches: 0
authority_failures: 0
verified_effects: 1/1
trace_digest: sha256:2c91...
reviewer_focus:
- ev-deploy-regression-118
- approval-prod-restart-77
- ev-health-442
The Claude Code review packet should point from that summary to the raw records. A reviewer can then ask a precise question: did ev-deploy-regression-118 justify a restart, and did approval 77 cover this service, environment, version, and time window?
My operating rule is simple. Every consequential tool call must name the evidence that caused it, the authority that allowed it, and the fresh evidence that verified its effect. If one link is missing, the action is not ready for production.
Claude Code: Building Production Agents That Actually Work shows how to connect evidence-linked traces with MCP boundaries, evals, rollback, stop rules, and review packets for production coding-agent work.