Compare a run against a baseline

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context by explaining the comparison logic (score drop > threshold or pass->fail flip) and implying dependence on the output of llmeval.run. It does not contradict the annotations and goes slightly beyond them by detailing the filtering condition, though it does not disclose potential performance characteristics or file-format requirements.

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 two sentences with zero filler. The first sentence states the core action and output condition, front-loading the most important information. The second sentence provides usage guidance, also concise. The structure is efficient and easy to scan.

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 has four parameters, two required, and an output schema exists (per signals). The description clearly explains the purpose and usage, including a prerequisite ('after llmeval.run'). It doesn't need to explain return values since an output schema exists. It could mention file-format expectations or error conditions, but these are either implied or covered by the schema. Overall, it's sufficiently complete for an agent to use correctly.

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 100%, so the schema already documents all four parameters (repo, current, baseline, threshold) with clear descriptions. The tool description mentions 'threshold' but only repeats what the schema says ('Score drop that counts as a regression; the harness default is 0.10'). It adds no new meaning beyond the schema, so the baseline score of 3 is appropriate.

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 states a specific verb ('Compares'), the resource ('two llm-eval-harness result files'), and the exact output condition ('cases whose score dropped by more than the threshold or that flipped from pass to fail'). It also differentiates from the sibling llmeval.run by explicitly saying 'Use it after llmeval.run', so an agent can tell it apart without ambiguity.

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 tells when to use the tool: 'Use it after llmeval.run to see whether a prompt change or model upgrade regressed anything.' This provides clear context and names the prerequisite tool, effectively guiding the agent on when this tool is appropriate and when it is not (e.g., before a run). No other exclusions are needed.

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