Tool quality is often discussed in terms of function names and input schemas. Those matter, but an agent must also interpret the result well enough to decide what to do next.
A poor result turns the model into a log parser. A giant result fills context with raw text. A terse “success” hides the evidence needed for the next decision. And a result that exists only as an unstructured sentence is hard for a client to validate, audit, or reuse.
The design goal is not to return all available data. It is to return the smallest reliable interface for the next decision.
A tool result is an interface between a deterministic operation and a non-deterministic agent—not a transcript of everything that happened.
Why the usual API intuition is incomplete
Conventional typed API clients are designed for callers that follow explicit contracts. Code can take a documented branch, parse a structured response, and handle an error deterministically.
An agent can misunderstand a parameter, choose an unnecessary tool, overgeneralize from a partial result, or miss the field that determines whether it can continue. Anthropic’s guidance on tool design describes tools as contracts between deterministic systems and nondeterministic agents. For agent-facing tools, that makes response design part of helping the model recover, plan, and explain—not merely confirming that a function returned.
The MCP tools specification defines input schemas, optional output schemas, content items, structured content, resource links, and error behavior. It also calls on servers to validate inputs and clients to validate results before passing them to a model. These protocol features can support a richer agent-facing interface, although MCP does not prescribe the three-artifact design below.
A proposed three-artifact result pattern
Virillio Code Editorial proposes separating a tool outcome into three artifacts when the operation needs both bounded model context and durable evidence. This is an architecture option, not an MCP requirement or an established industry standard; a small read-only lookup may need only a concise validated result.
- Artifact: Operational record — Audience: Runtime and audit systems — Purpose: Complete execution facts and side-effect receipt — Example: Request ID, timestamps, raw response, retry metadata
- Artifact: Model projection — Audience: The agent’s active context — Purpose: Bounded, decision-relevant summary — Example: “3 files changed; tests passed; 1 warning remains”
- Artifact: Evidence reference — Audience: Agent or user on demand — Purpose: Pointer to details too large or too sensitive for the active turn — Example: A URI, artifact ID, or paginated result set
The point is not to duplicate data blindly. It is to give each layer the form it needs.
1. Operational record: retain the truth
The operational record is the system’s evidence that a tool call happened. It should capture enough information to support auditing, recovery, and user explanations: invocation identity, normalized input, timing, outcome, error class, effect status, and links to larger artifacts.
This record may include data that is inappropriate for every model turn. A full query result, a large build log, or a sensitive response can be useful to a human reviewer or a retry policy without belonging in the prompt.
The operational record is also where idempotency and side-effect semantics belong. “The call succeeded” is not enough if the system needs to distinguish “created a new record,” “found an existing one,” and “timed out after the external system may already have acted.”
2. Model projection: expose the decision surface
The model projection is the small, semantically shaped result that the agent needs to choose its next action. It should answer:
- What happened?
- Which facts change the next decision?
- Is more evidence available, and how can it be retrieved?
- Is the outcome final, partial, or failed?
For a test tool, that might be the failing test names, exit status, and a link to the full log. For a code-search tool, it might be the number of matches, the most relevant file paths, and a cursor for the next page. For a write operation, it might be a concise effect receipt and an explicit warning about what cannot be automatically undone.
The projection should be bounded by design. Token efficiency is not merely a cost optimization; it prevents older tool output from crowding out the user’s goal, current files, and later decisions. A system can preserve full output elsewhere without making it mandatory context.
3. Evidence reference: defer detail without losing provenance
Some details should remain available, but not inline. MCP resources provide URI-identified data under host-controlled inclusion policy, and a tool result can return a link to such a resource. A result can similarly point to a managed output artifact, a paginated query, or a structured document.
The key is provenance. A reference should say where the data came from, what it contains, how fresh it is, and whether the agent may retrieve it. A bare URL or opaque blob forces the model to guess; a well-described reference makes it possible to ask for the right evidence only when needed.
Structure is for clients as well as models
Returning structured content does not mean abandoning human-readable text. A good result often has both:
- Structured fields for deterministic client validation and downstream branching.
- Concise text that helps a model understand the outcome without reconstructing the schema mentally.
MCP’s tools specification recommends that tools returning structured content also provide a serialized text representation for compatibility. The broader principle is useful beyond MCP: use a schema for correctness and a clear summary for reasoning.
Avoid the opposite failure mode, where every response becomes a large JSON blob. The agent should not need to scan dozens of irrelevant fields to discover that a permission was denied or a result set is incomplete.
Error results should teach the next action
An error is part of the interface, not an exception to it. The most helpful result classifies what failed and tells the agent what can change:
- Error category: Input validation — What the projection should say: Which field is invalid and why — Useful next action: Correct the arguments
- Error category: Permission or confirmation — What the projection should say: What authority is missing — Useful next action: Ask the user or request the proper grant
- Error category: Temporary dependency failure — What the projection should say: Whether retry is safe and when — Useful next action: Retry with a bounded policy
- Error category: Partial success — What the projection should say: What completed and what did not — Useful next action: Continue from the durable evidence
- Error category: Irreversible side effect — What the projection should say: What changed externally — Useful next action: Report clearly; do not silently replay
MCP distinguishes protocol errors from tool-execution errors for a reason: an agent can often self-correct an actionable execution error, while a malformed protocol request may need a different response path. Preserve that distinction in the model projection.
A result-design checklist
Before shipping a tool, review its result with the same care as its input schema:
- Can a model identify the outcome in one short paragraph?
- Is the next action obvious for success, partial success, and failure?
- Is important evidence structured and validated?
- Is the full operational record available without flooding context?
- Can the result point to large or sensitive detail with provenance?
- Are retries and side effects described truthfully?
- Can a user understand what the agent did from the audit record?
If the answer to any question is no, the tool may work in a demo but will be difficult for an agent to use reliably over many turns.
What we are learning building Virillio Code
Virillio Code’s tool and session work remains in development. We are evaluating result designs that serve three scales: the agent’s next turn, the session’s durable history, and an auditor’s later reconstruction. The three-artifact pattern expresses that design goal; it is not a claim that the current product implements every element for every tool.
The transferable lesson is straightforward: design a tool result as an interface with a decision surface, an evidence path, and a truthful operational record. Agents become more capable when their tools return less noise and more usable structure.
Sources and further reading
- MCP Tools specification — MCP tools support structured content, output schemas, validation, error semantics, and audit-oriented safeguards.
- Writing effective tools for AI agents — Agent tools benefit from meaningful, token-efficient context and clear contracts.
- MCP Resources specification — URI-identified resources can provide on-demand context under client policy.
Editorial disclosure
This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.