tool-design-composition
Compose and expose agent toolsets: task-level operations, batching, discovery, dry runs, and versioning.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- tool-design-composition
- description
- Compose and expose agent toolsets: task-level operations, batching, discovery, dry runs, and versioning.
- argument-hint
- [tool set to organize or extend]
- user-invocable
- true
02 资源文件 1
- 参考文档agents/openai.yaml311 B
03 SKILL.md 正文
Tool Composition and Discovery Design
A composable tool set has four properties: consistent input and output shapes, so one tool's output feeds the next tool's input; batch support, so the agent does not loop one item at a time; more than one abstraction level, so the agent picks the granularity the task needs; and discoverability, so the agent finds the right tool without trial and error.
Procedure
- Map the current set: every tool, its type, and the sequences agents actually run (from traces, not from intent).
- Find bundle candidates (Task Bundle): sequences repeated across runs with no branching between steps.
- Find batch candidates (Batch Operation): the same tool called in a loop over a list.
- Find ladder gaps (Abstraction Ladder): capabilities with only a raw low-level tool and no intent-level tool, or the reverse.
- Add a
modeparameter (Operation Mode) that defaults topreviewon every destructive or costly command. - Design discovery (Dependency Hint, Tool Registry, Schema Explorer): hints in descriptions, a registry or search tool once the set is large, and layered schema exploration for data sources.
- Prune: merge near-duplicates and retire tools with no traffic. Fewer, better-described tools beat many similar ones.
- Verify: run each new tool on its own, then run the agent and read its trace to confirm it picks the new bundle, batch form, or preview mode instead of the old sequence.
Rules with examples
Offer the capability at more than one altitude (Abstraction Ladder)
low execute_query(sql) full control, expert use
mid search_records(table, filters) structured, safe
high find_customers_like(description) intent-level, does the work
Each rung has a stated use case; higher rungs call lower ones internally; descriptions say when to use which. Do not ship only the low rung and expect the agent to compose it correctly every time.
Bundle the sequence the agent always runs (Task Bundle)
search_users then open_dm then send_message becomes dm_user(name, message).
Name the bundle after the task, not the steps. Handle intermediate failures inside the
bundle and return a composite result that reports each step. Keep the atomic tools
available for edge cases, and say in the bundle's description that it replaces the
sequence.
Accept lists (Batch Operation)
Any tool the agent calls per item over a list gets a batch form: an array input, a
documented maximum batch size, per-item results with status, and a partial-success
report (see tool-design-output). Batch the upstream calls internally where the API
allows. Decide up front whether a batch is all-or-nothing or partial, and say which.
Explore before executing (Operation Mode)
Give commands a mode parameter that defaults to the safest option:
explore list what the tool could do here, read-only
preview show exactly what would change, no side effects
dry_run validate inputs without executing
execute perform the action
Return the same result structure in every mode so the agent can compare a preview to
the real run. A schema mode that returns the upstream's complex input shape is useful
when the shape cannot be expressed in the tool interface.
Make the sequence explicit when it matters (Tool Chain)
For multi-step processes with a fixed order, define the chain as ordered steps with data passing between them and checkpoints for resume. A chain is a specification the agent follows, or a single orchestrated tool that runs it; either way the order is not left to inference.
Fan out, then merge (Scatter-Gather Tool)
A tool that consults several sources queries them in parallel, merges the results into one canonical shape, and reports per-source status so a failed source degrades the result rather than failing it.
Discovery: how the agent finds the right tool
Say what to call first (Dependency Hint)
Descriptions and parameter docs name prerequisites ("userId: if you only have an
email, call search_users first"), follow-ups ("after this, get_user verifies the
change"), and alternatives ("if this fails, try send_email"). Repeat the hint in the
error the tool returns when the prerequisite is missing.
Catalog the set when it is large (Tool Registry, Capability Matching)
Past roughly twenty tools, tool-selection accuracy drops and every definition costs
context tokens.
Provide a list_available_tools(category) registry with name, description, category,
and auth requirements, and a find_tool_by_intent(intent) search that ranks tools by
semantic match with confidence and usage examples. Where your runtime can defer tools,
keep the must-use tools always loaded and let the long tail be discovered.
Reveal structure in layers (Schema Explorer)
For data sources, do not dump the full schema. Layer it: list_tables(), then
describe_table(name), then sample_rows(table, limit), then get_query_hints(table).
Each layer's description names the next.
Check before relying (Health Check)
A fast (sub-second) check_service_health(service) returns healthy, degraded, or
unavailable with specific reasons, so the agent does not spend turns on a dead backend.
Cache the status briefly.
Across the system
- Tool Gateway: one entry point routes to many backends and aggregates discovery, so the agent sees one consistent set.
- Tool Adapter: wrap a legacy or awkward API in a clean tool: LLM-friendly description, constrained inputs, shaped output. The adapter hides the legacy shape entirely.
- Canonical Tool Model: shared
User,Task,Eventshapes and field names across every tool, mapped to and from each backend. - Tool Versioning: version in the name (
send_email_v2) or metadata, run versions in parallel during migration, and deprecate with a migration note in the old tool's description.
Anti-patterns
- Thirty atomic tools and no bundle for the sequence 80% of runs perform.
delete_fileswith no preview mode.- Two tools that differ only in one optional parameter.
- A registry that lists tools without their auth requirements or categories.
- A composite tool built before any trace showed the sequence being used.
- A migration that changes a tool's behavior in place instead of versioning it.
On Runtype
- Tool count and residency. Runtype does not cap the number of tools in a dispatch;
it caps the request's serialized
runtimeToolsat 1 MB. A model provider can still refuse a long tool list (TOOL_COUNT_REFUSED_BY_PROVIDER), so use tool search for large tool sets. Tool search is on by default for multi-turn agents: at 20 or more tools, Runtype keeps a hot set loaded and defers the inline runtime tools behind atool_searchtool that the model calls to load more. Saved, built-in, and MCP tools stay loaded. Settools.toolSearch.enabled: falseto send every tool on every request. Single-turn agents and flow prompt steps always send every tool, so keep those sets small or split them across subagents. Either way, make descriptions distinct, because they are what the model chooses by and whattool_searchmatches against. - Tool-call budget. An agent makes at most 10 tool calls per execution unless you
set
config.tools.maxToolCalls. A per-item loop over a list uses up that budget quickly, so ship a batch form, or raise the cap on purpose. - Task bundle and tool chain. A flow is the platform's explicit chain: fixed step
order, data passing, per-step error handling. Expose it as one tool
(
toolType: "flow") when the agent should run the whole sequence as a single call. Map tool parameters to flow inputs withparameterMapping. The model receives the flow's terminal step output; to return a composite status object instead, assign it to a flow variable and name that variable inoutputVariable. A variable name that starts with_is rejected, and a variable the flow never assigns fails the call. - Code Mode for batch, chain, and fan-out. When the logic between calls varies by
input (loops over a list, conditional chains, several sources merged), set
config.tools.codeModeConfigon the agent or prompt step.toolPoollists the tool ids the model can call (wildcards such asmcp:*work), andtimeoutMsdefaults to 60000. The model writes JavaScript that calls those tools in a sandbox, and intermediate values never enter model context. Choose aflowtool when the order is fixed; choose Code Mode when the model must write the logic. - Binary results. A binary tool result, such as a screenshot or a generated image,
carries a
runtype-asset://handle. To accept it in your own tool, declare the input as a string with"contentEncoding": "base64"; a handle passed there is replaced with the stored bytes before your tool runs, so the model never copies base64. A parameter without that declaration receives the handle string unchanged. - Abstraction ladder. Built-in and Orthogonal catalog tools are the low rung;
custom,external, andmcptools the middle; flows and subagents the top. Compose subagents as saved subagent tools, inline subagent tools, or dynamic spawning throughconfig.tools.subagentConfig, which gives the agent aspawn_subagenttool. Subagents have their own caps; readget_platform_documentation(topic="subagent-delegation"). - Gateway and adapter. An MCP server attached through
config.tools.mcpServersis a Tool Gateway: one connection, many tools. Anexternaltool is a Tool Adapter: it wraps an upstream API behind a clean interface. For a GraphQL API, use anexternaltool that POSTs the query; thegraphqltool type is not executable. - Operation mode. On an agent, gate destructive tools with
config.tools.approval.require(for example,["delete_files"]; patterns such asmcp:*work). Approval asks a person before the call runs; it complements apreviewmode but does not replace it. Atool-callflow step runs a catalog tool deterministically with no approval gate, so there a preview must be a distinct tool or amodeparameter. Approval details:get_platform_documentation(topic="agent-design"). - Description length. A new saved tool's description is capped at 500 characters. When dependency hints, replacement notes, and deprecation notes do not fit, move them into parameter descriptions or the error text.
- Registry and discovery.
list_toolscovers saved tools,discover_mcp_server_toolsan MCP server, andget_platform_documentation(topic="builtin-tools")the catalog. Atool-callstep that names a catalog id nobody answers to is rejected asTOOL_CALL_STEP_UNKNOWN_CATALOG_TOOL. - Traces and verification. Find real sequences with
list_runs(filtered byagent_id) andtrace_execution. Test one tool withexecute_tool, then run the agent withexecute_agentand read the trace to confirm the tool choice. - Versioning. Agents and flows are versioned (
publish_agent_version,publish_flow_version); a tool behavior change ships behind a new published version rather than in place.
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.