tool-design-output
Design or audit what an agent tool returns: shape and trim payloads, paginate, report partial success, reference files and media, and add next-step hints. Use when tool output bloats the context window.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- tool-design-output
- description
- Design or audit what an agent tool returns: shape and trim payloads, paginate, report partial success, reference files and media, and add next-step hints. Use when tool output bloats the context window.
- argument-hint
- [tool whose result shape to design]
- user-invocable
- true
02 资源文件 1
- 参考文档agents/openai.yaml293 B
03 SKILL.md 正文
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
- 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.
- Define a flat, named shape for the result and keep it identical across calls.
- Decide the size policy: default summary, expansion flags, cursor pagination, truncation limits, and references for blobs.
- Add navigation:
hasMoreand cursor, GUI URLs, and a next-action hint. - Handle mixed outcomes with per-item status for anything that touches more than one item.
- 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: falseby 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. hasMoreomitted 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.
On Runtype
-
Runtime tool results go to the model directly. An
externaltool returns the upstream body unchanged (itsbodytemplate maps the request, not the response), so shape a noisy payload in aflowtool whoseapi-callstep feeds atransform-datastep. Acustomcode tool has no network egress unless it opts in withnetworkAccess(anallowedHostnameslist is the safe form); without it, the tool can shape only what arrives in its parameters. -
A
flowtool returns the value that the flow's final executed step wrote. SetoutputVariableto return one named flow variable instead, such as thetransform-dataoutput, andoutputMappingto select a dot path inside it. A_-prefixed variable is rejected, and a variable the flow never assigned fails the tool call. See Flow tools. -
If you run your own MCP server, apply these rules to its results. You cannot reshape a third-party MCP server's results, so prefer its narrower tools.
-
paginate-apiis the platform's pagination step for upstream lists (cursor, offset, page, orLinkheader). -
Empty is not the same as failed. A fetch-class step (
fetch-url,api-call,crawl,search) witherrorHandlingunset swallows a failure intodefaultValue(or an empty result) and reports success, so a downstreamtransform-dataorupsert-recordruns over zero rows as if the API returned nothing.validate_flowwarns withFETCH_CLASS_SWALLOWING_FEED; seterrorHandling: { "onError": "fail" }when an empty result must not look like a real one. Unlike these steps,paginate-apifails by default. -
upsert-recordneeds a JSON object as its source.validate_flowwarns withUPSERT_RECORD_SOURCE_NOT_JSONwhen a text prompt feeds it, and the write fails at runtime. Set the prompt'sresponseFormatto"json", shape the value intransform-data, or setcontentFieldon the upsert step to wrap the string. -
Store large content in a record and return its id. The agent calls
get_recordto fetch it. -
Binary media over 4 KB in a tool result, such as a screenshot or a generated image, becomes a
runtype-asset://handle automatically, so later turns carry the handle, not the bytes. Handles expire after 7 days. To accept one, declare the parameter withcontentEncoding: "base64", and Runtype substitutes the stored bytes before the call:{ "image": { "type": "string", "contentEncoding": "base64" } } -
The model receives each new tool result in full; Runtype does not truncate it for you. Older results outside the recent window (40,000 tokens by default) are masked: the model sees only a short "cleared" placeholder, not a trimmed copy. Write anything the agent needs in later turns to a record. See Context compaction.
-
To verify a result shape, run the tool with
execute_tooland read the raw result. After an agent run, the Context window bar in Logs shows the share of input tokens that tool results take, and hints when they dominate.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.