Skip to content

Composite Tools

devlomingo edited this page Nov 16, 2026 · 1 revision

Composite tools

The idea

Agents repeat the same chains of calls. Each step is a model turn and a round-trip. Toolsmith watches these chains in its traces and, when one repeats, proposes a composite tool that does the same work in one call, running independent steps in parallel.

Before:  getUser → getOrders → getOrderItems ×3 → getPayments ×3   (8 calls)
After:   flow__getUserOrdersDetails                                (1 call)

What gets discovered

A workflow must:

  • appear in at least 3 sessions (patterns.minSupport);
  • be linked by data flow: a later call uses a value an earlier call returned, or the same input feeds several calls;
  • have each step taken by most runs that reach it.

Repeated calls over a list (for each order…) become one forEach step. Unrelated calls in between, and other agents sharing a session, are separated out by data flow.

How a composite stays safe

Check What it means
Declarative plan A composite is data interpreted by fixed code. Nothing generated is ever run as code.
Equivalence For read-only plans, the evaluator runs the original calls one by one, then the composite. Results must be identical.
Authorization Every step must call a tool that is already exposed. The composite's access is the highest of its steps'.
Writes A plan that writes runs strictly in recorded order, is never executed by the evaluator, and needs its own --allow-writes approval.
Human approval Always required before an agent can see it.

Day-to-day

toolsmith-mcp patterns       # repeated workflows found so far
toolsmith-mcp discover       # propose composites and evaluate them
toolsmith-mcp show <name>    # the plan and its checks
toolsmith-mcp approve <name> --description "Use when the user asks about …"
toolsmith-mcp usage          # calls, round-trips saved, adoption

Write the --description in your users' words: agents choose tools by their descriptions, and you know the phrasing best.

A composite unused for 7 days is flagged. Extra tools cost agent context, so disable ones that aren't earning their place.

Measured benefit

On the 8-call benchmark workflow: about 4× faster than a sequential agent; at 50–100 concurrent agents about 1.9× the throughput and 3–5× less MCP traffic, with identical results. No LLM is in the benchmark loop, so the model turns saved are not counted. Full report.

Limits

  • Discovery needs a few repetitions; rare workflows are not found.
  • Composites pass values between tools and can filter, sort, pick and count with a fixed vocabulary. They don't compute anything else.
  • Values that collide by coincidence (small ids) can produce spurious patterns; evaluation and your review catch them.

Full details: TOOL-GENERATION.md and ARCHITECTURE.md.

Clone this wiki locally