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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these with 'Every call is read-only and idempotent' and expands on error behavior: 'never raises a protocol error — it returns {"error": "..."}'. This adds practical behavioral context beyond the annotations, covering safety and error handling.

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 structured in clear, well-organized paragraphs: purpose, capabilities, output format, usage guidance, and error behavior. Every sentence adds meaningful information without redundancy. Despite being multi-paragraph, it is efficiently front-loaded with the core action and quickly orients the agent.

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?

With a single parameter and an existing output schema, the description covers all necessary aspects: input format, output structure (with example), error handling, usage constraints, and safety guarantees. The mention of OWASP classes and fix direction provides a clear picture of what the tool returns. No gaps are evident.

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?

The input schema has only one parameter, 'code', with 100% schema description coverage. The description adds meaning by providing a concrete example of typical input ('{"code": "<file contents>"}') and clarifies that the input expects 'Full source text to audit, pasted as a single string; any common language.' This goes beyond the schema's brief description by giving usage context and format expectations.

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 explicitly states the tool runs an 'OWASP-oriented security pass over a source file' and lists specific vulnerability categories (injection, auth, crypto, SSRF, file handling). It distinguishes from siblings by noting it is not for 'style or structure (complexity_report)' and implicitly differentiates from secret_scan and ai_code_smell_scan. The verb-resource combination is clear and specific.

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 advises 'Use on one source file when vulnerabilities are the question' and explicitly states when not to use it: 'Not for style or structure (complexity_report), and never a substitute for a security professional on high-risk code.' This provides clear context for tool selection and excludes alternative uses, giving the agent actionable guidance.

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