Tool Manager

Reference Architecture

The Tool Manager is the only path through which the Decision plane produces side effects. It implements the Tool Gateway pattern from the Adapter Mesh: typed envelopes, identity brokering, schema validation, approval-mode enforcement, idempotency, OTEL trace propagation.

Definition

A boundary component that turns a Planner step into a ToolCallEnvelope, brokers ingress and egress identity, validates against the adapter’s argument schema, enforces the declared approval_mode, executes against the registered adapter, and returns a typed ToolResultEnvelope.

Why it exists

Direct adapter calls bypass approval-mode binding, identity propagation, and trace propagation. The Tool Manager is the single deterministic boundary that closes those loops for every external effect.

Inputs

• Plan step from the Orchestrator
• Run Context (tenant_id, user.delegation, agent.workload_identity, safety_mode, run_budget)
• Adapter registry (capability set, schemas, declared approval_mode)
• Active policy decisions from the Policy Engine

Outputs

• ToolCallEnvelope (built from the plan step + Run Context + policy decision)
• ToolResultEnvelope (status, output, citations, mutations, policy_decision_id, latency)
• OTEL span tagged with contextos.action.approval_mode_effective, contextos.action.policy_decision_id

How it works

1. Resolves the step’s tool_id to an adapter and capability.
2. Validates args against the adapter’s arg_schema_ref.
3. Re-evaluates the Policy Engine at execute time with the latest context.
4. For network / delegated / destructive: emits a propose envelope with frozen evidence snapshot; waits on the approval gate.
5. Brokers credential exchange (STS-style); attaches delegated_user_token_ref and agent_token_ref.
6. Executes against the adapter; captures latency, retries, cost.
7. Emits typed ToolResultEnvelope with citations, mutation refs, policy decision id, and trace context.

Cached read-only aliases

For prompt density, well-used read-only tools may be exposed as cached, first-class aliases (mcp_<server>_<tool>). Constraints:

• alias only synthesized from cached MCP discovery (no live discovery);
• only read-only tools eligible;
• tool must be operator-pinned or score well from prior usage;
• execution still routes through the Tool Manager so policy, approval, tracing, scoring stay centralized.

Idempotency

Every write-class capability declares idempotency_key as a required argument. The Tool Manager:

• generates the key if the Planner did not (deterministic from (step_id, request_id));
• caches (idempotency_key -> ToolResultEnvelope) per tenant and capability for the dedup window;
• returns the cached result on retry without re-executing the adapter.

Failure modes

• Tool schema drift between registered and live endpoint — caught at validate; returns failed with error_code=VALIDATION_ERROR.
• Approval-mode upgrade mid-flow — refuse and emit a security event.
• Idempotency cache miss after retry due to TTL — adapter sees a duplicate; mitigated by adapter-side dedup contract.
• Egress credentials expired — refuse and request re-issuance.
• Cached alias hides a permission change after policy update — invalidate alias cache on bundle promotion.

Operational concerns

• Adapter and protocol version pinning per environment.
• Egress rate budgets per (tenant, capability).
• Secrets rotation and credential-exchange hygiene.
• Allow-list of tools eligible for cached aliasing; revalidate on policy change.
• Per-tool latency budgets enforced by the Run Context, not the adapter.

Evaluation metrics

• Tool success rate by (adapter, capability).
• Approval-mode misclassification rate.
• Permission-violation rate.
• Mean and p99 latency by adapter.
• Idempotent-replay correctness on chaos-injected duplicates.