Pattern Matrix/White Paper/A1

A1 · Tool Dispatch

What problem it solves

As the number of tools grows, the chance that an agent picks the wrong one rises. There is a counterintuitive fact here: an LLM is good at using tools (filling in parameters, interpreting return values) but poor at choosing tools. A logistics dispatch agent wired to 17 tools once assigned all 80 orders to a single driver stuck in traffic—at every step it "felt" it had chosen correctly, with the error hidden in details it did not notice, such as "did not refresh driver status" and "did not check road conditions."

Tool Dispatch takes "which tool to choose" out of the model's hands and returns it to the engineering layer. Its core judgment is that tool selection is reliability engineering. It relies not on writing a smarter prompt, but on supplying complete metadata for each tool, plus a full set of engineering contracts: quotas, state refresh, and side-effect tracking.

Why the coordinate is "Action × Route"

• Vertical axis · Action: an agent turns decisions into outward effect through tool calls. In multi-tool scenarios, "which one to call" is the earliest and most frequent decision on the action side, so it belongs to the action module rather than the reasoning module.
• Horizontal axis · Route: it works by directing a given call to the most suitable tool based on current intent and context. This is a typical routing structure, not a chained sequence or a hierarchical wrapper. The minimal tool set (A4) in the same module also falls on the routing side, but with a different division of labor—A1 addresses "how to pick," while A4 addresses "trim before picking."

Core mechanism

The quality of industrial-grade Tool Dispatch is determined mainly by the richness of tool metadata. OpenAI's early function calling had only three fields—name, description, parameters—which is enough for a demo. Claude Code's tool schema expands to 14 fields, grouped roughly into eight categories by purpose: identification, dynamic description, dual schema, execution characteristics, UI behavior, source marking, progressive disclosure, and lifecycle.

The most critical among them are the five execution-characteristic fields: isReadOnly, isConcurrencySafe, isDestructive, requiresFreshState, requiresApproval. Their engineering philosophy is that all default to false—that is, "if unknown, treat as unsafe." If a tool implementer forgets to declare, the system still handles it conservatively; only an explicit read-only declaration admits a tool to the parallel channel and skips the confirmation prompt. Each field corresponds to a senior engineer's intuition about tool operations, encoding judgment accumulated over years of experience into a machine-readable contract.

Around the metadata, three engineering disciplines must be in place:

Suitable production scenarios

• When many tools, many side effects, and a high cost of mis-dispatch stack together: logistics dispatch, customer-service tickets, operations actions.
• When integrating external tool protocols such as MCP: external tool sources are untrusted, so additional security review must rely on the source marking in the metadata.
• Fixed-process tasks: one can go further with Programmatic Tool Calling, where the engineering layer explicitly orchestrates the call sequence and the model only fills in parameters and interprets results, reducing round trips, improving fault tolerance, and making auditing clearer.

Where it goes wrong

• Metadata too thin: with only name plus description, an agent picks a tool from a single sentence, which is like handing an intern a one-line job description and expecting them to start. This is the leading root cause of mis-dispatch.
• Side-effect tools without supporting controls: tools that write to a database, send messages, or deduct payment, without quota, state refresh, or saga—one mis-dispatch is a production incident.
• Tool stuffing: sending more than 50 tools to the model, with the schema eating up a large stretch of context, drops accuracy rather than raising it. The response is progressive disclosure—core tools stay resident, the rest are retrieved and loaded on demand.
• Tool poisoning: this is OWASP Agentic's top threat. An attacker embeds hidden instructions in the description of an MCP tool, and every session that uses this tool is compromised, persistently and broadly. It is not ordinary prompt injection; it requires five layers of defense—allowlisting, description scanning, description sandboxing, behavior monitoring, and least privilege—and missing any one layer leaves an open attack surface.

Key metrics

• Tool selection accuracy (healthy zone >90%): replay historical queries and use a reviewer model to judge whether each step chose correctly. Below 80% usually means the descriptions are not good enough or there are too many tools.
• Side-effect controllability rate (healthy zone 100%): run chaos tests periodically, deliberately making the model mis-dispatch some destructive tool, and check whether it can be stopped by quota within a minute and rolled back cleanly by saga. Any mis-dispatch should be rollable back.
• Tool hallucination rate (healthy zone <5%): the proportion of calls to nonexistent tools or with wrong parameters. Suppress it with strict registry validation plus a pre-call schema check.
• Average tools per task (healthy zone 3-7): too few means the agent is not doing the work; too many is over-tooling.

Minimal implementation skeleton

dispatch(tool_name, args, session):
                tool does not exist        → reject (tool_hallucination)
                quota exhausted            → reject (quota_exceeded)
                fresh state required but stale → reject (stale_state_must_refresh)
                approval required          → suspend (awaiting_approval)
                run handler:
                    success and destructive → register saga inverse + increment quota + refresh state timestamp
                    failure                → record trace, hand off to upper-layer saga rollback
                return DispatchTrace (tool / parameters / trigger / status / rejection reason / latency)
            

Engineering implementation points: metadata defaults to being treated as unsafe; quota is counted by the primary parameter (e.g., dispatch counted by driver id); MCP tools carry a source marking and go through additional description validation and behavior monitoring.

Enterprise implementation example

Liang Bo's team's execution agent divides tools, skills, and knowledge bases into three roles: tools are the "hands," skills are the "playbooks," and the knowledge base is the "map plus manual." The agent uses retrieve to read the map, use_skill to read the playbook, and call_tool to act—reading the map and playbook before acting is exactly Tool Dispatch making the selection at the engineering layer. Applied to that intra-city dispatch agent, the team added five things when rewriting the dispatch layer: tool metadata expansion, selection guidance, mandatory state refresh before write operations, a quota on dispatching to the same driver within a single session, and saga side-effect tracking. Accuracy rose from 60% to 96%, at the cost of about 800 additional lines in the dispatch layer. Each extra line is, in essence, a pitfall an engineer once stepped into, hardened into a rule the machine executes.

Relationships to other patterns

• Minimal tool set (A4): complementary within the same cell. A1 picks accurately within a given tool set; A4 first trims the tool set to a reasonable size so that A1 can pick at all.
• Plan-and-execute (A2): A1 optimizes single-step decisions, while A2 orchestrates the whole multi-step task. Programmatic Tool Calling is where the two meet—the engineering layer sets the call sequence, and within each step it is still a single dispatch.
• Guardrail sandwich (A5): A5 wraps a pre-check and a post-check around the dispatch, nesting with A1's quota and state refresh—A1 picks the right tool, and A5 ensures the wrong pick is still caught.
• Complexity routing (R2): same line of thinking, both routing based on context. The difference is that R2 routes the reasoning tier, while A1 routes the tool.

What this pattern teaches

The essence of Tool Dispatch is not "writing a prompt that picks tools," but encoding the tool-operation discipline accumulated over years by the engineering community into metadata and engineering contracts for the agent to use—a demo-grade agent has 3-field tool metadata, while a production-grade one has 14 fields, and that field gap is the distance between a toy and a system.

This page is part of the ADPS pattern white papers. Back to the pattern matrix, or see the runnable code catalog.