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

With no annotations, the description carries the full behavioral burden and does much of it: it discloses payload redaction, report storage, dedup by bug hash, insertion of SECURITY bugs, and explicitly states the postcondition it does NOT perform (marking the scan COMPLETED). Missing only auth/permission requirements and failure behavior.

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?

Three tight sentences that front-load the purpose, then invocation, then side effects and postcondition. Every clause adds information; nothing is repeated from the name or 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?

No output schema and no annotations, yet the description covers purpose, parameter passing, backend side effects, and the downstream workflow step an agent must take. For a two-param upload tool this is essentially complete.

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 0% for two required params, so the description must compensate. It ties the params to CLI flags ('--id', '--report-file') and specifies the reportFile format (Gitleaks JSON), but never defines what 'id' identifies (scan id, project id?) or gives the expected file path form.

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 and resource: 'Upload a full Gitleaks JSON report for a secrets security scan.' The 'Gitleaks'/'secrets' framing cleanly separates it from the sibling report-sast-findings, report-dast-findings, and report-deps-findings tools without opening any schema.

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 invocation ('Pass --id and --report-file <path>') and, crucially, the workflow ordering: it does not mark the scan COMPLETED and the playbook calls update-scan-progress COMPLETED afterward. That routing guidance is strong, though it stops short of stating when this tool should be used instead of the other report-*-findings siblings.

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