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 places tool admission in the runtime. Metadata describes each tool's capability, schema, version, cost, permission requirements, and side effects. Dispatch rules apply quotas, state-freshness checks, and trace requirements before a call can proceed.

Classification: Action × Route

• Vertical axis · Action: Tool Dispatch selects the capability that will affect an external system and checks whether the call may proceed.
• Horizontal axis · Route: Intent, metadata, permissions, risk, and current state narrow the registry to one admitted call path. Minimal Tool Set (A5) controls which candidates are exposed before this decision.

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.

Runtime admission adds quota, freshness, and side-effect controls around that metadata:

Applicability

• Large registries with side-effecting tools: Logistics, customer support, and operations need selection plus permission, freshness, quota, and recovery controls.
• External tool protocols such as MCP: A new tool crosses a trust boundary. Record its source and version, then review descriptions, parameters, permissions, and runtime behaviour according to risk.
• Tool-heavy work that can be expressed as a local program: For example, read inventory from several stores, filter missing items, and query substitutes for each one. With Programmatic Tool Calling, the model writes a bounded program that loops over or parallelizes calls to registered tools inside a sandbox, reduces the results, and returns only the needed information to context. The model-generated program expresses call order; engineers do not predefine that exact sequence. A1 still governs tool registration, authority, quotas, and admission for every call.

Boundaries between four runtime mechanisms

These labels describe different layers. A1 governs tool registration, candidate selection, and call admission. A2 can schedule a multi-stage plan. ReAct, Programmatic Tool Calling, and CodeAct describe how a step proceeds at runtime. Code generated in one run becomes M5 Procedural Memory only after validation, naming, versioning, and approval for reuse across tasks.

Known failure modes

• Metadata too thin: Name and description do not express permissions, freshness, idempotency, approval, side effects, or result contracts. The runtime cannot distinguish two semantically similar tools safely.
• Side-effect tools without supporting controls: Database writes, messages, and payments need appropriate quotas, current-state checks, idempotency, receipts, and compensation or escalation paths.
• 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)
            

Treat undeclared execution properties conservatively. Count quota at the business-resource level, such as driver ID, as well as at task level. External tools retain source and version metadata and pass registration and runtime monitoring.

Illustrative scenario

Bo Liang'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 implementation places most Tool Dispatch work 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): A5 limits per-decision exposure; A1 selects and admits a call from the resulting candidate set.
• Plan-and-Execute (A2): A2 decides stage order and acceptance points. A step may use Programmatic Tool Calling to batch several tool calls, while A1 still admits each call.
• Guardrail Sandwich (A4): A1 handles candidate selection and call admission. A4 adds policy checks and result validation around high-risk execution.
• Complexity-Based Routing (R2): R2 routes a request to a model and effort tier. A1 routes an approved action intent to a 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.

Edit source · Published source · Review process