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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description does not need to repeat those. It adds the concept of 'known' relationships, implying non-exhaustiveness, which aligns with openWorldHint. No contradictions, but little added insight 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 a single sentence of 9 words, front-loading the key action. It is efficient, but could benefit from a brief second sentence clarifying the parameter or output scope. Nonetheless, it achieves conciseness without waste.

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 lookup tool with one parameter and an existing output schema, the description is minimally adequate. It misses details like error handling or data scope, but for a straightforward retrieval, it passes the bar. Improvement would add context about the return format.

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%. The description mentions 'GHED variable' but the parameter is named 'indicator_code', with no explanation of their relationship. The agent must infer that indicator_code identifies a GHED variable. This is insufficient for low coverage.

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 verb 'return' and the resource 'additive child relationships for a GHED variable'. It distinguishes from siblings like 'explain_indicator_relationship' by focusing on returning existing relationships rather than explaining them. However, 'GHED' is not explained, which assumes domain knowledge.

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 no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it. This leaves the agent without decision support.

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, so no contradiction. The description adds minimal behavioral context beyond the purpose—it does not explain what 'cautions' entails or how the summary is structured. For a read-only tool, this is adequate but not rich.

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 very concise with no wasted words. However, it is too brief given the tool's complexity, sacrificing necessary details for brevity. A few more sentences would improve completeness without harming conciseness.

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 lacks context about the output (which has an output schema) and the interplay of filters. Despite having many parameters, no explanation of how they are used together is provided. The tool's complexity demands more descriptive context.

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%, meaning no parameter descriptions exist in the schema. The description only mentions 'indicator/filter' but does not explain any of the 9 parameters, such as geography filters or year range. This is a critical 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 clearly states the action ('Summarize') and the resource ('metadata, availability, and cautions for an indicator/filter'). It distinguishes itself from siblings like 'data_availability' and 'get_indicator_metadata' by combining these aspects.

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 does not provide guidance on when to use this tool versus alternatives. For instance, if only metadata is needed, 'get_indicator_metadata' might be more appropriate; if only availability, use 'data_availability'. No such context is given.

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 and openWorldHint. The description adds specific behavioral context: if complete is false, the identity cannot be validated even when components sum nearly to the total, and missing components are not zero or implicitly included. This aligns with the openWorldHint and provides useful nuance beyond 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 two concise sentences, front-loaded with the primary purpose. It avoids repetition and each sentence earns its place by adding either the core action or critical behavioral caveats.

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?

Although an output schema exists (so return format is covered), the description is incomplete for successful invocation. It fails to explain the parameters, making it unclear what indicator_code, country, year, and relationship_id should contain. The reference to additive_hierarchy is vague without guidance on how to use it. The tool's name implies building a breakdown, but the description only says 'check', creating uncertainty about expected behavior.

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%, meaning no parameter descriptions exist in the schema. The description does not explain any of the four parameters (year, country, indicator_code, relationship_id) or their formats, meanings, or defaults. It only mentions 'country-year' and references additive_hierarchy, leaving the agent without guidance on how to populate the parameters.

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: checking a current-NCU accounting total for one country-year. It names the resource and the action, and references the sibling additive_hierarchy for selecting a relationship, which helps differentiate it. However, the name suggests 'building' a breakdown while the description says 'check', creating slight ambiguity about the primary action.

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 advises using additive_hierarchy to choose a relationship, providing some usage direction. It also explains a condition (complete=false) that affects validation interpretation. However, it does not explicitly state when to use this tool versus alternatives, nor does it give exclusions or alternative tools for similar tasks.

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 provide readOnlyHint=true and openWorldHint=true, so the description's mention of 'build' might imply creation, but the readOnlyHint indicates no state change. The description adds context about the output format (CSV, codebook, README) 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?

A single sentence covers the tool's outputs efficiently. However, it could be slightly more structured (e.g., listing outputs) without adding length.

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 8 parameters with zero description coverage, the description is incomplete. It does not explain parameter usage, valid combinations, or how to configure the export. The output schema exists but does not compensate for missing parameter guidance.

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?

