Schema: tools and side-effect contracts

[rajanbor]

Goal

Define library/schemas/tool.schema.json for tools an AI agent may invoke.

Human contract

Explain purpose, inputs, outputs, authentication, permissions, side effects, idempotency, timeout, retry policy, failure modes, redaction, and audit evidence. Include read-only and state-changing examples.

Machine contract

Use typed input/output schema references and explicit side-effect classes. Require confirmation or escalation for destructive or externally visible actions. Define retryable errors and idempotency without vendor-specific fields.

Acceptance criteria

• Schema, guide, valid examples, and unsafe invalid fixtures exist.
• A mutating tool cannot omit side effects or recovery behavior.
• Secret fields are marked and excluded from logs/examples.
• Agent references to tools can be validated.
• Tests cover timeout, retry, and idempotency constraints.

Depends on the document envelope and aligns with the agent schema.