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

The description goes far beyond the annotations: it explains the one-shot, non-idempotent nature, that findings are posted for human triage and no fixes are applied automatically, that the action is billable, that only one audit can be in-flight per project, and that triggering is disabled unless the project is on an operator allowlist. It complements the annotations (readOnlyHint false, idempotentHint false) without contradicting them.

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 opens with a clear one-sentence purpose, then uses scannable paragraphs for behavioral details, constraints, and prerequisites. Every sentence adds meaningful information: taxonomy content, workflow, billing, in-flight limit, allowlist, and plan requirement. There is no filler and no repetition of annotation-schema data.

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 complex security-review tool, the description is remarkably complete: it covers the input, the analysis scope, the output destination, the human-in-the-loop workflow, filtering, cost, concurrency, and access restrictions. The output schema provides return details, and the description fills in operational context that the output schema cannot express.

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?

With only one parameter and 0% schema description coverage, the description compensates partially by repeatedly referencing 'project' (project's Security review, one audit per project, project allowlist). It does not explicitly say 'project_id is the identifier of the repository to scan', but the single parameter is simple and the context strongly implies that meaning. A more explicit mapping would be ideal, but it is adequate for a single-parameter tool.

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 uses a specific verb-resource combination ('Find security problems in a repository') and immediately distinguishes the tool from siblings like run_control_gap_review and run_legal_exposure_review by emphasizing a deep, whole-codebase security audit. It also names concrete categories (secrets, deps, injection, SSRF, etc.) that pin down its unique scope.

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 clearly states when to use the tool (to find security problems, including specific vulnerability classes) and gives operational constraints (billable, one audit in-flight, allowlist gating, paid plan). It does not explicitly name alternative tools or say 'use run_control_gap_review for compliance gaps', but the context of sibling tools makes the intended use reasonably clear.

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