With 0% schema description coverage and 8 parameters, the description offers no parameter-level explanation. For example, it does not clarify the difference between 'countries' and 'country_group' or how 'top' limits rows. This is a significant 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 clearly states the tool produces export-ready CSV data, codebook, and README text for a research extract. This specific verb-output combination distinguishes it from sibling tools like build_additive_breakdown or build_research_panel.

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 the tool should be used when a researcher needs an exportable package of data and documentation, but it lacks explicit guidance on when not to use it or alternatives among many siblings (e.g., get_indicator_data for raw data).

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 annotations (readOnlyHint, openWorldHint), the description discloses that country_group resolves to ISO3 lists and filters combine via SQL AND, offering behavioral insight into parameter interaction. No contradiction with annotations 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 concise, using two sentences to convey purpose and key parameter behavior without extraneous detail. It is well-structured with a clear main statement followed by a specific note on country_group.

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 9 parameters and an output schema, the description lacks completeness by not explaining most parameters or the output format. While annotations cover safety, the description does not fully enable an agent to use the tool correctly, though the existence of an output schema mitigates return value ambiguity.

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?

With schema description coverage of 0%, the description must compensate. It only explains the country_group parameter and the filter combination logic, leaving 8 parameters (indicator_codes, countries, region, income, year_start, year_end, top, format) unaddressed. This is insufficient for an agent to correctly invoke the tool.

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 builds a tidy long panel for multiple GHED variables across countries and years, specifying the resource (GHED variables), action (build panel), and scope (countries/years). This distinguishes it from sibling tools like get_indicator_data which retrieve single indicators, or compare_countries which focus on comparisons.

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 explains how country_group works with curated codes and that filters (countries, region, income) combine via SQL AND, providing context for usage. However, it does not explicitly state when to use this tool vs alternatives, such as when a multi-variable panel is needed versus simple indicator retrieval.

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 and openWorldHint. The description adds valuable behavioral context: it discloses the cache initialization side effect (though read-only) and the performance implication of the first call taking minutes. This is beyond what annotations convey and helps the agent anticipate behavior.

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 sentences, no waste. The primary purpose is front-loaded, followed by essential guidance and an alternative. Every sentence earns its place, and the structure is 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?

With an output schema present, the return format is covered. The description explains the side effect (cache init), performance characteristics, and provides an alternative for update checks. For a parameterless tool, this is fully 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?

There are no parameters, so the baseline is 4. The description correctly omits parameter details since none exist, and there is no additional parameter-related meaning needed. The description adds value through behavioral context, not parameter explanation.

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: it returns cache status and WHO source-document details, and initializes an empty cache. This clearly distinguishes it from siblings like refresh_cache (which refreshes) and check_for_updates (which checks updates without downloading). The purpose is explicit and 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 provides explicit usage guidance: it warns that the first call may take minutes and suggests pre-warming with a terminal command, and it directs users to check_for_updates as an alternative for checking newer data without downloading. This is a clear when-to-use and when-not-to-use with an alternative.

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 indicate read-only and open-world behavior. The description adds context about what is being compared but does not introduce behavioral traits beyond those already captured.

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 that is concise and contains no unnecessary words. Every part contributes to the meaning.

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 absence of parameters and the presence of an output schema, the description is sufficiently complete. It could mention what the output indicates, but the core function is clear.

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?

No parameters exist, so schema coverage is 100%. The description does not need to add parameter information; a baseline of 4 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 clearly states the tool's action ('compare') and the specific resources ('local cache source document' vs 'current GHED all-data file'), distinguishing it from sibling tools like cache_status and refresh_cache.

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 a use case (checking cache freshness) but does not explicitly state when to use this tool versus alternatives like cache_status or refresh_cache.

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?

The description adds context beyond annotations: it mentions output format options (rows vs CSV) and parameter merging behavior. Annotations already declare readOnlyHint and openWorldHint, so the description supplements without contradicting. It does not detail rate limits or other potential behaviors.

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 very concise: two sentences that front-load the purpose, then provide parameter guidance. Every sentence adds value without 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?

Given 8 parameters (1 required) and 0% schema description coverage, the description covers the core parameters but misses several optional ones. Output schema exists, so return values are covered. It is adequate for basic use but not fully 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?

With 0% schema description coverage, the description must explain all parameters. It covers indicator_code, countries, country_group, and format, but not year_start, year_end, latest_only, or top. These omissions leave significant gaps for an 8-parameter tool.

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 it returns 'One GHED indicator across countries' in tidy rows or CSV format. It specifies the core resource (GHED indicator) and action (compare across countries), distinguishing it from siblings like 'compare_country_group' or 'get_indicator_data'.

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 explains how to use countries vs country_group parameters, including that they can be merged, and references list_curated_country_groups for available groups. It does not explicitly state when not to use this tool, but the guidance is sufficient for typical use.

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 and openWorldHint=true. The description adds filtering behavior (AND composition) but does not detail response format or pagination. No contradiction with 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?

