scan_mcp

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

With no annotations, the description carries the full burden. It does add real behavioral context: tokens and DB URIs are passed indirectly via environment-variable names, and backend_url exists specifically to attempt an auth bypass. It never says whether the scan is purely read-only, whether it writes anything to the target DB, or what happens if a credential env var is unset.

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 purpose is front-loaded in one sentence, followed by a compact aligned parameter glossary with no filler. The parameter list is arguably duplicative of the schema, but since the schema has zero property descriptions this repetition is the only source of that information.

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?

An output schema exists, so return values needn't be described, and the parameter glossary covers a 6-param, all-optional signature well. What's missing is a brief note on depth/cost of a full scan and any side-effect or credential-handling caveat, which matters for a security-scanning tool with no annotations.

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%, so the description must compensate, and it does: all six parameters are explained, including an explicit URL example for mcp_url and the non-obvious semantics of token_env/db_env as variable names rather than secrets. The 'role' default of 'the token' in the schema is slightly clarified by 'label for that role, used in the report text', though the interaction between role and token_env is not spelled out.

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 first sentence gives a specific verb (scan) and resource (an MCP endpoint plus the question server, DB user and Toolbox config behind it) and states the output shape ('plain-English report of what a model could reach'). It doesn't explicitly name scan_local_program or list_checks as the alternatives, so sibling differentiation relies on inference from the parameter names.

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 marks four parameters as optional and frames them as deepening the scan (the backend 'to test the bypass'), which implies a shallow-vs-deep usage pattern. There is no explicit statement of when to pick this over scan_local_program or list_checks, and no prerequisites such as needing the endpoint reachable or a token already set in the environment.

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