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

The description adds a valuable non-obvious behavior: 'Missing observations remain null, never implicit zero.' This goes beyond the annotations, which only declare the operation as read-only, idempotent, and non-destructive. It informs the agent about data representation, which is critical for interpreting results. The description does not contradict annotations.

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, tightly worded sentence that states the core purpose and a key behavioral caveat. No filler or redundancy. The most important information (purpose and null handling) is front-loaded. It earns its place entirely.

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 presence of an output schema, the description does not need to explain return values. It covers the primary action and a critical data-representation detail. The only missing piece is explicit usage context, but that is already scored low under usage guidelines. For a read-only tool with strong annotations and schema coverage, the description 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?

Schema description coverage is 100%, so all three parameters (corpus, audit_id, include_published) are already documented in the schema. The description does not add parameter-level details beyond what the schema provides. It mentions 'dated observed quality metrics' but that relates to the output, not the parameters. Baseline 3 applies because the schema carries the full load.

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 clear verb-resource pairing: 'return dated observed quality metrics'. It distinguishes from published figures, which hints at differentiation from sibling tools like corpus_stats or compare_corpora, though it does not name them explicitly. This is clear but not as sharply differentiated as the calibration example.

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?

No guidance is given on when to use this tool versus alternatives. It does not mention context, exclusions, or a preferred use case. The mention of 'separately from published figures' implies a distinction but does not state when to choose this over corpus_stats or compare_corpora. An agent would infer usage from the name and parameters rather than from explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds a small behavioral detail beyond annotations — that the result includes parents of derivatives — which is useful. It doesn't contradict annotations, and given the rich annotation coverage the bar is lower, so a 3 is appropriate.

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?

A single, front-loaded sentence with zero filler. The one qualification (including parents of derivatives) is placed where it adds value. It is lean without being under-specified to the point of meaninglessness.

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 a single well-documented parameter, an output schema present, and full annotation coverage, the tool is largely self-documenting. The thin description is adequate but leaves behavioral specifics like output shape and scope unaddressed; the 'including parents of derivatives' hint covers part of that, but not all.

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 100%, and the sole parameter 'corpus' already carries a description ('Variant key.'). The description adds nothing about how this parameter is used or validated, so it sits at the baseline 3 where the schema does the heavy lifting.

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 gives a specific verb (Return) and resource (licence and citations), plus an informative qualifier about including parents of derivatives. This is clear enough for an agent to guess its purpose, though it doesn't explicitly differentiate itself from siblings like audit_corpus or corpus_stats, which a reader might conflate with it.

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?

No guidance is given about when to use this tool versus any of the seven siblings such as audit_corpus or corpus_stats. An agent must infer context from the name and description alone; there is no statement of when not to use it or which alternative fits which scenario.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the specific comparison dimensions, which is a form of scoping that slightly goes beyond the annotations. However, it does not disclose any additional behavioral traits (e.g., output format, performance, rate limits) and is mostly a restatement of purpose.

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, concise sentence with no fluff. It front-loads the core verb and resource, and lists the key comparison dimensions efficiently. There is no wasted text or redundancy.

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 is relatively simple with one parameter, and an output schema exists (so return values are presumably documented elsewhere). However, the description leaves the exact meaning of 'corpora' strings ambiguous and offers no connection to sibling tools like list_corpora for obtaining valid values. It is functional but not fully complete for an agent unfamiliar with the domain.

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 must compensate for explaining the 'corpora' parameter. While the tool name and description imply that each string is a corpus identifier, it doesn't clarify whether these are names, IDs, or paths, nor how to obtain them. This is minimal added meaning over the raw schema type.

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 ('Compare') and a specific resource ('corpora') with enumerated dimensions (variant quality, provenance, licence, benchmark status). It clearly conveys what the tool does, though it doesn't explicitly distinguish it from siblings like 'corpus_stats' which might also cover some of these dimensions.

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?

No guidance is provided on when to use this tool versus alternatives such as list_corpora or corpus_stats. There is no mention of prerequisites, when not to use it, or how it relates to siblings. The usage context is only implied by the verb 'compare'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns rows and schema, which is useful but superficial; it does not disclose potential error behavior, auth needs, or performance implications. Since the annotations carry most of the burden, the description adds moderate value.

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, front-loaded sentence with zero fluff. It immediately states what the tool does and the scope, making it easy for an agent to parse quickly.

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?

