owasp_scan__owasp_scan_path

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

With no annotations at all, the description carries the full disclosure burden. It does useful work by revealing that this is a compound/orchestration operation rather than a single check and by naming the output shape (A–F grade). It says nothing about runtime cost despite fanning out to seven auditors, whether the scan is read-only, whether results are persisted, or what maxFiles limits do when exceeded.

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?

A single dense sentence with the action front-loaded, the orchestration list in the middle, and the return value last. No filler, no restatement of the tool name.

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 4-param, no-annotation, no-output-schema tool, the description covers what is scanned, that it is an aggregate, and the output form (letter grade), which is the key information an agent needs. The remaining gap is the optional parameters — especially discoverShadow's host-level side effect — which an agent cannot reason about from the description alone.

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 75%, just under the high-coverage threshold, and the description adds no parameter meaning at all. The undocumented `maxFiles` (no schema description) and the non-obvious `allowlistPath` / `discoverShadow` semantics — notably that discoverShadow ties to MCP09 host discovery and needs an allowlist — are left entirely to the schema.

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?

Specific verb+resource+scope: "Run a unified OWASP MCP Top 10 scan over a filesystem path." It then enumerates the auditors it orchestrates (secret, server, oauth, audit-gap, context-oversharing, toxic-flow, tool-poisoning) and the return value (A–F grade), which clearly separates it from the single-purpose sibling scanners like secret_scanner__scan_directory or oauth_auditor__scan_file.

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 word "unified" and "orchestrates" imply this is the one-shot aggregate over many individual auditors, giving clear usage context against ~100 single-scanner siblings. However, it never explicitly states when to choose it over closely related siblings such as owasp_scan__owasp_scan_live, owasp_scan__owasp_scan_catalog, or owasp_scan__list_owasp_coverage, and offers no exclusion criteria (e.g. cost, when a targeted scanner is preferable).

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