Two concise paragraphs: first sentence defines purpose, second explains filter logic. No redundant words, front-loaded with key information.

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 9 parameters and an output schema, the description lacks details on what 'compare' returns (e.g., summary statistics, differences), and omits explanation for year range, latest_only, top, and format parameters. Incomplete for the complexity.

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%. The description explains the key grouping parameters (country_group, region, income) and their composition, but ignores other parameters like year_start, year_end, latest_only, top, and format. Partial compensation for low coverage.

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 verb 'compare' and the resource 'GHED indicator across a country group'. It distinguishes from siblings like compare_countries and summarize_country_group by specifying the grouping dimension (curated, regional, income-based).

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?

Provides explicit guidance: 'Pass at least one of country_group, region, or income' and explains filter composition via SQL AND. However, it does not explicitly state when to avoid this tool or suggest 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?

Beyond the read-only and open-world annotations, the description adds important output semantics: percent_change and cagr are fractions, absolute share changes are percentage points, and the agent should inspect years, warnings, and limits. This helps the agent correctly interpret results and anticipate caveats.

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 compact and front-loaded; the main action is stated first, followed by crucial numeric interpretation notes and a caveat. Every sentence carries useful information, though some phrasing (e.g., 'first/latest summaries') is slightly terse.

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 10 parameters, zero schema descriptions, and no parameter-level guidance in the prose, the description is not complete enough for an agent to confidently set filters and thresholds. The output schema exists and the numeric caveats help, but input semantics remain largely undocumented.

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% and the description does not explain any of the 10 parameters. It references indicators and output metrics, but nothing about country/region filters, year ranges, min_year_count, min_period_years, or top_per_indicator. The description fails to compensate for the complete lack of schema-level parameter documentation.

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 operation ('Compute first/latest summaries') on a specific resource ('several indicators') and explicitly contrasts itself with indicator_trend for a single indicator. This makes its scope clear and distinguishes it from a key sibling tool.

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 tells the agent to use indicator_trend when only one indicator is needed, giving a clear routing rule. It does not discuss other siblings like compare_countries or compare_country_group, but the single-vs-several indicator distinction provides clear enough context for the main alternative.

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 and openWorldHint=true. The description adds that the tool returns 'latest' values, implying currency but not high transparency. No mention of data limits, pagination, or potential warnings, but the annotations cover the safety profile adequately.

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 with no unnecessary words. It is front-loaded and efficient, conveying the core purpose without filler.

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 three parameters, no schema descriptions, and a tool that likely has nuanced optional filtering (year, indicator codes), the description is too sparse. While an output schema exists, the lack of parameter guidance makes the tool significantly incomplete for an agent.

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?

With 0% schema description coverage, the description must explain parameters. It only hints at 'country' implicitly, but does not explain 'year' or 'indicator_codes' meanings, formats, or relationships. This leaves the agent without critical information to use optional parameters correctly.

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 identifies the tool as providing 'latest headline health-expenditure values for one country.' This succinctly states the verb (provides), resource (headline health-expenditure values), and scope (one country), distinguishing it from sibling tools like compare_countries that handle multiple countries.

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 offers no guidance on when to use this tool versus alternatives. It does not mention when not to use it or point to siblings like compare_countries or get_indicator_data for different needs, leaving the agent to infer usage without explicit 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?

The description is consistent with annotations (readOnlyHint=true), indicating a read-only summary operation. However, it adds no behavioral details beyond what the annotations already convey, such as data freshness or pagination behavior.

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 that front-loads the key verb and resource. It is appropriately brief but could benefit from slight elaboration on parameter usage.

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, return values need not be described. However, with 7 parameters and 0% schema description coverage, the description is incomplete for guiding parameter selection. Annotations partially compensate, but parameter semantics are lacking.

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%, leaving 7 parameters completely undocumented. The description mentions 'indicators' but does not elaborate on the meaning or usage of the fields like 'countries', 'region', 'year_start', etc. This is insufficient for an agent to correctly fill parameters.

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 with a specific verb 'summarize' and resource 'availability for indicators', and the context 'before building a research panel' distinguishes it from sibling tools like 'build_research_panel' and 'get_indicator_metadata'.

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 timing guidance ('before building a research panel'), but does not explicitly state when not to use the tool or mention alternatives among the 34 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?

