Pattern Matrix/White Paper/A1

Problem

As the tool registry grows, overlapping names and stale state make selection harder. A logistics dispatch agent can repeatedly choose the same driver if it does not refresh availability or check the session quota. The individual tool call may be valid while the sequence is operationally wrong.

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.

Classification: 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 (A5) in the same module also falls on the routing side, but with a different division of labor—A1 addresses "how to pick," while A5 addresses "trim before picking."

Solution and mechanics

Production Tool Dispatch depends on tool metadata that covers identity, schemas, execution behavior, source, progressive disclosure, and lifecycle. A name, description, and parameters are enough to invoke a demo tool, but not enough to govern side effects and state.

Useful execution characteristics include isReadOnly, isConcurrencySafe, isDestructive, requiresFreshState, and requiresApproval. Unknown values should take the conservative path: no parallel execution, no approval bypass, and no assumption that state is fresh. If booleans cannot represent "undeclared," use explicit enums or reject incomplete schemas at registration.

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

Applicability

• 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.

Known failure modes

• 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 a large registry to the model consumes context and increases ambiguity. Keep core tools resident and retrieve extended tools on demand.
• Tool poisoning: An attacker can place hidden instructions in an external tool description. Defenses include allowlisting, description scanning, sandboxing, behavior monitoring, and least privilege, selected from the system's threat model.

Verification and metrics

• Tool selection accuracy: Replay historical queries and judge whether each step selected a suitable tool, grouping errors by task class.
• Side-effect controllability: Use chaos tests to verify that quotas, approvals, and saga compensation stop or reverse a destructive mis-dispatch.
• Tool hallucination rate: Track nonexistent tools, invalid parameters, and schema failures. Investigate changes in registry quality and candidate-set size.
• Tools per task: Analyze the call distribution together with task complexity and repeated calls; the count alone does not establish over-tooling.

Reference implementation

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.

Illustrative scenario

Liang Bo's execution-oriented agent separates knowledge retrieval, skill loading, and tool calls into retrieve, use_skill, and call_tool. In an intra-city dispatch scenario, the dispatch layer adds richer metadata, selection guidance, mandatory state refresh before writes, a per-session driver quota, and saga side-effect tracking. The named practice shows that most Tool Dispatch work sits in contracts, state, and side-effect control. Any outcome figure should be published only with the team's approved evaluation method.

Related patterns

• Minimal tool set (A5): complementary within the same cell. A1 picks accurately within a given tool set; A5 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 (A4): A4 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 A4 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.

Design conclusion

Tool Dispatch encodes permission, idempotency, state freshness, approval, rollback, rate limits, and audit behavior as metadata and runtime contracts. Tool choice cannot rely on name, description, and parameter schema alone.