The Cracks Index

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful transparency by stating 'Read-only, area-level aggregates only, no personal data', which conveys privacy and aggregation characteristics beyond the schema. It also clarifies the data scope (latest snapshot, peer group). This exceeds baseline expectations without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences: the first immediately states the main purpose, the second lists the concrete outputs, and the third adds the use case. Every sentence earns its place with no repetition or filler. It is efficiently front-loaded with the key verb and resource.

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?

Despite having one parameter and rich annotations, the description covers the essential context: the tool computes statistical placement, lists outputs, and clarifies its read-only, aggregate-only nature. With an output schema present, the return value details are handled elsewhere. The description is sufficient for an agent to select and invoke the tool correctly without 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?

Schema description coverage is 100%, so the parameter 'area' is fully documented in the input schema. The description does not add additional parameter-level semantics—it only references 'its own level' which is consistent with the schema's mention of country codes, NUTS-2 regions, and municipalities. Since the schema carries the parameter detail, the description adds no extra value beyond the baseline.

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 function: 'Return where one area sits statistically within its own level.' It specifies the exact outputs (percentile, distance to median, best/worst, nearest areas), making it distinct from siblings like indicator_ranking or region_detail. The verb is specific ('Return') and the resource is precise (statistical placement within its peer group).

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 a clear use case: 'Useful for answering "is this area typical, or an outlier?"'. This gives context for when to use the tool. It does not explicitly name alternative tools or exclusion criteria, but the stated purpose separates it from comparison or ranking tools. No explicit when-not-to-use is mentioned, so it falls short of a 5.

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 the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that it compares composite score and rank, which is mild additional context. It does not disclose other behavioral traits like error handling or return format, but the output schema likely covers that.

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 exactly two sentences: the first conveys the core purpose, the second briefly explains the parameter. It is front-loaded, concise, and contains no filler 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?

For a simple one-parameter tool with full schema coverage, comprehensive annotations, and an output schema, the description is adequate. It states the purpose and parameter without needing to explain return values or safety (handled by schema/annotations). It does not mention alternatives or limitations, but that is not critical for such a straightforward 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?

The schema description for iso3_list is fully detailed (ISO-3166 alpha-3 codes, example, case-insensitivity), so the description's repetition that it is "a list of ISO-3166 alpha-3 country codes" adds no new information. Since schema coverage is 100%, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: "Compare the composite score and rank of several countries." This uses a specific verb (compare) and specific scope (composite score and rank, several countries), which distinguishes it from sibling tools like country_detail (single country) and compare_gemeenten (municipalities).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when you need to compare multiple countries on their composite score and rank. It does not explicitly mention alternatives or when-not-to-use scenarios, but the wording "several countries" implicitly excludes single-country or municipality comparisons.

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 meaningful context beyond the annotations: it explicitly states 'Read-only, no personal data' (reinforcing but adding 'no personal data'), clarifies that 'wmo_pressure and youth_care_load are context only — shown but never scored', and provides interpretive guidance ('CBS aggregates describe an area, not its quality'). These are behaviors not visible in the annotations or schema.

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 first sentence states the purpose, the second explains input and output, and the third adds key caveats. No redundant sentences; every clause carries useful information. It is appropriately sized for a tool with one parameter and existing schema/annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter fully documented in the schema and an output schema present, the description covers the essential context: use case, input range, what is returned (indicators, composite score, rank), and important caveats (context indicators not scored, area-level aggregates). Nothing critical is missing for the agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, region_codes, is fully described in the schema with format, example, and constraints (two to six comma-separated GM-codes, case-insensitive). The description repeats 'two to six CBS GM-codes' but adds no new semantic detail beyond what the schema already provides. With 100% schema coverage, the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a clear, specific verb+resource: 'Compare the social-domain profile of several Dutch municipalities.' It further details the exact scope (two to six CBS GM-codes, four v1 indicators plus composite score/rank) and distinguishes from siblings by being explicitly Netherlands-specific and focused on social-domain comparison, unlike compare_countries or gemeente_social_profile.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says it is 'Useful for an agent answering how municipality A compares to B on the social domain', which gives a clear use case. It also includes a boundary ('Netherlands-only') and specifies the input range (two to six codes). However, it does not explicitly name alternatives or state when NOT to use it, so it falls short of the full 5.

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 idempotentHint, so the agent knows it is a safe read. The description adds that the result includes score, rank, and per-indicator breakdown, but these are output details already covered by the output schema. No additional behavioral context (e.g., data source, auth, rate limits) is provided, but given the annotation coverage, this is acceptable.

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 function without waste. Every word contributes to understanding the tool's purpose and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter), annotations cover safety traits, and an output schema exists, so the description need not explain return values. The description is sufficient for an agent to correctly select and invoke the 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?