Annotations include 'readOnlyHint: true' and 'openWorldHint: true', providing safety and scope context. The description only says 'explain', which is consistent but adds no behavioral details like whether it requires specific permissions or how it handles missing data. Annotations carry most of the burden.

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 that conveys the core functionality with no wasted words. It is concise and structured optimally.

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 simplicity (one parameter, read-only, output schema present), the description is minimally viable. It explains what it does but lacks usage context. With an output schema, return values don't need explanation, but some guidance on when to use it would improve completeness.

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% (parameters have no descriptions). The description mentions 'variable' but the parameter is 'indicator_code' with no explanation of what should be provided, format, or examples. It does not compensate for the missing 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?

The description clearly states the tool's purpose: 'Explain whether a variable is a total, component, ratio/share, or context series.' It uses a specific verb ('explain') and resource ('indicator relationship'), distinguishing it from sibling tools like 'additive_hierarchy' and 'build_additive_breakdown'.

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 the tool is for understanding how a variable relates to others, but it does not explicitly state when to use this tool vs alternatives like 'additive_hierarchy' or 'build_additive_breakdown'. No exclusions or prerequisites are mentioned.

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 and openWorldHint. The description adds no extra behavioral details such as case sensitivity, partial match behavior, or handling of multiple matches.

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?

Single sentence, waste-free. Could benefit from brief structure or examples, but efficient for the tool's simplicity.

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?

Adequate for a simple lookup tool with output schema and annotations. Missing information on behavior when both parameters are null or conflicting, and no fallback guidance.

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?

With 0% schema description coverage, the description should clarify parameter roles. It mentions search by name, alias, or code fragment but does not map these to the two parameters (country and country_name), leaving ambiguity.

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 finds ISO3 country codes using name, alias, or code fragment. It is specific and distinguishes from siblings that deal with country metadata or listings.

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 on when to use this tool versus alternatives like get_country_metadata or list_countries. No when-not instructions or context for optimal use.

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 this as read-only and open-world, and the description adds non-obvious interpretive caveats: country notes are context, not proof of indicator data type or trend causation, and empty metadata does not establish data quality. This is useful behavioral guidance beyond what the annotations provide.

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 the core purpose and contains no filler. Each sentence earns its place, including the caveats about metadata interpretation.

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 an output schema and read-only annotations, so return-value detail is not required. However, the top parameter remains unexplained, and the relationship to get_indicator_metadata is not clarified, leaving minor gaps for a tool that otherwise relies on clear context.

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 compensate. It indirectly maps indicator_code and country via 'indicator-specific notes' and 'query country alone', but it gives no explanation of the top parameter, its default, or its effect on results. This is only partial parameter coverage.

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 and resource: return source, data-type, and estimation notes from the Metadata sheet. It is clear enough, but it does not explicitly contrast itself with the sibling get_indicator_metadata, so differentiation is more implicit than explicit.

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 guidance on parameter fallback: if no indicator-specific notes exist, query the country alone for broader notes. It does not explicitly name alternatives like get_indicator_metadata or give exclusion criteria, but it gives enough context for an agent to know how to adjust its query.

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 read-only and open-world hints. The description adds behavioral transparency by detailing how spatial filters interact, which goes beyond annotations. However, it does not mention other behaviors like pagination (top parameter) or data freshness, but this is acceptable given 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 concise with two paragraphs: a clear function statement and a focused explanation of spatial filter composition. It avoids redundancy and front-loads the main purpose. Minor improvement could further tighten the second paragraph.

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 complexity (10 parameters, output schema exists), the description covers purpose and spatial filter logic but omits details on temporal filters, pagination, and behavior of the top parameter. The output schema covers return values, but the agent still needs more behavioral context for complete usage.

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 compensate. It explains spatial filter composition (country, countries, country_group, region, income) but fails to describe temporal filters (year_start, year_end), latest_only, or top. This partial coverage leaves gaps for a significant number of parameters.

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 'Fetch one GHED indicator with optional country and year filters', specifying the verb (Fetch), resource (GHED indicator), and available filters. However, it does not differentiate from sibling tools like compare_countries or indicator_trend, which may cause confusion about when to use this tool.

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 explains how spatial filters compose (merge into single country list, AND constraints), providing some guidance on filter usage. But it lacks explicit context on when to use this tool versus alternatives, such as search_indicators or compare_trends.

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 indicate readOnlyHint=true, so the description adds no new behavioral context. It is consistent with the read-only nature, but does not disclose any additional traits like pagination, authentication, or rate limits.

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 with no fluff, efficiently conveying the tool's purpose. It is appropriately 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 tool is simple (one required parameter, output schema exists), the description is adequate. However, it could mention what 'codebook metadata' includes (e.g., definition, source) to improve completeness.

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%, and the tool description does not explain the parameter 'indicator_code' beyond its existence. The description fails to compensate for the missing schema descriptions, leaving the agent with minimal guidance on parameter meaning.

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 returns 'Codebook metadata for one GHED indicator', which is a specific verb-resource combination. It distinguishes from siblings like 'get_indicator_data' (returns data) and 'list_indicators' (lists all indicators), but does not explicitly differentiate.

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 on when to use this tool versus alternatives, such as 'search_indicators' or 'list_indicators', or when not to use it. The description simply states what it does without 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 and openWorldHint, so the description's job is to add context. It explains the units of percent_change and cagr (fractions) and absolute_change (indicator units or percentage points), which is valuable behavioral info. It doesn't cover every edge case but adds meaningful detail 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?