For a simple read-only operation with one parameter and an existing output schema, the description is adequate. It defines the tool's function and scope without leaving major gaps. It does not mention edge cases (e.g., what happens if the corpus key is invalid) but those are minor given the tool's simplicity and the presence of an output schema.

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 fully documents the sole parameter (corpus: 'Variant key.') with 100% coverage. The description does not add any parameter-specific meaning, so the baseline score of 3 applies—the schema already does the heavy lifting.

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 action (“Return”) and resource (“rows and schema for exactly one declared dataset configuration”), which clearly distinguishes it from siblings like list_corpora (which lists datasets) and search_segments (which searches within data). The phrase 'exactly one' further narrows the scope, making the tool's purpose unambiguous.

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 you need both the data and structure of a specific dataset configuration—but it does not explicitly state when to choose this tool over alternatives, nor does it mention any exclusions. The usage context is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and mutability. The description adds a useful behavioral trait: that aggregated audit totals alone trigger a structured refusal. This goes beyond annotations and helps the agent anticipate failure modes. However, it doesn't disclose success behavior, pagination, or return structure, though an output schema exists.

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 sentence, so it's concise and not bloated. However, it's cryptic and not well-structured—it reads like an error condition rather than an overview. It's front-loaded with the condition but the phrasing is convoluted. It earns its place by adding behavioral info, but clarity suffers.

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 tool has 8 parameters, 1 required, and an output schema, the description is severely incomplete. It doesn't explain what the tool does with segments, what filters apply, or how output is organized. The output schema covers return values, but the description lacks essential context about the operation's purpose and scope. The precondition about audit manifests is useful but insufficient.

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 only 38%, with split, corpus, and min_quality having descriptions. The description text itself provides no explanation for any parameter (limit, query, exclude_* flags). With low schema coverage, the description should compensate, but it doesn't mention parameters at all. This leaves the agent guessing about parameter meaning and usage.

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 name 'filter_segments' implies filtering rows/segments, and the description begins with 'Filter rows', so the core action is present. However, it doesn't specify what criteria filter on (quality, duplicates, etc.) or what makes it distinct from search_segments. The description is more about a precondition than a clear statement of purpose.

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 gives no guidance on when to use this tool versus alternatives like search_segments or list_corpora. It only mentions a precondition (versioned row-level audit manifest), which is a behavioral constraint, not a usage guideline. No exclusions or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful context that the listing surfaces audit/verification state, but it omits scope details like pagination or result limits. Consistent with annotations; no contradiction.

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?

A single ten-word sentence with zero filler. The verb and core output are front-loaded, and nothing needs to be trimmed.

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?

For a simple listing tool with full schema coverage, rich read-only/idempotent annotations, and an output schema present, the description is largely complete. The only real gap is the absence of sibling-routing guidance, which was already penalized under usage guidelines.

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 all three parameters (task, language, include_derivatives) are already documented. The description loosely hints at the filters via 'language/task/config variants' but adds no syntax or format detail beyond the schema. Baseline 3 applies since the schema does the heavy lifting.

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-resource pair ('List ... variants') and tells the agent what kind of data is returned (language/task/config variants plus audit and verification state). It does not explicitly differentiate from siblings like audit_corpus or corpus_stats, so it misses the top score.

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?

There is no guidance on when to use this tool versus alternatives. With siblings such as audit_corpus, corpus_stats, and compare_corpora, an agent gets no help deciding between listing state and performing an audit or computing stats. Only implicit usage is conveyed by the verb 'List.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds context about the data source (published or dated audit metrics) and the decision areas (quality, licence, benchmark, language-purity), which is useful but does not disclose any additional behavioral nuances beyond what annotations state. It does not contradict the annotations.

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-constructed sentence that immediately states the core purpose and key differentiators. There is no redundancy or filler; every phrase contributes to understanding the tool's function. It is appropriately concise and front-loaded with the main verb and object.

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 8 parameters but no required ones, an output schema, and safety annotations covering read-only/idempotent behavior. The description provides sufficient purpose and input context for an agent to infer how to invoke it, and the output schema handles return values. However, it does not explain the concept of a 'variant plan' or detail how the quality/licence/benchmark/language-purity decisions are made, which could be ambiguous for an unfamiliar agent. Given the complexity, this is a minor gap, so a 4 is appropriate.

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 88%, so most parameters already have explanatory text in the schema. The description mentions 'published or dated audit metrics' which maps to the metric_source parameter, and 'language-purity' aligns with include_mixed_language, but these are not elaborated beyond the schema's own descriptions. The description adds high-level context but does not meaningfully clarify individual parameters beyond what the schema already provides.

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 purpose: to build a de-duplicated variant plan, using audit metrics and making explicit decisions on quality, licence, benchmark, and language-purity. The verb 'build' and specific resource 'variant plan' differentiate it from sibling tools like list_corpora, search_segments, and filter_segments, which perform more basic operations. It is specific enough for an agent to understand what the tool accomplishes, though it does not elaborate on what a 'variant plan' entails.

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 de-duplicated variant plan with explicit quality and language-purity decisions is needed—but it does not explicitly mention alternatives or conditions when other tools (e.g., filter_segments, corpus_stats) would be more appropriate. No exclusions or contrasting guidance is provided, leaving the agent to infer usage from context rather than clear direction.

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

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

Annotations already declare readOnly/idempotent/destructive status. The description adds specific behavioral constraints (config cannot cross language boundaries, ephemeral audio URLs) that go beyond the annotations, providing some useful context, though limited in scope.

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 concise (two sentences) but not front-loaded with a clear purpose. The first sentence is vague, and the second adds peripheral constraints without enriching the core definition.

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?

For a search tool with 5 parameters and an output schema, the description lacks essential context about search semantics, parameter combinations, and result interpretation. It does not suffice to guide correct usage without additional documentation.

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 60%, and the description does not clarify the remaining parameters. The mention of config overrides hints at the config parameter but does not map parameters to their roles, leaving agents to infer meaning from names and schema defaults.

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 the verb 'Search' and a resource ('a schema-verified variant'), but 'variant' is ambiguous and not tied to the tool's name 'segments'. It does not clearly explain what is searched or what results look like, offering only a weak distinction from siblings.

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?

No guidance is given on when to use this tool versus alternatives like filter_segments or compare_corpora. The notes about config overrides and audio URLs are operational constraints, not usage direction.

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