Tool Design Output

Tool Output Design

Every byte a tool returns costs context tokens and becomes part of the model's next input. Design the result as that input.

Procedure

1. List what the agent needs to decide its next step. Only those fields are essential. Everything else is optional detail or a follow-up call.
2. Define a flat, named shape for the result and keep it identical across calls.
3. Decide the size policy: default summary, expansion flags, cursor pagination, truncation limits, and references for blobs.
4. Add navigation: hasMore and cursor, GUI URLs, and a next-action hint.
5. Handle mixed outcomes with per-item status for anything that touches more than one item.
6. Verify. Run the tool once and read the raw result. Then run the agent and check how much of its context the tool results take. If they dominate, tighten the size policy.

Rules with examples

Shape the response (Response Shaper)

Never return the upstream payload as-is. Flatten nesting, select relevant fields, rename cryptic keys, add computed fields, and convert machine encodings to readable ones (ISO-8601 datetimes, not epoch seconds; active: true, not status_code: 2).

Before:

{
  "data": {
    "id": "usr_123",
    "user": {
      "attributes": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "contact": { "primary_email": "ada@example.com" },
        "perm": { "r": "admin" },
        "st": 2,
        "created": 1719800000
      }
    }
  }
}

After:

{
  "id": "usr_123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin",
  "active": true,
  "createdAt": "2024-07-01T02:13:20Z"
}

Spend tokens deliberately (Token-Efficient Response)

• Essential fields only. Codes over prose where a code is unambiguous.
• Truncate long text fields at a documented length and say so ("bodyTruncated": true).
• Count instead of listing when the agent needs the number, not the items.
• Make the expensive part opt-in: includeBody: false by default, with the description telling the agent which call fetches the full item.
• Log response sizes so oversize results show up in traces.

Paginate by cursor (Paginated Result)

Page numbers and offsets drift as data changes. A cursor that encodes the last item's sort key, not a position, does not. Return:

{
  "items": [],
  "count": 50,
  "hasMore": true,
  "nextCursor": "eyJhZnRlciI6ImN0Y18wNTAifQ",
  "nextAction": { "tool": "list_contacts", "args": { "cursor": "eyJhZnRlciI6ImN0Y18wNTAifQ" } }
}

Accept limit with a sensible default and a hard maximum. Keep ordering stable for the same query. Always include hasMore explicitly, even when false.

Summary first, detail on request (Progressive Detail)

Default to the summary the agent usually needs. Offer a detail enum (summary | full) or specific include* flags for sections such as comments or attachments, and document exactly what each level includes. Pair with a get_* tool that returns one item in full.

Say what to do next (Next-Action Hint)

A result can carry the suggested follow-up: tool name plus the parameters to pass, the data still required, and alternative paths. This is the tool-side half of dependency hints and removes a guess from the agent's loop.

{
  "jobId": "job_9",
  "status": "queued",
  "nextAction": { "tool": "check_job_status", "args": { "jobId": "job_9" }, "afterSeconds": 30 }
}

Link to the interface (GUI URL)

Any tool that creates or reads a resource with a web UI returns viewUrl, and editUrl where editing exists. Use deep links to the specific resource. Note expiry for links to sensitive resources.

Report mixed outcomes per item (Partial Success)

Batch and multi-source tools never collapse to a single boolean. Return successes, failures with reasons, summary counts, and a retry hint for exactly the failed items:

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "email": "a@example.com", "ok": true },
    { "email": "b@example.com", "ok": true },
    { "email": "c@example.com", "ok": false, "error": "mailbox full", "retryable": true }
  ],
  "nextAction": { "tool": "send_invites", "args": { "emails": ["c@example.com"] } }
}

Reference large data instead of embedding it (Resource Reference)

Files and blobs travel as typed URIs (resource://files/abc, with contentType, sizeBytes, and a name) that other tools resolve. The conversation carries the reference, not the bytes. Handle expired or missing references with a clear error.

One vocabulary across the set (Canonical Tool Model)

Define canonical shapes (User, Task, Event, Page) once and map every tool's upstream response onto them. Same field names for the same concept everywhere (createdAt in every tool, never created, creationDate, and ts in three tools). Consistent shapes are what let one tool's output feed the next tool's input without a transformation step in the agent's head.

Anti-patterns

• Returning response.json() from the upstream API.
• An unbounded array with no limit, no cursor, and no count.
• hasMore omitted when false, so the agent cannot tell "done" from "unknown".
• A batch tool that throws on the first failure and discards the successes.
• Different tools naming the same field differently.
• Embedding a 200 KB document body in a result the agent only needed the title from.

For error shapes, retry classification, and step failure defaults, see tool-design-errors.