Two sentences, no fluff. The first sentence states purpose and alternative; the second covers units and interpretation advice. Information is front-loaded and each 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?

With 10 parameters, a complex schema, and zero parameter explanation in the description, the tool is severely under-described. The description explains only the core operation and units, but does not address filtering options, output structure, or how the parameters interact. An agent would struggle to use this tool correctly beyond the simplest case.

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%, and the description provides no parameter-specific guidance. The only implied parameter is indicator_code from the main verb, but all 9 optional parameters (top, income, region, year_start, etc.) are left undocumented, forcing the agent to infer their meaning from schema titles alone.

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 verb 'Compute' with a specific resource ('first/latest trends for one indicator') and explicitly differentiates from the sibling tool compare_trends for multiple indicators. This makes 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 explicitly names the alternative tool (compare_trends) and the condition for using it ('for several'), and gives practical guidance on interpreting results by inspecting actual years and change_units before ranking. This is clear and actionable.

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 provide readOnlyHint and openWorldHint. The description adds value by explaining that country_group accepts curated codes and intersects with region/income, clarifying the filtering logic beyond what annotations provide.

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 with two sentences. The first states the core purpose, the second adds crucial behavioral detail. No extraneous or redundant text.

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 and annotations, the description covers the essential purpose and key filtering behavior. However, it does not define all parameters, which is a gap for a tool with 0% schema description coverage. It is minimally adequate but not fully 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?

The input schema has 0% description coverage. The description only elaborates on country_group with examples, but does not define region or income parameters or their accepted values. This leaves significant ambiguity for the agent.

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 'List countries and territories available in GHED', using a specific verb and resource. It distinguishes from sibling tools like get_country_metadata (which provides details) and find_country_code (which maps codes), and adds context about optional grouping.

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 explains when to use the tool (to list countries, optionally filtered by group) and describes the intersection behavior, but does not explicitly state when not to use it or mention alternatives among the many 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?

Annotations (readOnlyHint, openWorldHint) indicate basic safety, and the description confirms a listing operation. However, the mention of filtering by region/income is inconsistent with the parameterless schema, potentially confusing behavior. No additional behavioral traits disclosed.

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 single-sentence description is concise, but the phrase 'by region and World Bank income class' is misleading given the empty parameter set. It earns its place but introduces inaccuracy.

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 no parameters and an output schema present, the description minimally covers purpose. It lacks context about how the output relates to sibling tools or how to use the returned groups. Some detail is missing for full completeness.

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?

No parameters exist (schema coverage 100%), so the description adds value by explaining the tool's purpose (listing groupings by region and income class). This contextualizes what the tool returns beyond the name.

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 lists GHED country grouping values, with a specific scope ('by region and World Bank income class'). However, this implies filtering parameters that do not exist in the input schema, creating a slight mismatch.

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 on when to use this tool versus siblings like list_curated_country_groups or summarize_country_group. The description does not specify context or 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 indicate safe read (readOnlyHint) and no side effects (openWorldHint). The description adds value by specifying the types of groups returned and how to leverage them, but does not detail response format beyond what the output schema likely provides.

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?

Two sentences, front-loaded with purpose and immediate usage guidance. Every sentence adds unique value without 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?

Given no parameters, existing annotations, and presence of an output schema, the description is complete: it explains what the tool does, what it returns, and how to use the results in other tools.

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?

With zero parameters, the description cannot add parameter semantics. Baseline 4 is appropriate as the schema coverage is 100% and no parameter info is needed.

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 it lists Decilion's curated country groupings (WB regions, LDCs, OECD) and explicitly contrasts them with built-in groups, distinguishing it from siblings like list_country_groups and resolve_country_group_membership.

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?

