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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral details beyond that: the FILTER mark behavior, template path resolution (both template and filled paths resolve to same dataset), and the inclusion of equivalent R/Stata code in the output. No contradictions. This exceeds the baseline and earns a 4 for adding meaningful behavioral context beyond 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 well-structured and front-loaded: a concise first sentence summarizing the output, followed by a crucial behavioral note about FILTER marks, then a clear 'Args' section. Every sentence earns its place — there is no fluff or repetition. The length is appropriate for the tool's complexity.

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 an output schema (has output schema: true), the description doesn't need to detail the return structure, but it still lists the content types. It explains the path parameter flexibility, filter behavior, and the presence of R/Stata code. Annotations cover safety. Nothing an agent needs to call this tool correctly is missing.

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 fully explain parameters. It does: 'path' is described as a dataset path, template or filled, with concrete examples, and 'filterable_only' is described as showing only variables usable as filters. This adds meaningful meaning beyond the raw schema, fully compensating for the coverage gap.

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 ('Inspect') and resource ('one dataset'), then enumerates exactly what it returns: variable definitions, data types, coded-value format, filterability, years covered, source description, and equivalent R/Stata code. It also explicitly ties to the [FILTER] marks, distinguishing it from siblings like get_data or search_datasets by describing its unique role in revealing filterable fields.

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 provides clear context on when to use this tool: it is 'where the [FILTER] marks come from' — implying that when the agent needs to know which fields are filterable before querying data, this is the tool. It also warns about behavior ('filtering on anything else returns UNFILTERED data rather than an error'), effectively telling the agent to consult this tool to avoid incorrect filtering. It doesn't explicitly name sibling tools, but the guidance is strong.

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, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral details: results are complete or refused, never truncated; queries over 10,000 rows are refused with true size and narrowing suggestions; a cost warning about 30s+ latency; preview rows are not random samples; decoding is field-specific. These go well beyond 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 long but every sentence carries essential information. It front-loads the core purpose and alternative guidance, then behavioral notes, then cost, then parameter details in a structured Args list. While dense, the structure makes it scannable; the length is justified by the tool's complexity.

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's complexity (5 params, no schema descriptions, output schema present), the description covers all necessary context: when to use, cost, refusal behavior, sampling caveats, and parameter semantics. An agent has everything needed to call it correctly and avoid misuse.

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 is the sole source for parameter meaning. It explains path (with placeholder syntax and optional leading slash), filters (with example, only [FILTER] fields work, ordering semantics), fields (with example and strong advice to always pass), add_labels (default and caveat), and preview (non-random sample caveat). Each parameter is thoroughly documented.

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 'Fetch raw data records from one dataset path' — a specific verb, resource, and scope. It explicitly distinguishes from get_summary ('For totals or averages across groups use get_summary instead'), so an agent can tell it apart without opening the schema.

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?

It explicitly directs when to use get_summary for aggregation, and suggests narrowing or using the bulk CSV link from refusal or the R/Stata snippet from describe_dataset for large analyses. It also advises filtering before fetching rather than issuing many wide calls in parallel, providing clear alternatives and context.

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 substantial behavioral context beyond annotations: 'Results are COMPLETE or refused' (failure mode), 'this hits a live API and a broad aggregation can take 30s+' (performance), 'Guessing costs a slow round trip; reading them does not' (latency cost), and 'The API cannot rank aggregates' (capability limit). It also reveals that 'EVERY year comes back in one call' and that the API refuses groupings producing too many groups. This is rich disclosure that materially helps the agent.

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 dense but every sentence earns its place. It is front-loaded with purpose and usage, then moves into behavioral constraints, performance cost, and parameter semantics. The Args section is clearly structured. Given the tool's complexity and the need to compensate for the lack of schema descriptions, the length is appropriate — there is no fluff or repetition.

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 tool with 5 parameters, 0% schema descriptions, and no enums, the description covers everything an agent needs: purpose, usage, exclusions, behavioral constraints, failure modes, performance, and parameter semantics. It also names alternative tools and explains when to use them. Since an output schema exists, it does not need to describe return values. No critical information is missing.

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% — no parameter descriptions are provided in the input schema. The description fully compensates by explaining every parameter in the Args section with concrete examples and constraints: path ('The SUMMARY path — no year, no {placeholders}, e.g. schools/ccd/enrollment'), var ('the measure to aggregate — a numeric, non-filter variable'), stat (lists the allowed values), by (examples 'fips' and 'fips,race' plus directory variables), and filters (examples with year and fips). This is exactly what the agent needs to construct valid calls.

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 precise statement of what the tool does ('Aggregate a dataset server-side: counts, sums, averages by group') and immediately differentiates it from the sibling get_data by stating 'Use this rather than get_data whenever the question is about totals.' This gives the agent a clear verb, resource, and scope, and explicitly names the alternative it is not.

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 provides explicit when-to-use guidance ('Use this rather than get_data whenever the question is about totals'), plus concrete exclusions and alternatives: 'NO COUNTY AGGREGATION... fetch the rows with get_data and aggregate them yourself,' and 'Do not retry with county in by.' It also explains when to filter years and warns that 'The API cannot rank aggregates' and 'refuses groupings that produce too many groups.' These are clear usage rules and alternatives.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond that: its role in supporting get_data and that omitting 'codes' returns all values. This is useful supplemental transparency without contradicting 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 concise and front-loaded: the main purpose and example appear in the first sentence, followed by clear parameter definitions. No wasted words; every sentence earns its place.

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?

