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

With annotations already declaring readOnly=false, idempotent=false and destructive=false, the description adds meaningful context: the backend parses, dedupes by bug hash, and only inserts new bugs, so re-runs are largely deduped. It also explains the markCompleted side effect. Return format is not described, but that's the main gap.

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?

Front-loads the core action, then concisely maps scanner types and completion behavior. Every sentence is useful, though the CLI-flag notation adds minor ambiguity for an MCP caller.

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 mutation tool with 8 params and no output schema, the description covers the essential behavior (ingestion, dedupe, insertion, completion) and annotations carry the safety profile. It falls short only in not explaining the four undocumented parameters or the response.

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 coverage is only 25% (one param has a description), so the description must compensate. It documents scanner format mappings (ZAP/Semgrep/Trivy/Gitleaks), id, report-file and markCompleted, but uses CLI flag names (--report-file) that don't match the schema (reportFile) and leaves botId, scanId, reportJson and projectApiKey unexplained.

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?

States a specific verb (upload/report) and resource (scanner JSON report for a security scan), and clarifies the backend action (parses, dedupes, inserts new SECURITY bugs). An agent can distinguish it from the sibling update-scan-progress tool because the description explicitly names that alternative for the completion path.

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?

Explains the workflow: use markCompleted=true to set the scan COMPLETED, otherwise the playbook calls update-scan-progress COMPLETED. This routes the agent between this tool and a sibling. It does not, however, state prerequisites or when-not-to-use this tool.

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