Provides explicit guidance on when to use the tool (for groups beyond built-in) and how to use the returned data (with `members` lists or via resolve_country_group_membership). Lacks explicit 'when not to use' but the contrast with built-in groups implies it.

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 indicate readOnlyHint=true. The description adds that the tool returns only headline indicators (category_1 = INDICATORS), providing useful filtering context. However, it does not disclose pagination behavior or result limits beyond schema defaults.

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-front-loaded sentence that captures the core functionality without unnecessary words. Every word serves a purpose.

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 sufficiently explains the tool's purpose but lacks detail on parameter semantics. Given the presence of an output schema and the simplicity of the tool, it is minimally adequate but has clear gaps.

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%, and the description does not explain the meaning or usage of 'skip' and 'top' parameters. It only provides the titles 'Skip' and 'Top', which are not fully explanatory for an agent.

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 'List headline GHED indicators only (category_1 = INDICATORS)', specifying the verb 'list', the resource 'headline GHED indicators', and a filtering condition. This distinguishes it from sibling tools like 'list_countries' or 'list_variables'.

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 does not provide any guidance on when to use this tool versus alternatives such as 'search_indicators' or 'get_indicator_metadata'. There is no explicit when-to-use or when-not-to 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 and openWorldHint. The description adds minimal context: it lists counts from the Codebook. It does not elaborate on potential changes, frequency, or source limitations beyond what annotations imply.

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 no unnecessary words. It efficiently conveys the tool's purpose.

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 zero parameters, an existing output schema, and annotations, the description is complete enough. It identifies the data source ('Codebook') and the nature of the output ('counts'), which is sufficient for a simple list 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?

There are no parameters, so baseline is 4. The description need not add parameter details; the schema coverage is 100% by default.

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 action ('List') and the specific resource ('GHED variable category counts from the Codebook'). It distinguishes itself from siblings like 'list_variables' by focusing on categories and providing counts.

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, such as 'list_variables' or 'search_variables'. The description does not specify any context or 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 declare readOnlyHint=true and openWorldHint=true. The description adds the source (GHED Codebook) and filtering capability, but does not elaborate on behavioral traits like pagination or listing scope. It 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 concise sentence, efficiently stating the core functionality. However, it is slightly too brief, sacrificing clarity on parameters and usage context.

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 4 parameters, many sibling tools, and no schema descriptions, the description is incomplete. It fails to explain parameter usage, provide guidance on when to use this vs. search_variables, or clarify the role of categories.

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?

With 0% schema description coverage, the description must explain parameters. It only mentions optional filtering by category, leaving category_1, category_2, skip, and top undefined. The skip and top parameters for pagination are entirely unmentioned.

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 lists GHED Codebook variables with optional filtering by category. It uses a specific verb 'List' and resource 'variables', but does not explicitly differentiate from similar sibling tools like search_variables or list_variable_categories.

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 no guidance on when to use this tool versus alternatives such as search_variables or list_variable_categories. It does not mention prerequisites, constraints, or 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 indicate readOnlyHint and openWorldHint as true. The description adds value beyond those by specifying the explanatory nature of the tool—it conveys knowledge rather than performing data mutations. No contradictions exist, and the description appropriately complements 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, focused sentence that immediately conveys the tool's purpose. Every word earns its place; there is no redundancy or unnecessary detail. It is front-loaded and easy to parse.

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 simplicity (no parameters, explanatory role), the description is complete enough. An output schema exists, so return values do not need description. The description adequately covers what the tool does and why an agent would use it.

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 tool has zero parameters, so baseline score is 4 as per instructions. The description does not need to elaborate on parameters. Schema coverage is effectively 100% since there are no parameters to document.

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 explains how GHED variables are organized and how to choose the right series. It uses a specific verb 'Explain' and specifies the resource 'GHED variables'. This purpose is distinct from all sibling tools, which do not offer explanatory guidance on variable organization.

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: when needing to understand variable organization and series selection. While it lacks explicit 'when not to use' statements, the context is clear enough that an agent can infer appropriate usage, especially given the unique explanatory role among siblings.

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, so the description adds unit and comparison details but doesn't disclose additional behavioral traits like pagination or data completeness. The description adds some value beyond annotations but is not extensive.

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, with the purpose front-loaded and unit details in a separate paragraph. No wasted words.

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 12 parameters with 0% schema coverage and an output schema, the description is insufficient to guide correct usage. It does not explain filtering parameters, ordering, or the meaning of the change units in relation to the output.

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 explains metric units but leaves 11 other parameters unexplained. The parameter names like min_year_count and min_period_years are ambiguous without description.

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 specific verb 'rank' and resource 'countries by change', and explicitly differentiates from indicator_trend for unranked summaries. The purpose is clear and distinguishes from siblings, though 'change' could be more precise about the time range.

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 names alternative tool for unranked summaries, and provides unit conventions. Gives clear context for when to use this tool vs indicator_trend, and clarifies metric units.

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 indicate idempotence and non-destructiveness. The description adds the specific action (download, rebuild) but lacks details on potential side effects like network usage, time cost, or impact on concurrent operations.

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?

