Repository navigation
Composite Tools
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)
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.
| 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. |
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, adoptionWrite 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.
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.
- 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.
toolsmith-mcp · MIT · Repository · Report an issue · Changelog
Getting started
Using it
Operating it
Links