audit

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context on top: it auto-detects the surface, fans out to the appropriate audit set, and accepts a project for taste binding. It does not discuss every possible caveat, but it does not hide any significant side effect either.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: it begins with the purpose, then explains the detection/fan-out behavior, then gives the actionable warning to prefer this over granular audit tools. There is no filler or redundant restatement of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a wide-dispatch tool with no required parameters, the description is strong because it defines the accepted target types and the relevant check families. However, it doesn't explicitly state that at least one target input should be provided, which matters since all 10 parameters are optional. The wealth of the schema mostly compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already self-documenting. The description contributes general context like 'target' and 'project' taste binding, but most of that meaning is already expressed in the schema. It adds little about parameter formats, precedence, or combinations beyond what the schema communicates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action — 'Run all applicable Raven audits for a target' — and explains the scope with a concrete verb and resource. It also distinguishes the tool from its siblings by explicitly telling agents not to pick individual audit_* tools. This makes the tool's role as an umbrella dispatcher unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives direct usage guidance: use this instead of choosing individual audit_* tools. It also explains how the surface is detected and which check families run per surface, so an agent knows this is the right entry point for broad audits rather than for a single focused check.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.