In Class 30 you learned the agent loop: think, act, observe, decide, stop. That loop is abstract until you watch it touch the outside world. This lesson makes it concrete. One question. One tool path. One stored result you can inspect later.

The question we will follow is a stock-research request: "What did this company report last quarter, and what changed?" A chatbot would answer from memory and sound confident. An agent must do something stricter: call an approved data source, filter and compare what came back, retrieve the primary filing, and write a summary where every claim points to retrieved evidence.

That discipline — input to tool to validated result — is the whole subject of Class 31.

The path, end to end

Here is the full path for our example:

Question ("What changed last quarter for Company X?")
  → approved market-data API (structured prices + reported figures)
  → filter / compare (quarter-over-quarter change, missing fields flagged)
  → filing retrieval (official quarterly report / 10-Q)
  → source-linked summary (draft + citations + stored record)

Walk each step slowly.

1. Approved data API. The agent starts with a named, permitted source — for example, a market-data provider API or a company-filings API. "Approved" matters. The agent does not search the open web for a random number. It calls a source its builder chose, with a credential that only allows reading. The request itself is structured: ticker symbol, period, fields wanted. That structure is the first control.

2. Filter and compare. The API returns structured data — JSON with revenue, earnings, dates, units. The agent filters to the relevant quarter, compares it to the prior quarter, and computes the change. This is ordinary code or a defined tool step, not model imagination. If a field is missing, the agent records that fact instead of filling it in. "Revenue not present in API response for Q2" is a valid observation. A guessed number is not.

3. Filing retrieval. Numbers without context mislead. So the agent retrieves the primary document — the quarterly filing or earnings release — from an official source. Now there are two evidence types: structured data (the API) and the company's own words (the filing). If they disagree, the disagreement is preserved and flagged for a human. The agent does not silently pick the flattering one.

4. Source-linked summary. Only now does the model write language. The summary is short, and every material claim carries a pointer: which API field, which filing page or section, retrieved at what time. The output is saved as a record — Markdown or a database row — with the inputs, the tool responses, and the draft together. That saved bundle is what Class 31.4 will call a run record.

Why schemas, validation, and freshness matter

Three ideas keep this path honest.

Schemas are the agreed shape of data. The API contract says: "I return ticker, quarter, revenue, currency, reported_at." The agent's code expects exactly that. If the response has a different shape — a renamed field, a string where a number belonged — validation fails and the run stops with an error instead of producing a confident wrong summary. Teach yourself to read the schema before you trust the sentence built on top of it.

Validation is the check at each handoff. Did the ticker match the request? Is the quarter the one asked for? Are units consistent (millions versus thousands)? Is the filing for the same company and period? Each check is small, and together they prevent the classic agent failure: a correct-looking answer assembled from mismatched parts.

Freshness is the timestamp question. Market data ages fast. A filing retrieved last quarter is not evidence about this quarter. Every tool response should carry two times: when the source says the data describes (period_ending, reported_at) and when your agent retrieved it (fetched_at). If the data is stale for the decision at hand, the agent says so and stops or asks for a refresh. Stale evidence presented as current is a silent lie.

A response is evidence, not memory

This is the mental shift:

When the agent summarizes, it is not allowed to "remember" that the company had a great quarter. It may only state what the API returned and what the filing says, with pointers a human can re-open. If the tool call failed, there is no summary — there is an error record and a stop. That restraint is what separates an agent you can operate from a chatbot you can only chat with.

Consider the failure modes this prevents. The model misremembers a ticker. The API returns last quarter's data under this quarter's label. The filing PDF is scanned and the extraction drops a minus sign. In each case, the evidence bundle — request, raw response, validation result, timestamp — lets a human see exactly where the chain broke. Without it, you have a fluent paragraph and no way to debug it.

Check your understanding

1. Why must the agent start from an approved API rather than any number found on the web? 2. What does validation check between the API response and the summary? 3. Why do you need both reported_at and fetched_at? 4. What should the agent do if a required field is missing from the tool response?

Exercise: write a one-tool trace

Pick a narrow question you care about — a stock, a product price, a sports statistic, a public dataset value. Trace it through exactly one tool path on paper. Do not build the agent yet.

Create a file called TOOL-TRACE.md:

# TOOL-TRACE.md — [your question]

## Question
- Exact question:
- How you will know the answer is complete:

## Tool
- Approved source / API:
- Endpoint or method:
- Read-only? (yes / expected scope):

## Request
- Inputs sent (symbols, dates, filters):

## Response (evidence)
- Fields returned:
- `reported_at` / period covered:
- `fetched_at`:

## Validation
- Schema check:
- Ticker / ID match:
- Units check:
- Freshness check (fresh enough?):

## Filing or primary source (if applicable)
- Document + section:
- Agreement or disagreement with structured data:

## Stored result
- Where saved:
- Claim → source pointer (list each):
- Missing or uncertain items:

Finish line: one completed TOOL-TRACE.md where every claim in your draft summary points to a retrieved field or document section.

Verification: cover the summary and hand only the pointers to a reviewer. If they can re-open the API response and filing and confirm each claim, the trace is sound. If any claim relies on "the model knew," rewrite it or mark it unknown.

Next, Lesson 31.2 widens the view: the same question could travel over an API, an MCP tool, a browser, or a CLI — and the surface you choose changes reliability, cost, permissions, and auditability.