Field guide / 11 min
Give every tool a narrow contract
Turn model intent into bounded, observable application actions.
OpenAI tools can search, retrieve files, execute code, connect through MCP, or call your own functions. Reliability comes from the boundary around each action: a small schema, explicit authority, idempotency, and a result the model can interpret.
Working principles
Capability is not authority
A tool definition says what is callable. Your server must still decide which user, task, and environment may perform the action.
Small schemas win
Prefer one clear operation with constrained arguments over a generic execute-anything surface.
Results are protocol messages
Return stable identifiers, bounded data, and explicit error categories so the next model step can reason about the outcome.
Field procedure
- 01
Inventory side effects
Mark tools as read-only, reversible write, irreversible write, or external communication. Start with read-only surfaces.
- 02
Define the minimum schema
Use required fields, enums, length limits, and additional-property controls. Keep secrets and authorization outside arguments.
- 03
Add an authority gate
Resolve the authenticated actor and task scope before execution. Require approval for high-impact operations.
- 04
Make execution idempotent
Use operation keys for writes and return the prior result when a retry repeats the same intent.
- 05
Return a compact result
Separate success data, user-correctable errors, policy denials, and transient failures. Avoid dumping unbounded logs into context.
PASS / FAIL
Acceptance checklist
- Every tool has an owner and impact class.
- Arguments exclude credentials.
- Writes use idempotency or duplicate detection.
- Audit records connect intent, actor, execution, and result.
WATCH / REJECT
Failure patterns
- A single broad shell or database tool.
- Letting descriptions act as authorization.
- Returning raw stack traces or massive payloads to the model.