The schema description for iso3 is comprehensive (ISO-3166 alpha-3 code, example, case-insensitive), covering 100% of parameters. The tool description does not add parameter-specific information, so the baseline score of 3 applies as the schema handles the semantics.

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 a single country's score, rank, and per-indicator breakdown, distinguishing it from siblings that compare or aggregate multiple entities. It uses a specific verb ('Return') and resource ('one country') with a concise scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching details of a single country, but does not explicitly mention when to use this tool instead of alternatives like compare_countries or region_detail. There are no exclusions or alternative tool references, so the guidance is only implicit.

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, destructiveHint, idempotentHint. The description adds a useful extra disclosure: 'Read-only, no personal data', which goes beyond the annotations. It also explains the behavioral nuance of returning 'the one change most associated with fastest improvement,' providing context beyond what annotations convey.

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 short paragraphs, front-loaded with the core action. Every sentence adds value, with no repetition of schema or annotation content. It is concise and well-structured.

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 one-parameter, read-only tool with rich annotations and an output schema, the description is complete. It provides sufficient context about the Cracks Index and the tool's purpose without needing to detail return values or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the single parameter iso3 with a clear description and example. The tool description adds no extra parameter-level detail, but given 100% schema coverage, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return the single highest-impact improvement for one country', which is a specific verb+resource+scope. This clearly distinguishes it from sibling tools like country_detail (general info) and improvement_guidance (broader guidance) by focusing on a single, tailored fix.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when you want the single most actionable improvement for a country, 'turning a ranking into a constructive, actionable signal.' It provides clear context but does not explicitly mention alternatives or exclusions, so it stops short of a full 5.

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 the tool as read-only/idempotent/non-destructive. The description adds behavioral context: it claims 'Read-only, no personal data,' warns that wmo_pressure and youth_care_load are context-only and never scored, and notes that CBS aggregates describe an area, not quality. This goes beyond the structured hints.

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 about 80 words, front-loads purpose, and contains no filler. Each sentence contributes either return details, scoping, or caveats; the organization is logical.

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?

Despite a rich output schema, the description thoroughly enumerates return fields (indicators, raw value, source, measured/modelled), composite score/rank, v0-equivalent, and clarifies the role of context-only variables. It also covers geographic scope and safety, making it self-sufficient for an agent to decide and invoke.

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 sole parameter region_code is fully documented in the schema with examples and case-insensitivity note (100% coverage). The description restates 'Given a CBS GM-code' but adds no new semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return the Dutch social-domain profile for one municipality,' a specific verb and resource. It enumerates the four v1 indicators, composite score, and rank, and clarifies the Netherlands-only scope, distinguishing it from sibling tools like area_statistics or compare_gemeenten.

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?

Clearly states the input (CBS GM-code) and scope (one municipality, Netherlands-only). It implies usage for Dutch municipalities but does not explicitly name alternatives or when-not-to-use, so it stops short of full exclusion guidance.

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

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

Annotations already establish this as a safe, read-only, idempotent operation. The description adds useful context by specifying that it returns data from the latest published snapshot (not live) and that the ranking is full (implying no pagination). No contradictions 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?

A single sentence with no wasted words. It is front-loaded with the action and result, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, zero parameters, and presence of an output schema, the description covers the essential aspects. It lacks an explicit mention of the cracks index domain, but the tool name and title provide that 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?

The tool has zero parameters, so schema coverage is complete by default. The description adds no parameter-specific meaning but appropriately clarifies what the parameterless operation returns, which is sufficient.

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 the full country ranking from the latest published snapshot. It uses a specific verb ('Return') and resource ('country ranking'), and the scope ('full', 'latest') distinguishes it from sibling tools like indicator_ranking.

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. It does not mention any exclusions or refer to sibling tools, leaving the agent to infer appropriate usage from the name and title 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 idempotentHint; the description reinforces this with 'Read-only, no personal data' and adds useful behavioral context that ranks are within the area's own level. 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?

