Tools Are Typed Authority Boundaries
A model may propose a call, but a deterministic runtime must decide whether that exact typed action has authority to cross a side-effect boundary.
- Authorship
- InterviewsVector
- Published / updated
- 2026-09-21 / 2026-09-21
- Review status
- Artifact tests passing · primary sources recorded
Original InterviewsVector teaching. Executable artifacts are deterministic illustrative boundary checks covered by focused tests; they do not claim production authorization, protocol conformance, durability, memory quality, or safety certification.
The decision in one pass
Treat every tool as a small, versioned capability with a typed request, typed success result, closed error vocabulary, declared side-effect class, least-privilege scopes, approval policy, retry semantics, budget, and owner. Model output is an untrusted proposal: parse it, reconstruct it at the public boundary, reject unknown fields and ambiguous scalar types, bind it to the exact contract version and authenticated principal, attenuate delegated scopes, and authorize the current resource immediately before execution. For a state-changing call, bind approval and an idempotency key to the exact operation. Validation shows only that a proposal fits a local contract; it does not prove the principal is authorized, the external system is unchanged, or the action is safe.
Why this matters
Tool calling turns generated text into reads, writes, messages, purchases, deployments, and deletions. A persuasive model explanation cannot substitute for a parser, policy engine, transactional adapter, or human decision. Without a narrow contract, retries duplicate effects, stale approvals authorize changed payloads, broad credentials create a confused deputy, and server errors are mistaken for success.
You will be able to
- Specify a tool as a versioned typed capability rather than a natural-language command.
- Separate schema validity, authenticated authorization, approval, execution, and result validation.
- Design effect-aware idempotency and closed error semantics for uncertain retries.
- Attenuate scopes and budgets before a model-proposed action reaches an adapter.
- State exactly what a local contract audit proves and what remains production evidence.
Prerequisite contract
Your Vector Loop for this lab
- 01
Model
List principals, resources, effects, trust boundaries, and every place a proposal can be rejected.
- 02
Derive
Derive a closed request schema, result union, scope set, approval rule, idempotency rule, and call budget.
- 03
Build
Implement a frozen content-addressed contract and reconstruct requests at the runtime boundary.
- 04
Stress
Probe unknown fields, bool-as-int, non-finite values, string subclasses, stale versions, missing scopes, replay, and constructor bypass.
- 05
Operate
Record proposal, policy, approval, idempotency, attempt, outcome, and reconciliation identities without logging secrets.
- 06
Defend
Explain which local invariants passed and which authorization, transaction, and safety claims still need external evidence.
Make the capability smaller than the API
Do not mirror a broad internal SDK into the model surface. Give one tool one bounded business meaning. A name and description help the planner select it, while the machine contract controls accepted fields and effects. Reject additional properties, duplicate names, coerced booleans, non-finite numbers, overlong strings, and stale contract identities before policy evaluation.
| Contract element | Question it answers | Unsafe omission |
|---|---|---|
| version and content identity | which exact behavior was offered? | a familiar name silently changes meaning |
| closed input schema | which values can cross the boundary? | extra fields smuggle control data |
| effect class | is this read-only or state-changing? | writes inherit read-style retries and approvals |
| scope set | what minimum authority reaches the adapter? | ambient credentials widen blast radius |
| result and error union | what did the executor establish? | timeouts and partial success collapse into generic failure |
| budget and owner | how often and who may operate it? | loops spend or act without a stopping rule |
Design retries from effect semantics
An idempotency key is useful only when the receiving system stores it in the same authority domain as the effect and returns the prior committed result for an equivalent retry. A key attached to logs after the write cannot prevent duplication. Bind it to actor, tenant, operation, canonical payload, and a declared retention window. If a timeout leaves the outcome unknown, reconcile by operation identity before issuing another write.
- 01Classify the effectSeparate pure reads, bounded writes, irreversible actions, and asynchronous jobs.
- 02Bind one logical operationDerive or receive an idempotency identity before the first attempt and keep it across transport retries.
- 03Represent uncertaintyReturn committed, rejected, retryable, and unknown-outcome states instead of a single boolean.
- 04Reconcile before repeatingQuery the authoritative system by operation identity when the first result is unknown.
Assign decisions to deterministic owners
For each illustrative proposal, identify the first boundary that must stop it. A schema can reject a wrong type, but only authenticated policy can decide scope; an approval record can authorize one reviewed payload, but only the executor can establish whether an external effect committed.
Place each decision at the tool boundary
Inspect illustrative tool proposals, then decide whether schema validation, authenticated policy, per-call approval, idempotency, or execution owns the next decision. The exercise grants no real authority.
Stop the tool call at the first authority boundary
Inspect one original synthetic proposal and predict its next valid transition. Tool schemas describe shape; trusted identity, policy, approval, and idempotency still govern authority.
These records contain invented principals, tenants, and actions. No request is sent to a real tool or service.
| Boundary | Contract | Observed |
|---|---|---|
| Identity | Bind the authenticated principal | principal=operator-17; tenant=acme |
| Arguments | amount_cents is an integer from 1 to 500000 | amount_cents="all remaining credit" |
| Authority | Operator may create bounded payments | Role grant exists, but arguments are not yet valid |
| Side effect | No call before every prior boundary passes | No provider request recorded |
Select a prediction, then check it against the current evidence.
Run the typed authority audit
The artifact freezes a bounded write contract, content-addresses it, copies caller-owned collections, reconstructs nested records at the public boundary, validates a closed scalar schema, attenuates a broader grant to one required scope, binds approval to the exact arguments and idempotency key, and checks the call budget. It never invokes a tool. The ALLOW decision therefore means only that this illustrative proposal passed the local checks.
1def main() -> None:2 print(format_example())Expected output
example=illustrative_only
contract_id=tool-contract@sha256:478ea5be7a46789a8a0139db45b410d2f455ca219b38948c7ff3cbc681ed32fe
tool=create_support_credit
effect=write
schema=VALID
delegated_scopes=support:credits:write
approval=BOUND_TO_CALL
idempotency=REQUIRED_PRESENT
decision=ALLOW
claim=LOCAL_CONTRACT_CHECK_ONLY
certification=NOT_A_PRODUCTION_AUTHORIZATIONVerify: python3 -m unittest discover courses/ai-engineering/reference-impl/tool_contracts
Observe decisions, effects, and unknown outcomes separately
Emit one trace identity across proposal, contract, policy decision, approval, attempt, external operation, result, and reconciliation. Count schema rejection, authorization denial, approval expiry, budget exhaustion, idempotency conflict, executor latency, typed errors, unknown outcomes, and confirmed duplicate effects separately. Redact or tokenize sensitive arguments; an audit log that leaks credentials creates another authority boundary.
Operate at three altitudes
Production lens
- — Version the schema, effect class, scopes, error union, approval rule, idempotency semantics, owner, and retirement date as one contract.
- — Give the executor attenuated short-lived authority, not a broad token copied from prompt context or model output.
- — Track committed, rejected, and unknown outcomes separately and reconcile uncertain writes before retrying.
Staff lens
- — Build a small reviewed capability catalog instead of exposing every backend method to every planner.
- — Require threat modeling and rollback or compensation for tools whose failure can spend money, publish data, change access, or contact people.
- — Make contract retirement observable so stored plans and long-running workflows cannot call a silently repurposed tool name.
Interview defense
You are adding a model-callable tool that can issue a customer credit. What belongs in its contract and runtime boundary?
I expose a narrow credit operation rather than a generic billing client. Its immutable contract has a closed schema with bounded amount, customer identity, reason, typed result and errors, write effect, minimum scope, per-call approval, idempotency semantics, call budget, and owner. The runtime treats the model call as untrusted, reconstructs exact types, binds the contract version and authenticated tenant, authorizes the current customer, binds approval and idempotency to the exact payload, attenuates credentials, and executes through an adapter. Timeouts produce an unknown outcome that is reconciled by operation ID before retry. The trace links proposal through external result, but validation alone is not authorization or proof that the write committed safely.
Expect the interviewer to press on
- — Why is a JSON schema not an authorization policy?
- — What must an idempotency key be bound to?
- — How do you represent a timeout after a possible commit?
Misconceptions to remove
“The model can call a tool safely because it emitted valid structured output.”
Structure only narrows parsing. Authenticated identity, current policy, approval, resource state, budget, and execution outcome remain deterministic runtime responsibilities.
“A retry after timeout is safe because the first call failed.”
The response failed to arrive; the effect may have committed. Reuse a correctly stored idempotency identity or reconcile before another write.
“Passing the user's full OAuth token is convenient least privilege.”
It delegates every token scope. Exchange or attenuate it to the minimum audience, action, tenant, and lifetime the adapter requires.
Check your model
1. What does a closed input schema prove?
Only that the supplied representation matches declared structural constraints; it does not establish identity, authorization, semantic truth, or successful execution.
2. Why bind approval to a payload digest?
So a reviewed approval cannot be replayed for changed arguments, a different tool, server, tenant, or logical operation.
3. What should happen when a write times out after dispatch?
Record an unknown outcome and reconcile against the authoritative system using the operation or idempotency identity before retrying.
Prove the mechanism
Design a contract for a model-callable refund request. Include exact scalar validation, additional-field rejection, typed error states, minimum scopes, approval binding, idempotency storage, uncertain-outcome reconciliation, call budget, and redacted trace fields.
Add a production constraint
Migrate a widely used tool from version one to version two without silently changing stored plans. Define dual registration, compatibility rules, policy and approval version binding, replay behavior, telemetry, rollback, and final retirement conditions.
Artifact: Typed tool authority contract
courses/ai-engineering/reference-impl/tool_contracts/tool_contract_audit.py
Download reference implementationPrimary references and next links
References
- 1. JSON Schema Core
JSON Schema. Official core specification for schema vocabularies, identities, and evaluation structure.
- 2. JSON Schema Validation
JSON Schema. Official validation vocabulary for structural instance constraints.
- 3. RFC 9110: Idempotent Methods
IETF. Standards-track definition of idempotent request semantics and retry motivation.
- 4. NIST glossary: least privilege
NIST. Primary definition of limiting resources and authorizations to those needed for an assigned task.
Continue through the graph
- A Tool-Using Agent Is a Bounded State Machine →
Place typed tools inside explicit transition, budget, and terminal-state rules.
- MCP Host, Client, and Server Boundaries →
Carry the same authority rules across a protocol boundary.
Glossary: tool contract · capability · least privilege · scope attenuation · idempotency · confused deputy · unknown outcome · reconciliation