probe_report

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

Annotations already declare readOnlyHint=false and openWorldHint=true, which covers the possibility of side effects. The description offers additional context about the report format and that fuzz runs only when requested, which implies a safety guard. However, it does not explicitly warn about the potential destructive effects when fuzzDestructive=true, though the schema parameter description does. This is an adequate but not thorough disclosure.

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, information-dense sentence. It front-loads the main verb and quickly enumerates all key output components. While it is a bit long, it contains no filler words and every clause adds useful information. The structure is acceptable for a tool that performs a multi-step process.

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?

Given moderate complexity (4 optional parameters, no output schema), the description adequately explains the tool's purpose and the content of its returned report. It covers the key aspects of what the report includes and mentions the optional fuzz component. However, it could be more explicit about preconditions like needing a connection (connectionId) and about the four dimensions being scored, but these are partially covered by schema and context. Overall, it is reasonably 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?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema already provides, such as the meaning of fuzz, maxTools, connectionId, or fuzzDestructive. It only indirectly references fuzz via 'when requested', but this adds no new meaning.

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 states the tool's composite function: running introspect + lint (and optionally fuzz), scoring results on four dimensions, and returning a Markdown report with specific components (overall score, letter grade, breakdown, findings, fuzz table). The verb 'Run... score... return' is specific, and the resource is the target. This distinguishes it from siblings like probe_lint and probe_fuzz, which are individual operations.

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 when to use this tool: when a comprehensive scored report is needed rather than just lint or fuzz. However, it does not explicitly say 'use this instead of probe_lint when you need scoring' or mention any exclusions. The guidance is clear from the context but lacks explicit alternative differentiation.

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