run_rest_api_scan

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

With no annotations, the description carries the full burden of explaining behavioral traits. It lists what is evaluated but does not disclose whether the tool modifies anything, what output format to expect, if it's read-only, or any side effects. This is a significant gap for a scanning tool.

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 a single, front-loaded sentence that enumerates the specific compliance checks without any filler. It is efficient and well-structured for a tool that only needs to state its purpose.

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?

The tool is moderately complex with two undocumented parameters, no output schema, and no annotations. The description only covers the checks performed, leaving out parameter guidance, result semantics, and operational context, so it is incomplete for an agent to invoke confidently.

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 schema description coverage is 0%, and the description makes no mention of the two parameters (strictMode and includeRoutes). The agent has no explanation of how these parameters affect the scan, making it impossible to reason about their usage or values.

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 clearly identifies the tool's function: evaluating REST endpoints for specific compliance issues like pagination, state-mutating GETs, and raw stack traces. It distinguishes itself from sibling tools by focusing on HTTP compliance and REST-specific concerns, making its purpose unambiguous.

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 implies this tool is for REST API scanning based on the name and the listed checks, but it does not explicitly state when to choose it over alternatives like run_security_scan or run_vulnerability_scan. No exclusions or alternative usage scenarios are mentioned, so guidance is implied rather than stated.

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