The description is well-structured and front-loaded with the tool's purpose, followed by a concise parameter section. It is somewhat redundant with schema descriptions, but the additional context about area levels and ranking is justified.

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 an output schema exists, return values need not be explained. The description covers what areas are included, filters, ranking scope, and read-only behavior. It is sufficiently complete for this list tool, aside from the parameter value mismatch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description introduces a conflicting value for the level parameter: it says 'gemeente' while the schema says 'municipality'. This ambiguity can mislead an agent when choosing the correct allowed value, so the description undermines rather than enhances the schema's baseline semantics.

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 begins with a specific verb and resource: 'List sub-national areas in the Cracks Index, ranked within their level.' It clearly distinguishes this tool from country-level siblings by explicitly stating it returns sub-national areas (EU NUTS-2 and Dutch municipalities) with composite score and rank.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use this tool to list sub-national areas with optional filters (level, country_iso3, limit). It does not explicitly name alternatives or exclusions, but the list-oriented purpose is evident relative to richer sibling tools like region_detail or indicator_ranking.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety. It adds valuable behavioral context: the lever is framed as 'the change most associated with improvement' (not a guarantee), includes disclaimers about non-advice, and mentions a link to a 'claim your score' page. This goes beyond annotations and enriches the agent's understanding of what the tool returns.

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 main purpose, then expands on input formats, output components, and disclaimers. Each sentence contributes useful information. It is slightly redundant by repeating area formats already in the schema, and the legal disclaimers add length, but overall it remains well-structured and not overly verbose.

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 1-parameter tool with an output schema present, the description is exceptionally complete. It explains the input formats, the exact output (highest-impact lever, approach, link), the nature of the guidance (aggregated, non-guaranteed), and the read-only/no-personal-data characteristic. With an output schema handling return structure, no significant gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description for the 'area' parameter is 100% covered with format examples (ISO-3166, NUTS-2, CBS GM-code) and case-insensitivity. The tool description repeats this information without adding new meaning about the parameter itself. Therefore, the description adds no significant value beyond the schema, warranting the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return constructive improvement guidance for one area,' a specific verb+resource+scope that immediately clarifies the tool's function. It distinguishes itself from sibling tools by emphasizing 'one area' and detailing the output (highest-impact lever, Fynqo's approach, link), making it clearly different from statistics or comparison tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use this tool: when you need improvement guidance for a single area. It provides context about input formats and output, and states 'Read-only, no personal data,' which further clarifies appropriateness. However, it lacks explicit exclusions or named alternatives, so it falls short of a 5.

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 readOnlyHint and idempotentHint true. The description adds context beyond this: it explicitly states 'Read-only, area-level aggregates only, no personal data' and explains how to interpret coefficients near +1/-1. This is useful behavioral transparency without contradicting 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 three sentences: the first states the core purpose, the second explains the methodology and the added note, and the third covers interpretation and privacy. Every sentence earns its place and it is front-loaded with the key 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 the tool's simplicity (one parameter, output schema present), the description is complete: it covers methodology, output content (strongest relationship note), interpretation guidance, and privacy. It does not explicitly tie the 'level' parameter to the areas being correlated, but that is already in the schema, so the description adequately complements the structured data.

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 provides 100% coverage for the single 'level' parameter, including allowed values and a default. The description does not add parameter-specific meaning beyond what the schema already states, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Return pairwise correlations between the six indicators across areas,' using a specific verb and naming the exact resource. This clearly distinguishes it from siblings like indicator_ranking and score_trends, which focus on rankings and trends rather than pairwise relationships.

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 analyzing relationships between indicators across areas and notes it works on area-level aggregates. It gives clear context for when to use it, but does not explicitly mention alternatives or when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnly and idempotent hints, and the description adds valuable context: read-only, area-level aggregates only, no personal data, and the direction-corrected normalized_score meaning. This goes beyond the annotations without contradicting them.

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 four sentences, front-loaded with the primary action, and every sentence adds meaningful detail (score direction, returned values, privacy). No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With full schema coverage, strong annotations, and an output schema present, the description provides sufficient context for the tool's purpose, return behavior, and safety profile. No critical gaps remain.

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 already covers 100% of parameters with clear descriptions, so the baseline is 3. The description's mention of normalized_score and raw values relates more to output than to parameter syntax, adding minimal extra parameter-level 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 opens with a specific verb and resource: 'Rank all areas by a single chosen indicator.' It clearly distinguishes itself from sibling tools by focusing on broad area-level ranking by one indicator, and the following sentences explain the ordering and returned values.

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 scope is clearly stated ('all areas', 'single chosen indicator'), which gives the agent a strong sense of when to use it. However, it does not explicitly name alternatives for scenarios like comparing two specific regions, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing a safe read operation. The description adds what the methodology covers (indicators, weights, direction, sources) but no additional behavioral traits such as pagination, formatting, or authorization. This falls short of adding rich context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, highly concise, and front-loaded with the action ('Return the index methodology') followed by a compact enumeration of contents. Every word 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?

For a simple, parameterless tool with an output schema and full annotation coverage, the description is complete. It conveys the essential purpose and scope of the return value, leaving no critical gaps for an agent to understand what to expect.

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 the baseline is 4. The description properly compensates by explaining what the tool returns, which is the sole semantic content needed. No schema parameter descriptions are necessary.

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 'Return' and a precise resource 'index methodology', listing the contained elements (indicators, weights, direction, sources). This clearly distinguishes it from sibling tools that return actual data or 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 gives no indication of when to use this tool versus alternatives. It doesn't mention any contrasting tools, prerequisites, or explicit usage scenarios. The title partially implies its purpose, but the description could clarify that this is for understanding index construction rather than accessing 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: the rank is "within its own level" (regions vs municipalities) and the 'fix' is the "single highest-impact improvement." It also notes "Read-only, no personal data," which reinforces the annotation without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences plus a brief safety note. Each sentence carries meaningful information: the first captures the core output, the second defines the input and rank scoping, and the third is a concise qualifier. 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?

With a single required parameter, strong annotations, and an output schema present, the description fully covers the essential behavior. It explains the rank nuance and the nature of the 'fix', making the tool's purpose and output clear without needing to detail return fields or error cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema's parameter description already explains the region_code format and gives examples. The tool description repeats the format but does not add new parameter-specific semantics beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Return one sub-national area: score, rank, indicator breakdown and fix." It clearly distinguishes this from siblings like country_detail (national level) and compare_* tools (comparison), and matches the tool name 'region_detail' with a precise definition of what is returned.

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 states the input format (EU NUTS-2 or Dutch CBS GM-code) and explains the rank semantics, giving clear context for when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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, destructiveHint, and idempotentHint. The description adds useful behavioral context: it 'walks every published Cracks Index snapshot', returns 'net change from the first to the most recent snapshot', and explicitly states 'no personal data' — details 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 concise and well-structured: a clear opening summary, a detail paragraph on input and behavior, and a brief scope note. No filler — every sentence adds value.

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 one parameter fully documented in the schema, a detailed description of the output (score, rank, net change), and the presence of an output schema, the description is complete for its complexity. It covers input format, behavior, and output meaning.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the 'area' parameter description specifying accepted codes and case-insensitivity. The description reinforces this by listing identifier types and their examples, but adds no significant new semantic meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Return one area's composite-score history across every snapshot', specifying the verb, resource, and scope. It further details that it returns composite score, rank, and net change, which distinguishes it from sibling tools like area_statistics or top_movers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: for a single area's historical trend. It specifies accepted identifier types (ISO, NUTS-2, CBS) and notes it is read-only, but it does not explicitly mention alternatives or when-not-to-use scenarios.

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 annotations, the description adds valuable behavior: it compares composite scores, defines improvers and decliners with a counterintuitive naming explanation (improvers' score fell, decliners' rose), and discloses the empty payload when data is insufficient. It also confirms read-only, area-level aggregates, and no personal data.

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, front-loaded with the core purpose, and uses a clear structured format. Every sentence adds value, explaining mechanism, edge case, and data safety without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a simple two-parameter schema and an output schema present, the description covers the tool's behavior, edge cases (needing two snapshots), and data characteristics fully. It is complete for an agent to use confidently.

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 covers both parameters with descriptions, providing 100% coverage. The tool description adds no extra parameter-level detail, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the biggest risers and fallers between the two latest snapshots, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on temporal comparison rather than static rankings or area details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use when you need top movers between snapshots, and notes the precondition of at least two snapshots. It does not explicitly name alternative tools, but the context is sufficient for an agent to decide when this tool is appropriate.

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