Tools and integrations
L2. One contract for every capability. The tool is the only route to the world, and it is where policy, audit and tenancy meet.
Tools and integrations
L2. The only route to the world.
An agent that can reach anything is a system with no boundary. Every capability goes through one contract, and that contract is where policy, audit and tenancy meet.
Components
| Component | Job |
|---|---|
| Tool registry | The catalogue. What exists, what it takes, what it returns, and who may call it. |
| Tool invoker | Run one call. Ask policy, check the arguments, execute, record the result. |
| Internal tool | A handler over an internal service or over company state. |
| External tool | A handler over a vendor API. |
| Adapter | Hide one vendor: authentication, protocol, pagination, rate limit and retry. |
| Credential vault | Hold every secret. A tool asks for a credential by reference. |
The tool contract
Every capability has the same shape. There is no second shape.
tool
name update_company
description what it does, written for a model
input schema company_id, fields
output schema updated_company
scopes what the caller must hold
side effect read | write | send
risk low | medium | high
The agent sees the name, the description and the two schemas. It never sees the binding, the credential or the vendor.
Who calls a tool
Two callers, and no third.
| Caller | Model in the path | Example |
|---|---|---|
| An agent | Yes | It chooses a tool while it reasons |
| A workflow step | No | An ingest pipeline fetches from a vendor and upserts the result |
A deterministic pipeline still goes through the tool layer, because that is where the adapter, the credential, the rate limit and the audit line live. Do not put an agent in a pipeline that has no decision to make. That is cost with no judgement.
Agent → Tool contract → Internal tool → Internal service → Database
The agent does not know how the CRM API works. That is the point. A route change is absorbed in the handler, and no agent spec changes.
Internal and external
Tools
├── Internal
│ ├── CRM
│ ├── Company API
│ ├── Search
│ └── Analytics
│
└── External
├── Slack
├── Email
├── GitHub
├── Linear
├── Calendar
├── Browser and web
└── Other SaaS
An internal tool is a handler over our own service. It is not a raw route. A route is shaped for a client that knows the domain. A tool is shaped for a model that does not.
An external tool is a handler over an adapter. The adapter owns everything vendor-specific: OAuth, webhooks, protocol, pagination, rate limit, retry and error mapping. A vendor change is one file.
Three connections carry the first measurement sources: Stripe for finance, PostHog for product, Sentry for engineering. Each one is a connections row and about four tools rows, split by side effect: a list tool for ingest, a get tool for a drill-down, and any write tool gated by policy. See Metrics and connectors.
The four checks
A call passes four gates, and each one has one job. No gate does another gate's job.
| # | Gate | Decides | Why it is separate |
|---|---|---|---|
| 1 | Registry | Is this tool visible to this agent at all? | A capability an agent must never hold is absent, not denied |
| 2 | Policy | Allow, deny or require approval, given these arguments | One rule binds every agent |
| 3 | Handler | Are the arguments valid, and is the operation sane? | The schema cannot express every rule |
| 4 | Row-level security | Does this principal own this row? | A check in code is one line a future tool can forget |
Gate 1 and gate 2 differ in kind. A denial the model may see is a tool result, and the agent can adapt, for example by drafting rather than sending. A capability the agent must never have is not offered at all.
Gate 4 is the last line, and it is in the database. A handler can forget. The database cannot.
Rules
- An agent never holds a credential. The invoker resolves a credential reference at call time, from the vault.
- An agent never writes SQL, and never calls a raw route. Both are tool calls.
- A write tool is idempotent, or it takes an idempotency key. A run retry must not send a second email.
- A tool is a row in the registry. A new tool is a write, not a deploy.
- One tool, one capability. A tool with a mode flag is two tools.
- The description is written for a model. It states what the tool does and when to use it, in plain words.
- A tool result never carries a secret. Not in the payload, and not in an error message.
- The registry serves a subset per agent. A full catalogue in a context window is a cost, and it lowers selection accuracy.
Data model
| Table | Holds |
|---|---|
tools | The registry: name, description, schemas, kind, binding, scopes, side effect, risk. |
connections | One external account: vendor, scopes granted, credential reference, health. |
connections holds no secret value. It holds a reference. The value is in the vault, in the foundation.
Risks
| Risk | Mitigation |
|---|---|
| The tool surface grows past what a context window can hold | The registry serves a per-agent subset, selected by the agent spec |
| A tool leaks another tenant's data | Row-level security is the boundary, and it is in the database. The other three checks are defence in depth |
| A vendor outage stops a workflow with no clear error | The adapter maps every vendor error to a small result set, and the step retries with a backoff |
| A prompt injection in a tool result steers the agent | Scan external content before it enters a context window, and gate the memory write path |
| A raw route is exposed to a model "just this once" | Every capability is a registry row. A route with no row cannot be called |
| A rate limit is hit, and the retry storm makes it worse | The adapter owns the limit, and it backs off. The run waits at a step boundary |
Open questions
- Who may add a tool? A tool is a capability, so the answer is a permission decision, not a code decision.
- Do we support third-party tool servers, or only our own handlers? A tool server is a fast way to add capability, and it is an egress and trust decision.
- Does a tool declare a cost, so the budget check at accrual is accurate before the call?
- How does an agent discover a tool it does not have? A "request a capability" path is useful, and it must not become a way to widen a grant.
Diagram source. ac-docs/diagrams/mission-control-layers.drawio, page mission-control-tools.
Edit that page, then run ./scripts/export-diagrams.sh mission-control-layers.
Update this page and the diagram together.