# TOOLS.md

> Inventory model-callable capabilities and make schemas, descriptions, authentication, authorization, side effects, idempotency, errors, timeouts, output limits, and approval requirements explicit.

**Decision rule:** Expose the narrowest capability that supports a named workflow. Use MCP for reusable cross-system access and ordinary application functions for capabilities owned inside one product boundary.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Tool inventory and contract

> Make tool selection and consequences understandable to both models and reviewers.

- **Capability:** <Name the user outcome and why a model needs this tool>
- **Schema:** <Define narrow typed inputs, outputs, defaults, and validation>
- **Side effects:** <Classify read-only, reversible, external write, financial, destructive, or privileged behavior>

## Identity and authority

> Keep authentication separate from the permission to perform a specific action.

- **Authentication:** <Define caller, user, service, tenant, and credential lifecycle>
- **Authorization:** <Define resource- and action-level policy checked at execution time>
- **Approval:** <List arguments and actions requiring preview, confirmation, or a second reviewer>

## Reliability and observability

> Specify predictable behavior under repetition, delay, partial failure, and large outputs.

- **Failure contract:** <Define typed errors, retryability, timeout, cancellation, and partial results>
- **Idempotency:** <Define duplicate detection, keys, replay, and exactly-once assumptions>
- **Telemetry:** <Record tool name, sanitized arguments, authorization, latency, result, and correlation identifiers>

## Verification

> Test the contract as adversarially as the model and external systems will use it.

- **Contract tests:** <Cover valid, malformed, boundary, oversized, and unsupported inputs>
- **Safety tests:** <Cover prompt injection, confused deputy, cross-tenant, approval bypass, and revocation>
- **Operational tests:** <Cover timeout, retry, duplicate execution, dependency failure, and recovery>

## Related AgentAtlas field guides

- [Tools and MCP](https://agentatlas.dev/topics/tools-mcp)
- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)
- [Observability](https://agentatlas.dev/topics/observability)

## Primary references

- [MCP specification](https://modelcontextprotocol.io/specification/) — The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations.
- [Connect Codex to MCP servers](https://learn.chatgpt.com/docs/extend/mcp) — How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities.
- [Codex security](https://developers.openai.com/codex/security) — Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration.
- [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) — Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.