Tool Results, Provenance, and State Updates

A raw payload, a natural-language summary, and a typed result envelope hand the runtime three very different things to update state from. Prefer whichever one lets dependent actions wait for a verified postcondition, not for text that merely reads as success. A summary is the weakest on that count. It can describe an outcome the tool never confirmed, in confident prose. The step that comes next then acts on the description rather than on the outcome.

This is not a matter of taste, and it has a date. In June 2025 the Model Context Protocol added a typed result channel alongside the prose one. Revision 2025-06-18 lets a tool declare an `outputSchema`. Where it does, the specification stops being permissive: “Servers MUST provide structured results that conform to this schema.” The conforming data travels in a `structuredContent` field, and clients should validate it against the declared schema. Sarah Gooding at Socket put it plainly the day after: “Tools can now declare an outputSchema, a JSON Schema describing the precise structure of their results”.

So the three columns are no longer a preference poll. A raw payload gives maximum detail, couples you to the backend, and is hard for a model to interpret. A natural-language summary is easy to read, ambiguous about state, and fragile as control flow. A typed result envelope supports validation and enables replay. It costs you an interface you now have to design and keep stable. That was the price a live protocol paid to hand its clients a result they can check rather than read.

Tool results should distinguish request acceptance, asynchronous progress, completion, partial success, and failure. They should also carry resource identity, version, timestamps, provenance, and a verification path.

That distinction is not an invention of agent design. HTTP made it normative. RFC 9110, published in June 2022, defines the one status code built for exactly this case: “The 202 (Accepted) status code indicates that the request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility in HTTP for re-sending a status code from an asynchronous operation.”

Read the last sentence again. The protocol does not merely decline to promise completion. It tells you in advance that it will never come back to correct itself. Whatever confirms the outcome has to be something you go and read later. Microsoft's Azure Architecture Center gives API designers the same rule: “An asynchronous method should return HTTP status code 202 (Accepted) to indicate that the request was accepted for processing but is incomplete.”

Natural-language summaries are useful for the model. Durable state should be updated from typed fields. Otherwise wording changes can alter control flow.

A status field can report an action finished while nothing has moved. That failure is not hypothetical. It has been sampled, counted and published. The US Postal Service Office of Inspector General reviewed parcels at 25 delivery units and issued a management alert on 19 February 2020. Of 1,126 packages sampled, 423 — 38 percent — had been improperly scanned. The alert itemises the worst category among them: “One hundred and ninety-one (191) packages that were scanned “Delivered” to the addressee, but which were still at the unit.”

It was not a one-off. A second audit covered select Chicago stations and went to the U.S. House Committee on Oversight and Reform. Dated 1 February 2021, it records the same finding under Improper Scanning: “One hundred fifty packages had a “Delivered” scan. A “Delivered” scan should only be made when a package is successfully left at the delivery address.” Of 249 improperly scanned packages there, 150 carried that scan.

Nothing about those records looks broken from downstream. The field is well typed, the value is terminal, the timestamp is real. The customer, the merchant, the refund workflow and any agent polling for completion all read the same word and all draw the same conclusion. The parcel was on a shelf.

Downstream code can trust a result only when it carries execution status, resource identity, provenance, and an evidence handle. The evidence handle and the next actions have to belong to different owners, with a test each.

Execution status states whether the operation was rejected, accepted, pending, partial, or complete. Resource identity names the exact object and version affected. Provenance records source system, timestamp, and execution actor. The evidence handle provides a receipt, job ID, diff, or query for independent verification. Next actions declare the retry, poll, compensate, escalate, or finish options that are legal from here.

Provenance is the node most often left as a design word. It does not have to be. It has had a standard since 30 April 2013, when PROV-DM became a W3C Recommendation. The abstract defines the term: “Provenance is information about entities, activities, and people involved in producing a piece of data or thing, which can be used to form assessments about its quality, reliability or trustworthiness.” The model has three kinds of thing — entities, activities and agents — with time of creation, use and end recorded against them. That is what “source system, timestamp, and execution actor” turns into once someone writes it down properly. The Australian Research Data Commons points practitioners at the same model: “provenance information can be described directly in the W3C Provenance Data Model (PROV-DM) and Provenance Ontology (PROV-O).” The InterPARES Trust AI Terminology Database cites it too.

The evidence handle carries one extra condition, and it is the one most often skipped. It must not share a dependency with the action it reports on. A status surface hosted inside the system it monitors is an evidence handle only for as long as nothing is wrong — which is precisely when nobody needs it.

Take an action that completes later than the call returns, and design the result envelope it should have. The exercise is there to show how an early state update compounds. If the envelope reports acceptance as if it were completion, every step built on top of it inherits an outcome nobody has checked, and the error surfaces several actions later. Write down which field the runtime reads to decide the action is genuinely finished. Then write down who writes that field, and what the state should say in the meantime.

You do not have to invent the answer. Two public standards have published theirs, and you can copy either. Google's AIP-151 covers long-running operations. It dates from 2019 and states the rule: “Individual API methods that might take a significant amount of time to complete should return a google.longrunning.Operation object instead of the ultimate response message.” The field the runtime reads is the boolean `done`. Google's own operations.proto says precisely what it gates: “If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.” While `done` is false, neither branch of the `oneof result` is set. There is no prose to over-read and no half-answer to mistake for an answer.

Microsoft's Asynchronous Request-Reply pattern arrives at the same place from the other direction. The status endpoint's response carries a `status` field holding “a consistent, documented set of terminal and nonterminal values” — Pending, Running, Succeeded, Failed or Canceled. Alongside it sit `createdAt`, `lastUpdatedAt`, `percentComplete` and `error`. That field is written by the operation service, not by the caller and not by the model. The caller's only job is to poll it.

Now run the five steps against your own envelope. List the lifecycle states, keeping accepted, queued, running, partial, completed, cancelled and failed apart. Attach stable identity: job and resource identifiers that cannot be confused with labels. Expose provenance: timestamps, actor, version and source system. Define verification: a safe read or receipt that confirms the postcondition and is not produced by the actor. Map recovery actions: when to poll, retry, compensate, or escalate.

Tool outputs are part of the agent's environment model. Stable result semantics are necessary for planning, monitoring, and incident reconstruction.

A reviewer of tool result semantics works backwards. Pick a step that depends on an earlier action. Ask what that step read in order to conclude the earlier action had succeeded. If the answer is the acceptance of the call rather than a confirmed outcome — a 202 whose own specification warns it will never be corrected, a summary sentence, a scan written by the party being audited — the dependency was never earned. Every step downstream of it rests on the same unchecked assumption.

The three failures in this lesson are one failure at three scales. A scan that said “Delivered” for 191 packages still sitting at the unit. A dashboard that stayed green for roughly two hours because it lived inside the outage it was meant to report. Ninety-seven e-mails that named an error correctly to nobody who was listening. In each case the information existed and the interface between the information and the next action did not.