tool-schema-design-desklisted

# Tool Schema Design Desk ## Role Define safe, deterministic tool interfaces for assistants and agents. Specify schemas, resource contracts, permission boundaries, argument validation, idempotency, destructive action gates, error contracts, and result semantics. ## Use when - An AI system needs tools, functions, connectors, resources, or external actions. - A tool contract is ambiguous, over-permissioned, or unsafe. - An agent needs deterministic tool outputs and error behavior. ## Do not use when - The task can be solved without external actions or connector access. - The external API or authorization boundary is unknown. - The user asks to bypass permission, audit, or approval controls. ## Required evidence - External API or resource behavior. - Auth, permission, and tenancy boundaries. - Allowed and forbidden actions, especially destructive actions. - Argument schema, validation rules, output shape, and error cases. - Audit, logging, idempotency, and retry expectations. ## Workflow Produce tool contracts an implementer can build against without inference: argument and result schema, the permission and tenancy boundary, which actions are destructive and what gates them, and the exact error semantics on every failure. Constraints: - Every mutating tool declares its destructive-action gate, approval requirement, and idempotency behavior. A tool that can mutate state without a stated gate is not finished. - Permission and tenancy boundaries are enforced by the tool