rca_analysis_compare

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context beyond annotations: it returns raw JSON for programmatic use, names the output fields (consensus_causes, model_disagreements), and documents the not_found failure mode for invalid or foreign result_ids.

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 first two sentences are punchy and front-loaded: behavior first, differentiation second. The Args/Returns section is a bit redundant with the schema (repeating result_ids constraints), but the block is compact and organized, so it doesn't become bloat.

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 description covers the core comparison behavior, the alternative rendering tool, the source of result_ids, the return format, and the not_found error condition. Coupled with the output schema and safety annotations, an agent has everything it needs to decide whether and how to invoke this tool.

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%, so the description needed to compensate by explaining all parameters. It only addresses result_ids (and mostly repeats the schema's own phrasing), while token and client_id are not mentioned in the description. The Args line is also slightly misleading because it presents 'params' as if it were result_ids rather than an object containing multiple fields.

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 opens with a specific verb ('Compare') and a precise object ('multiple RCA results'), and enumerates what the comparison surfaces: overlapping root causes, confidence agreement, and model disagreements. It also explicitly contrasts itself with rca_report_compare, so an agent can distinguish it from the closest sibling without inspecting schemas.

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 explicitly instructs using rca_report_compare when a rendered markdown/HTML document is desired instead of raw JSON, and identifies where result_ids come from (rca_analysis_run or rca_analysis_list_results). This is clear 'when to use this vs alternative' guidance.

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