An output schema exists, so return format is covered there. The description provides everything an agent needs to call the tool correctly: purpose, parameter semantics, and the key behavior of omitting codes. It is complete for a lookup helper with these annotations.

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 carries the full burden for parameters. It completely explains format_name ('The "Format" shown for a variable in describe_dataset' with examples) and codes ('Comma-separated codes to look up — "6,48". Omit for all values.'). This fully compensates for the schema's lack of descriptions.

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 and resource: 'Look up the code-to-label mapping for a coded variable' and immediately ties it to a concrete use case with an example ('"California" -> fips=6'). This clearly differentiates it from sibling tools like describe_dataset or get_data. The purpose is unmistakable.

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 says 'mainly to find a filter value for get_data', giving clear primary context and the example reinforces when it applies. It lacks an explicit 'when not to use' or alternatives, but the main scenario is well conveyed. A 4 is appropriate for strong context without explicit exclusions.

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 mark readOnly/idempotent/non-destructive; the description adds substantial non-obvious behavior: candidate-style returns, type-word stripping, state-asking rather than guessing, and 10-30s first-call cost with caching. 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?

The description is long but every sentence carries operational value, with the core task front-loaded and behavior/cost notes structured before Args. No filler or repetition beyond the necessary Args section.

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 4-parameter resolution tool with an output schema, it covers matching semantics, fips dependency, latency/caching, batching advice, and candidate interpretation. Nothing essential is missing for correct invocation.

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%, but the Args section explains every parameter: name's distinctive-word advice, entity_type's allowed values, fips's conditional requirement and lookup pointer, and max_results default. This fully compensates for the empty schema descriptions.

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?

Opens with a specific verb+resource: 'Resolve a school/district/college NAME to the ID used in get_data filters,' which positions it clearly against get_data and lookup_codes. It also distinguishes itself by stating it returns candidates, not an authoritative answer, because names repeat.

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?

Tells the agent this feeds get_data filters and that fips is required for schools/districts, with a pointer to lookup_codes. It provides clear context but stops short of explicit when-not-to-use/alternative selection among sibling tools.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description explains that all arguments are optional filters and that search matches per-token rather than as a phrase. It also warns about likely-empty results for grade-level terms, adding useful behavioral context.

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 front-loaded with purpose and return shape, followed by a compact Args list. The NOT COVERED paragraph is longer but earns its place by preventing wasted searches. No filler or redundant restatement.

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 an output schema present, return values need no lengthy explanation. All four parameters are documented, the key sibling routing is provided, and known coverage gaps are spelled out. An agent has everything needed to invoke this tool 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 0%, so the description carries the full burden, and it delivers: each parameter gets concrete allowed values or examples, and 'search' gets a detailed matching semantics explanation. This compensates fully for the bare 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?

States a specific action ('Find datasets') on a clear resource ('Education Data Portal'), and describes the result: each dataset's path template, description, and years available. It also routes the agent to describe_dataset when variables are needed, which helps distinguish it 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?

Explicitly says to pass a template to describe_dataset for variables and summary calls, and lists domains not covered by the portal so the agent should not search repeatedly. This gives clear when-to-use and when-not-to-use guidance.

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