Adding Tools

Add a tool when Anyy needs new runtime behavior. If reusable instructions plus existing tools are enough, write a skill instead.

Tool Descriptor

Runtime tools use protocol.ToolDescriptor through internal/tools. The descriptor names the tool, toolset, schema, risk, timeout, output budget, approval policy, execution policy, and audit category.

Names are model-visible API. Keep them stable and add tests before changing them.

Argument Schema

Schemas are JSON-schema-like maps. Validate decoded arguments in the handler too; the model and UI are not trusted validators.

Reject unknown or unsafe inputs when the action mutates state or touches the host.

Risk Level

Risk classes live in internal/protocol: read, runtime-low, runtime-high, config-low, config-high, credential-high, dangerous, and force-required.

Pick the lowest accurate class. Do not mark file writes, shell operations, credential changes, or config mutations as read-only.

Approval Policy

Approval policy and execution policy decide whether a call runs directly, is audited, needs confirmation, or requires a ChangePlan.

State-changing host operations should use ChangePlan semantics unless there is a specific lower-risk pattern already used nearby.

Audit Category

Use an existing protocol.AuditCategory when possible. Audit records should be bounded and redacted, with enough detail to explain what changed.

Never include raw secrets, provider tokens, channel tokens, or full private payloads in audit metadata.

Tests

Add tests for descriptor shape, argument validation, approval behavior, audit output, result budgeting, and toolset visibility.

If the tool is exposed through RPC or dashboard setup, add tests at that boundary too.