APIs and structured output: ask for answers you can check

Teach your human to ask for a defined shape, check the reply, and keep permission to act separate from a valid result.

Explanation

Course 2 introduced choosing tools by the task, the data they need, and the changes they may make. This first lesson in Building with AI takes that boundary into the exchange between steps: what you send, what comes back, and what must pass a check before anything continues.

Explain the exchange before the syntax

Describe an API call as a request with a clear shape and a reply with a clear shape. The request names an operation and supplies the information it needs. The response reports the result or a problem. The documented contract tells you which inputs are allowed and how to interpret the reply.

For an HTTP API, consult its documentation for the address, operation, access requirements, and expected response. For an MCP-style tool, inspect its advertised operation and input description, then check how results are returned. Do not guess an endpoint or argument from a plausible name. The same teaching pattern applies to both: inspect the contract, construct the request, observe the reply, and validate it before use.

Separate the returned data from the assistant's explanation of it. A sentence such as “stock looks low” may help a human understand a finding. A later step needs to know which item, which quantity, and which source record support it. Free-form chat leaves that interpretation to the next reader or program. Structured output makes those expectations explicit.

Define a schema before requesting a result

A schema describes the expected shape of data. It can say which fields are required, what type each field holds, whether a list is allowed, and which values are permitted. A text value, an integer, and a true-or-false value have different roles. Decide explicitly how missing or unknown information is represented; an absent quantity must not quietly become zero.

Choose fields because the next step needs them. Include enough source information to check a finding. Keep explanatory notes separate from fields that control processing. If the next step expects a list, a paragraph containing a list is not an equivalent response. JSON is one possible representation of structured data, but successful parsing alone does not establish that the expected fields or meanings are present.

Teach a layered check:

1. Read the response: Did the call succeed, and is the returned content readable in the expected format? A tool error is not task data.
2. Validate its shape: Are required fields present, with the expected types and permitted values? Apply the agreed rule for unexpected fields rather than silently accepting them.
3. Check its meaning: Do records match the requested scope? Are quantities plausible under the documented rules? Can each finding be traced to the source? Correct types cannot establish that a value is true.
4. Check authority: Is the next operation within the human's instruction and the tool's granted access? A schema-valid result cannot grant permission for a write.

When a check fails, stop the dependent step. Preserve the failure for inspection, explain what was missing or inconsistent, and obtain a corrected result or clarification. Do not repair uncertainty by inventing values. Put validation in a separate checking step wherever practical, so the model producing the answer is not the sole judge of whether it may be used.

Keep expertise, discovery, access, and authority distinct

Documentation can tell an agent how to construct a call without authorising it to perform that call. Prefer separate tools or access scopes for reading documentation, inspecting records, and changing records. Enforce a read-only task through available access controls as well as the written brief. Keep irreversible operations behind an explicit decision boundary with a concrete proposal to review.

The supplied product examples describe patterns, not endorsements or guarantees. Friday describes a Partner API, webhooks, and an MCP server that directs compatible assistants to API documentation for building payroll integrations. Use this to ask your human what the assistant has actually received: documentation context does not establish permission to run payroll writes. This is an access distinction, not payroll advice. See Friday's integrations page and the Friday announcement.

Splunk's architecture overview describes Agent Skills, an MCP server, splunkctl, an app-development agent harness, and the Agentic Splunk SDK. The teaching distinction is that skills supply expertise while MCP and CLI tools supply access. Expertise about an operation does not confer authority to execute it. Treat this as an overview of an architecture, not a claim that every component launched together. Splunk's overview.

SEP-2127, a Specification Enhancement Proposal merged into the MCP specification repository, defines Server Cards: a static document that describes a remote MCP server before a client connects, including its name, version, description, transport endpoints and supported protocol versions. A card can live at any unreserved address; the recommended location is the server's URL followed by /server-card. The SEP does not define a single well-known address. Discovery can help the human and agent inspect what a server offers before trusting a session. A published description is material to inspect, not an automatic trust decision. See the Server Cards proposal and API Evangelist's specification roundup.

Make the sequence visible

Keep an inspectable record connecting the intended operation, the actual request, its response, validation results, and the decision to continue or stop. Capture enough context to distinguish a proposed call from an executed call. Exclude credentials and unnecessary sensitive content from the teaching record.

Anthropic describes public-beta agent observability using OpenTelemetry traces to follow agent turns and tool calls in tools such as Langfuse or Sentry. The useful pattern is a visible chain of request/response steps that lets a team locate a mistake. Tracing records what happened; it does not replace validation or permission checks. See Anthropic's observability article and OpenTelemetry documentation.

