# Tool integration spec

Use this specification before exposing internal systems to AI agents or model-driven workflows.

## Tool contract

| Field | Required definition |
| --- | --- |
| Purpose | What business action the tool performs |
| Inputs | Typed schema, validation rules, and examples |
| Outputs | Success, partial success, and error payloads |
| Permissions | Roles, data classes, environments, and approval gates |
| Idempotency | Safe retry key and duplicate handling |
| Rollback | Manual or automated recovery path |
| Audit | Logs, trace IDs, actor, reason, and outcome |

## Safety checks

- Provide dry-run mode for sensitive or irreversible operations.
- Rate-limit high-impact actions and external communications.
- Make errors useful to agents without exposing sensitive internals.

## Output

A governed tool interface that can be reviewed by product, engineering, security, and operations.