get_rebuild_health_report

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds context about the report's contents but does not disclose additional behavioral traits such as authentication needs, rate limits, or effects on underlying data. The added detail is useful but not beyond what the annotation covers.

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, well-structured sentence that front-loads the tool's main purpose. Every phrase carries meaning: 'compact', 'one reverse task', and the list of report contents. No wasted words.

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?

With no output schema, the description partially explains what the report returns by listing 'env blockers, evidence aggregates, and next fixes'. However, it does not describe the output format, parameter behavior, or any edge cases. For a read-only reporting tool with 3 parameters, it is moderately complete but has clear gaps.

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 for explaining parameters. It only hints at outputMode via 'compact' but does not name or explain taskId, outputMode, or observedCapabilities. The required taskId is implied by 'one reverse task' but not explicitly mapped 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?

The description uses a specific verb 'Produce' with a clear resource 'rebuild health report' and scope 'for one reverse task'. It also lists the report's contents (env blockers, evidence aggregates, next fixes), which distinguishes it from sibling tools like export_diagnostic_bundle or generate_parameter_report.

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 usage when a health report for a specific reverse task is needed, but does not explicitly state when to use this tool versus alternatives or provide exclusions. Sibling tools like auto_rebuild_fix_loop or recommend_next_step are action-oriented, but no direct comparison is given.

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