get_scan_prompt

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

No annotations exist, so the description carries full burden — and it comprehensively delivers. States 'Read-only; no side effects' upfront, details what each kind returns, what's excluded (implemented controls), and how control_id scopes output to one control or all. No contradictions with any structured fields.

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?

Approximately 300 words — long but dense for a two-mode tool; front-loaded with purpose and read-only guarantee, with clear '─' section dividers for each kind. Every paragraph earns its place, though minor redundancy exists in repeating kind semantics across sections.

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 tool with two distinct modes, downstream integrations, and filtering rules, the description fully covers behavior, parameter usage, and follow-up workflow. Output schema exists so return-value explanation would be redundant; nothing material is left unexplained.

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 covers 75% of params, but the description significantly elevates kind and control_id beyond their schema stubs by explaining semantic differences, defaults, and the ignored-when-functional behavior. model_id and server_version rely on schema alone, which is adequate given their self-explanatory names.

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?

Description opens with a specific verb+resource ('Get guidance prompts for scanning a codebase') plus an explicit read-only declaration. It distinguishes itself from siblings by enumerating two distinct output kinds (security vs. functional) and exclusions (only NOT_IMPLEMENTED controls), clearly separating it from get_review_queue and get_functional_coverage.

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?

Offers explicit when-to-use guidance per kind: 'Use this to drive a gap-discovery pass' for security and 'Drive test implementation from it' for functional. Names four downstream tools (submit_findings, submit_assertions, submit_functional_test_assertions, get_functional_coverage) and clarifies when control_id applies (security only; ignored for functional).

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