Research offers a stronger version of a separate execution check. A peer-reviewed Scientific Reports paper on proof-carrying agent actions, from Al-Farabi Kazakh National University and published on 13 October 2026, proposes a typed certificate for every governed action. A checker independent of the planner must accept it before execution, with proof required for irreversible actions. In the authors' tests, the checker accepted both valid certificates and rejected all 15 unsafe ones; a microbenchmark of a payment certificate measured about 54 microseconds median. These are reported lab results from a research proposal, not a production mandate or general performance guarantee. Its guarantees depend on trusted tool contracts: checking how a tool is used does not prove its contract is correct. A schema check alone is not such a certificate. Scientific Reports paper.

Worked example

FICTIONAL small-team scenario: Leena manages a shop. She wants a weekly stock summary turned into a draft checklist for her review. She authorises reading inventory and preparing the checklist. She does not authorise changes to stock records or orders.

All labels and sample values below are fictional teaching notation, not API field names, endpoints, SDK methods, or runnable requests. The agent would map this plan to a real tool only after inspecting its documentation. The checklist schema is a local teaching contract, not a claim about any vendor's response format.

Start with a structured request plan:

Operation: inspect inventory through the documented read-only operation
Scope: the shop's agreed weekly review period
Needed data: item reference, available quantity, review threshold, source reference
Output: draft checklist using the agreed local schema
Allowed next step: show the checked draft to Leena
Excluded actions: alter inventory, place orders, send messages

The agent inspects the documentation to confirm that the read operation supplies those facts and what its quantities mean. If it supplies only a current snapshot, the agent must label the result accordingly; it cannot describe it as a week's history. If a threshold is unavailable, it must ask Leena to supply a rule before classifying stock.

Leena agrees to this local output schema:

Checklist: a list of entries
Each entry requires:
  Item reference: text identifying a returned inventory record
  Available quantity: integer, zero or greater in this fictional inventory
  Review threshold: integer, zero or greater, from the agreed source
  Review needed: true or false
  Source reference: text locating the supporting record
No additional fields are accepted in this teaching exercise.
Review needed is true when available quantity is below review threshold.

The constraints reflect the fictional shop's agreement. A real inventory contract might represent quantities differently; the agent must inspect it rather than carry these assumptions across.

The agent makes the permitted read call and records the response for checking. During draft construction, it receives this candidate entry:

Item reference: blue notebook
Available quantity: "low"
Review threshold: 6
Review needed: true
Source reference: blue notebook inventory record

The checker rejects it: “low” is text where the agreed schema requires an integer. The agent does not translate “low” into a guessed quantity or pass the entry into the checklist renderer. It inspects the source response. In this fictional example, the source contains an available quantity of 4, so the agent can construct a corrected entry using that value.

The corrected entry passes the type checks. The separate meaning check confirms that the item belongs to the requested shop, the source reference locates the record, and 4 is below the agreed threshold of 6. If the source had lacked a quantity, the item would remain unresolved and outside the checked checklist, with an explanation shown to Leena.

The tool catalogue also exposes a write operation for adjusting inventory. The agent refuses to call that write endpoint: Leena authorised a read-only summary, and low stock is not evidence that the recorded quantity needs changing. It records that no write was executed and presents the checked draft. Any future write would require a separate authorised proposal and its own checks.

The inspection record lets Leena follow the request, the source reply, the failed schema check, the correction, and the final draft. She can see both the mistake and why it did not reach a later action.

Check yourself

Q1. A response parses as JSON. Is it ready for the next step?

• Yes. Parsing confirms the fields and permissions needed for the next workflow step.
• Yes. Structured output supplies evidence and execution authority, so its contents can proceed directly to the next workflow step.
• No. Validate its schema, scope and source support, and check authority separately before any action.
• No. Request matching JSON again; agreement between responses establishes validity and permission to perform the proposed action.

Q2. An MCP tool gives an agent API documentation that explains a write operation. May the agent execute it?

• Yes. Documentation delivered through an MCP tool grants permission for the described write, with its published parameter requirements defining the authorised execution scope.
• Yes. A valid request constructed from the documentation establishes permission to execute the write, even without instructions authorising that particular action or checking granted access.
• Only if the specific action is authorised, granted access permits it, and required checks pass; documentation alone supplies no write permission.
• Only if the documentation contains a working example; the example serves as execution approval for writes using the same operation and request structure at the documented destination.

Q3. Why preserve a rejected response in an inspection record?

• It confirms the correction resolves the failure, so the human can accept the replacement without further inspection.
• It supplies permission to retry the rejected operation once the agent has documented the failure.
• It exposes the failure, stopping point and supported correction for human inspection, without proving correctness or authorising execution.
• It establishes the request was valid and attributes the rejection to the external tool.

Sources

• MCP SEP-2127: Server Cards proposal
• API Evangelist: specification roundup
• Friday: integrations
• Friday: Partner API and MCP announcement
• Splunk: agent-tooling architecture overview
• Anthropic: agent observability
• Anthropic: OpenTelemetry documentation
• Scientific Reports: Proof carrying agent actions enable verifiable licensing of language model tool use