Single sentence, no redundancy. The description is concise and front-loads the core action.

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 zero parameters and the presence of an output schema, the description sufficiently covers the tool's purpose and behavior. No additional context is necessary for this simple 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?

No parameters exist, so baseline is 4. The description does not need to add meaning beyond what the schema provides, and it correctly omits unnecessary detail.

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 downloads/re-downloads the GHED workbook and rebuilds SQLite, specifying the exact action and resource. This distinguishes it from sibling tools like cache_status or check_for_updates.

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 on when to use this tool versus alternatives. The description does not mention prerequisites, recommended context, or situations to avoid, leaving the agent to infer usage from the name alone.

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 and openWorldHint. Description adds context about content (GHED-using literature) but no behavioral details beyond annotations. Minimal additional 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?

Single sentence, very concise. Front-loads purpose. No unnecessary words. Appropriate for a simple tool.

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?

Output schema exists but not visible. Description mentions patterns and recommended variables but no detail on output structure or format. For a tool with no parameters and existing output schema, slightly more context on what to expect would be helpful.

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?

No parameters, so schema coverage is 100%. Baseline is 4. Description doesn't mention zero parameters, but it's not necessary. No loss of meaning.

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?

Description states tool researches patterns in GHED-using literature and gives recommended variables. Verb 'research' is somewhat vague but resource 'GHED-using literature' is specific, and it distinguishes from siblings like 'suggest_variables_for_research_question' which focuses on a specific question.

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 on when to use this tool vs alternatives. Sibling list includes many research-oriented tools, but no comparison or context is provided. Agent must infer usage.

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 indicate the tool is read-only and non-exhaustive. The description adds behavioral context by specifying acceptable input formats (canonical codes, WB region codes, common spellings), which aids correct invocation.

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: the first defines the primary function, the second lists acceptable inputs. Every sentence adds value with no 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 description adequately covers the input parameter and acceptable formats. Despite the presence of an output schema, it lacks mention of error handling for invalid inputs, but overall it is sufficient for a straightforward resolution 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?

With 0% schema coverage, the description fully compensates by explaining the 'group' parameter accepts canonical codes, WB region codes, and common spellings, providing concrete examples. This adds significant meaning beyond the schema's bare string 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 clearly states the tool resolves curated group codes to their ISO3 member lists. It distinguishes itself from sibling tools like list_country_groups and summarize_country_group by focusing on resolving codes to members, not listing or summarizing.

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 implicitly tells when to use the tool: when you have a group code or common spelling and need the ISO3 member list. It could be improved by explicitly stating when not to use it (e.g., for non-curated groups), but the context makes it clear enough.

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 readOnlyHint and openWorldHint annotations, the description discloses the substring matching behavior, the need for short fragments, the no-match fallback strategy, and the special category_1=None behavior. This is substantial behavioral context that helps an agent know what to expect during a search.

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 the core action and sibling differentiation, followed by concise, high-value behavioral and fallback guidance. Every sentence adds operational value without repetition or filler.

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 an output schema and read-only annotations, the description covers the main usage pitfalls: substring vs semantic search, query format, fallback routes, and the category_1=None behavior. It is slightly incomplete on the semantics of top and category_2, but the schema defaults and titles make those parameters reasonably inferable.

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 compensate. It adds meaning for query (substring fragments with examples) and category_1 (None searches all variables), but it does not explain top or category_2. Partial compensation only, so the score is mid-range.

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 and resource ('Search headline indicators') and immediately differentiates itself from search_variables for detailed SHA series. It also clarifies that this is substring, not semantic, search, which removes ambiguity about what the tool actually does.

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 tells the agent when to use this tool vs search_variables, and when to fall back to topics_index if no match. It also gives concrete query-shaping guidance (short fragments, not full research questions), making the invocation context unmistakable.

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 and openWorldHint=true. The description adds behavioral detail: it's substring search, advises short fragments, and explains that empty results may indicate a wording mismatch rather than unavailability. This goes beyond the annotations and helps the agent interpret outcomes correctly.

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 concise sentences, front-loaded with the primary purpose and immediate alternative. The guidance is efficient without excess wording. It could be slightly more structured (e.g., bullet points), but it's still very readable and scannable.

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 usage alternatives and query behavior, and the presence of an output schema covers return value documentation. However, it omits the meaning and usage of category_1/category_2, and 'top' pagination is not explained. For a tool with four parameters and no schema descriptions, more detail is needed for full context.

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 compensate for parameter meaning. It partially explains the 'query' parameter (short fragment, not full question) but says nothing about 'top', 'category_1', or 'category_2'. These are left undocumented, and the description does not bridge that gap for the majority of parameters.

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 'Search all Codebook variables' – a clear verb and resource. It also distinguishes itself from search_indicators by directing to that tool for headline measures, so the agent can tell them apart. It doesn't explicitly differentiate from list_variables or other search-like tools, but the purpose is 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 explicitly says 'use search_indicators for headline measures' – providing a clear alternative and when to use it. It also advises using a short fragment and suggests topics_index as a fallback when results are empty. This gives concrete guidance on when to use this tool versus 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 provide readOnlyHint=true and openWorldHint=true. The description adds value by mentioning 'cautions', suggesting the tool also provides warnings or limitations, which extends behavioral context beyond structured 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?

