validate_against_gold

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

With no annotations, the description carries the full behavioral burden, and it does so well: it discloses that agreement is computed per leaf, that the pooled figure is orientation-only, that the human coding is the reference standard, and that a span-keyed disagreement list is produced. It does not discuss side effects or error conditions, but 'Compute' implies a read-only analysis and the output schema presumably covers return structure.

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?

Three dense sentences with no filler: the first states what is computed and the metrics, the second clarifies the per-leaf vs pooled distinction, and the third defines both parameters. Every sentence earns its place and important scope qualifiers are front-loaded.

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 the output schema exists, the description is not required to explain return values, and it provides the essential input relationship and reference-standard orientation. Minor gaps remain around exact required fields inside the array objects and potential constraints like same-length or spec-version matching, but the description is sufficiently complete for a generic-object validation 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?

Schema coverage is 0%, so the description must compensate. It names both arguments, states they are arrays of objects, identifies their roles ('instrument' vs 'human_codings'), and clarifies that they share manuscript ids and spec version. It does not enumerate individual object fields, but since the schema uses additionalProperties: true, there is no structured field detail to compensate for.

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 ('Compute') and a precise resource ('per-leaf agreement between instrument assessments and human gold-standard codings'), then enumerates the concrete metrics produced. This clearly distinguishes it from the parse/render/assess/aggregate sibling tools, none of which perform gold-standard validation.

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 clearly establishes when this tool is appropriate: when you have instrument assessments and human gold-standard codings to compare. It does not name alternatives or explicit exclusions, but the context is unmistakable given the siblings are all about parsing, rendering, assessing, or aggregating—not validating against gold standards.

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