Chapter C49 · Interactive Course
From a request to a tool result
APIs, tools, schemas, proposals, results and failure classes.
Core Learning Concept
Follow the tool exchange from definition to proposed call, validation, authorization, execution, and result. Match each result to its call, then choose a repair based on the failure type. Keep format validity separate from correct values and completed external actions.
What You’ll Learn in This Chapter
-
An API is a software interface
Recognize a programmatic request to another system.
An Application Programming Interface defines how software programs communicate with services. Its structured contract specifies required request parameters and expected responses, letting programs invoke remote capabilities reliably without human interfaces.
-
A tool makes an action available to the agent
Identify a callable capability exposed by a host.
A tool exposes an operation an agent host can execute, such as searching files or creating an event. The model can request that operation using its declared interface. Merely describing a desired action in text does not prove that the tool exists, was called, or completed successfully.
-
A schema describes acceptable arguments
Read required fields in a small tool contract.
A schema specifies the required fields, datatypes, and structure for tool calls. Automatic schema validation rejects missing or malformed inputs prior to execution, preventing invalid requests from reaching external systems.
-
A tool call is a proposal to execute
Distinguish generated arguments from application execution.
A model’s tool call specifies an operation and arguments for the host to process. The host may validate, authorize, execute, or reject it according to the system’s design. Follow that boundary in the diagram: producing a call and performing its requested side effect are separate events.
-
Results return to the next step
Follow a call-result-response loop.
A tool result reports what happened for a particular call, commonly linked by an identifier. The agent can use it to decide the next step or compose a reply. An empty search result or error is information that should shape the answer, not a gap to fill with an invented success.
-
Structured output is a format promise
Separate schema validity from truthful content.
Structured output constrains a response to an expected format, with guarantees depending on the feature and failure conditions. A valid JSON object can still contain an incorrect date or unsupported claim. Handle refusals, incomplete responses, and validation errors, then check the contents against the task.
-
Different failures need different repairs
Classify invalid input, denied access and temporary outage.
Different failure modes require distinct responses. Malformed inputs need syntax corrections, missing permissions need authorization, and temporary outages warrant bounded retries. Never retry side-effecting operations blindly without checking external system state first.
-
Complete the tool loop
Arrange a tool definition, arguments, permission decision, returned error and corrected next action into a coherent trace.