Single sentence that efficiently communicates action, input, and output. Every word earns its place with no 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?

Has an output schema, which reduces the burden on description for return values. Description covers the core purpose and adds 'cautions'. Could elaborate on what cautions entail, but sufficient given output schema exists.

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% for the single parameter 'question', so the description must compensate. It clarifies the parameter is a 'natural-language research question', but provides no format guidance or examples. Adequate but not enhanced.

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 'Map' and specifies the resource 'natural-language research question' and output 'likely GHED variables and cautions'. It clearly distinguishes from siblings like search_variables that perform string matching rather than conceptual mapping.

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?

Implies usage for research questions but does not explicitly state when to use this tool versus alternatives like search_variables or list_variables. No when-not or exclusion criteria 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, so the description adds no extra behavioral context like side effects or rate limits. Acceptable given annotation coverage, but no added 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?

Two concise sentences front-loading purpose and usage tip. No fluff, but could be more structured with parameter list.

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 7 parameters and 0% schema coverage, the description only covers grouping selection. Missing explanation of other parameters and summary behavior, though output schema exists.

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%; the description only hints at three grouping parameters (country_group, region, income) with examples. Other parameters (indicator_code, year, latest_only, top_n) are not explained, failing to compensate for low schema coverage.

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 summarizes an indicator within a country group, specifying types (curated, regional, income). It distinguishes from siblings like compare_country_group, but could be more explicit about the summary's nature.

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?

Provides a usage tip to pass at least one grouping parameter with examples, but lacks when-to-use guidance or alternatives. Minimal but not comprehensive.

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 and openWorldHint=true, covering safety. The description adds that it is 'curated' and involves 'mapping', which provides context but does not elaborate on behavioral traits like static nature or update frequency. It is adequate given 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 sentence that is concise, front-loaded with the key term 'Curated', and contains no unnecessary words. It efficiently conveys the tool's core function.

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 simplicity (no parameters, annotated, output schema exists), the description is mostly complete. It explains the purpose but could briefly mention what the output contains or how the mapping is structured, though the output schema likely covers that.

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?

There are no parameters, so the schema has 100% coverage. The baseline for zero-parameter tools is 4, and the description does not need to add parameter details. It correctly omits irrelevant information.

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 it's a curated index mapping user requests to variable codes. It specifies the resource (GHED topic index) and the action (mapping). However, it does not explicitly differentiate from sibling tools like search_indicators or list_variables, but the unique mapping purpose is implied.

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 on when to use this tool versus alternatives is provided. With many sibling tools for searching and listing, the description should indicate that this tool is for translating user requests directly to codes, rather than general search.

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 provide readOnlyHint. Description adds 'cache provenance', giving more detail but no behavioral traits beyond what annotations imply.

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?

Single clear sentence with no wasted words. Perfectly concise.

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?

Tool has zero parameters and output schema exists, so description adequately covers what it returns. No gaps.

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?

No parameters, so baseline 4. Description adds no parameter info but not needed.

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?

Clearly states it returns workbook version lines and cache provenance. Distinct from sibling tools like cache_status.

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 on when to use versus alternatives like cache_status or refresh_cache.

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