Design Typed Tool Contracts and Action Controls
Give an agent narrow, validated interfaces and enforce authority, idempotency, verification, and recovery outside the model.
By the end
You will be able to
- Define typed tool inputs, outputs, errors, and side effects.
- Validate model-selected arguments before executing application code.
- Apply least privilege and exact-target approval to consequential actions.
- Design idempotency, postcondition checks, and recovery for uncertain outcomes.
Not every tool call carries the same risk
Reading a file, editing a local draft, sending a message, deploying production, and deleting data have different consequences. Permission design should reflect those differences instead of treating tool access as a single switch.
Prefer the smallest authority that can finish the task. Keep secrets out of prompts and logs, scope credentials to the required system, and expire temporary access.
The schema is an API contract, not a permission grant
Give each tool one clear purpose and a narrow schema with required fields, enums, formats, length and numeric bounds, and additional properties disabled where the provider supports it. Validate again in application code because generated structure can still contain unauthorized or semantically unsafe values.
Return stable success and error shapes. Separate retriable transport failures from validation, authorization, policy, conflict, and unknown-outcome errors so the controller can make a bounded recovery decision.
{
"type": "object",
"properties": {
"resourceId": {"type": "string", "pattern": "^doc_[a-z0-9]{8}$"},
"operation": {"type": "string", "enum": ["archive"]},
"idempotencyKey": {"type": "string", "minLength": 16, "maxLength": 64}
},
"required": ["resourceId", "operation", "idempotencyKey"],
"additionalProperties": false
}Approval belongs before the consequential step
A human gate is useful only when the reviewer can still prevent impact. Ask before sending, purchasing, publishing, deploying, or destroying, not after the action has already happened.
Safe automation also needs an idempotency strategy, a bounded retry policy, and a recovery path. Repeating a failed action blindly can duplicate messages, charges, or changes.
Separate selection from execution
The model may select a tool and propose arguments. A trusted executor authenticates the caller, validates the schema, authorizes the resolved resource, binds any approval to that exact action, enforces limits, and only then calls the implementation.
Treat returned content as untrusted data. Verify the real postcondition and record a secret-safe audit event containing the request identity, decision, target, result, and recovery status.
Practice activity
Specify and threat-test a consequential tool
- Choose a tool that writes, sends, spends, changes permission, or deletes, and define its narrow JSON input and stable result/error union.
- Write executor checks for identity, schema, semantic validity, authorization, exact-target approval, rate and cost limits, and idempotency.
- Test malformed arguments, an unauthorized target, prompt-injected tool output, timeout after success, and a duplicate call.
- Define the postcondition query and recovery or escalation for each outcome.
What to produce
- A typed tool contract with side effects, error taxonomy, approval, idempotency, and postcondition rules.
- A five-case threat-test table showing rejection, verification, and recovery evidence.
Reflect before continuing
Which unsafe request passed JSON validation but failed authorization or policy?
Evidence
Sources and verification
- Function callingOpenAI · verified 2026-07-25
- Tool use with ClaudeAnthropic · verified 2026-07-25
- Function calling with the Gemini APIGoogle · verified 2026-07-25
Knowledge check
Make it stick.
Choose the strongest answer for each question. Your attempts become part of your device-local transcript.