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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating safe read and potentially incomplete data. The description adds that data is 'per year' and the role semantics, but does not elaborate on behavior like data freshness or handling of missing years. With annotations covering the safety profile, the additional contribution is moderate.

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 long, directly stating the tool's purpose and the key role distinction. Every word is necessary; no fluff or repetition.

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

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

With an output schema present, the description does not need to detail return values. It covers the core functionality (yearly data, role selection) adequately. Minor gaps: no mention of how openWorldHint affects results or that output schema exists, but overall sufficient given 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 description coverage is 100%, so the schema already documents all parameters. The description re-emphasizes the role default and meaning, but adds little beyond the schema's own descriptions (e.g., year range defaults are only in schema). 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 clearly states 'Individual asylum applications lodged per year' which identifies the resource (asylum applications) and the verb (lodged per year). It distinguishes between two roles ('asylum' vs 'origin'), which helps differentiate from sibling tools like asylum_decisions or refugee_population.

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 each role ('asylum' for applications filed IN the country, 'origin' for filed BY nationals abroad), providing clear context. However, it does not explicitly guide when to choose this tool over siblings like 'asylum_decisions' or 'trend_analysis', leaving room for ambiguity.

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. Description adds that results are per-year with specific categories, but does not reveal other behavioral traits like data freshness, pagination, or limitations. With annotations covering safety, description adds moderate value.

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

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

Two sentences: first lists the data returned, second explains the role parameter. No wasted words, front-loaded with core information. 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?

With output schema present, the description is sufficient. It explains the key data categories and the role parameter's effect. An agent can correctly invoke the tool based on this description alone.

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%, so each parameter already has a description. The tool description does not add additional semantic meaning beyond what the schema provides. 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?

Clearly states the tool returns decisions on individual asylum applications per year, categorized by outcome types (recognized, complementary protection, rejected, otherwise closed) plus recognition rate. Distinguishes from sibling 'asylum_applications' by focusing on decisions rather than applications.

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?

Explains the role parameter default and meaning ('asylum' = decided in the country). Provides context for when to use each role value, but does not explicitly state when to use this tool vs alternatives like 'asylum_applications' or 'compare_countries'.

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 behavioral context beyond annotations: it specifies the domain (displacement), role option, and normalization. Annotations already declare readOnlyHint and openWorldHint, which are consistent. The description does not contradict annotations and adds useful detail.

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 only two sentences, front-loaded with the main purpose, and every sentence adds value. No unnecessary 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?

Given the complexity of 6 parameters and an existing output schema, the description adequately covers the tool's functionality and defaults. Minor omissions like data source mention are acceptable as schema covers return values and parameters.

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 parameter descriptions already present. The description adds context for defaults (e.g., refugees, last 10 years) but does not significantly enhance understanding of individual parameters beyond what the schema provides. 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 clearly states the action ('compare'), resource ('displacement metric'), and scope ('2–5 countries over a year range'). It also specifies defaults and normalization, which distinguishes it from sibling tools that typically focus on single-country or single-metric analysis.

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 defaults and the option for normalization, giving context on typical usage. However, it does not explicitly state when not to use this tool or point to alternative tools for other scenarios, so it falls short of explicit guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and completeness profile is clear. Description adds little beyond stating the data source (ACLED via HDX) and annual periodicity.

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 data source, no waste. 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?

Given 3 parameters with full schema coverage and an output schema available, the description is sufficient. It could optionally mention the annual aggregation or data update frequency, but is adequate.

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% with clear parameter descriptions (country, year_from, year_to including examples and defaults). The tool description does not add extra meaning 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?

Description clearly states it provides annual conflict event counts and fatalities for a country via ACLED/HDX, with a specific verb+resource. It distinguishes from siblings by mentioning pairing with refugee_population/trend_analysis.

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?

Description gives a use case pairing with other tools, but does not explicitly state when to use this vs alternatives among many siblings. No exclusions or alternative tools 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 indicate readOnlyHint=true and openWorldHint=true. The description adds that it's a 'snapshot' of latest data, clarifying point-in-time nature, and lists specific components. No contradictions.

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-structured sentence that front-loads the purpose and lists output content without unnecessary 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 the tool's simplicity (one parameter, no nested objects) and the existence of an output schema, the description sufficiently explains what the tool returns, making it complete for agent 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?

The schema covers the single 'country' parameter with a description (100% coverage). The description does not add new meaning to the parameter beyond what the schema provides, so 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 clearly states the tool provides a humanitarian snapshot including displaced population hosted, population displaced from the country, and top origin countries. This is specific and distinct from siblings like 'refugee_population' or 'compare_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 implies use when needing a quick overview of displacement data for a country. It does not explicitly exclude scenarios or mention alternatives, but the sibling list provides context for other 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 already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context about data recency (recent years only) and role defaults, which goes beyond annotations. No contradiction.

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

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

Two sentences that front-load the purpose and add constraints. No redundant or vague wording. Every sentence contributes 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 tool has an output schema, the description adequately covers what data is returned (age/sex breakdown), population scope (displaced people connected to a country), and data limitation (recent years only). Could mention typical use cases but sufficient.

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%, so description adds limited value beyond parameter descriptions. It explains roles in context ('asylum' = hosted, 'origin' = from) but essentially paraphrases schema. 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 clearly states it provides age/sex breakdown of displaced people by country, with roles 'asylum' (hosted) and 'origin' (from). It distinguishes from sibling tools like 'refugee_population' or 'latest_statistics' by focusing on demographic 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 mentions data recency ('UNHCR publishes demographics for recent years only') and default role, but does not explicitly guide when to use this tool vs. alternatives like 'top_host_countries' or 'trend_analysis'. Usage context is implied but not explicit.

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 openWorld hints. The description adds that it exports normalized records and mentions format-specific behavior (geojson requires group_by), which is helpful 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, front-loaded with the main action and available formats. No unnecessary 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?

Output schema exists, so return values are covered. The description includes the key behavioral nuance about geojson and group_by. With 10 parameters, it could add more context about filtering options, but the schema descriptions fill in the 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 coverage is 100%, so the description adds limited extra meaning beyond the schema descriptions. The geojson/group_by hint provides some value, but for 10 parameters, the description does not elaborate on most.

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 exports normalized records from any dataset in multiple formats, and the context of geojson with group_by differentiates it from sibling tools that focus on analysis or visualization.

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 to use when the user wants raw data to download or paste elsewhere, and notes the geojson caveat with group_by. It does not explicitly state when not to use, but the purpose is 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?

The description adds value beyond annotations by revealing the data source (IPC via HDX) and output structure (phase breakdown with headline). This complements the readOnlyHint and openWorldHint annotations, though it could mention real-time update 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 two sentences, front-loading the essential purpose and data source. Every word contributes meaning, with no redundancy or 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?

Given the tool's low complexity (2 params, output schema exists), the description adequately covers the output and data source. It could explicitly note the optionality of the year parameter, but the schema already does so.

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%, so baseline is 3. The description reinforces that 'country' is the main filter and indicates the output is a breakdown per country. It adds moderate context beyond the schema's property 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 provides 'Latest IPC food-insecurity phase breakdown for a country' and specifies the output details (people per phase 1–5, phase 3+ headline). This distinguishes it from sibling tools, none of which focus on food security.

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 food security data retrieval but does not provide explicit when-to-use or when-not-to-use guidance, nor does it compare to sibling tools like 'conflict_events' or 'demographics'. Usage context is inferred.

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 discloses that the tool performs a statistical extrapolation and is not official planning data, which adds behavioral context beyond the readOnlyHint and openWorldHint annotations. It also instructs the user to present the result with a caveat.

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, consisting of two sentences that front-load the purpose and then add an important caveat. 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?

Given the availability of an output schema and full parameter descriptions, the tool description adequately covers the projection methodology and its limitations. It could mention the output format briefly, but the output schema likely handles 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?

All four parameters are fully described in the input schema (100% coverage). The tool description does not provide additional parameter-level details beyond what the schema offers, 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 it is a naive linear projection of a displacement metric 1-5 years ahead based on the last 10 years. It also explicitly distinguishes itself from UNHCR planning figures, providing specificity beyond a mere verb-resource pair.

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. It lacks explicit when-to-use, when-not-to-use, or comparison with sibling tools like 'trend_analysis'.

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 declare readOnlyHint=true and openWorldHint=true, but the description adds valuable behavioral context: it specifies that the tool returns chart specifications (not actual rendered images) for various formats, and explains normalization behavior. 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?

The description is two sentences, front-loaded with the core purpose and formats, then a second sentence adding key parameter context. No unnecessary words; every sentence earns its place.

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

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

Given 8 parameters, full schema coverage, and an output schema, the description covers the main points (formats, normalization). It does not detail all parameters, but those are documented in the schema. The presence of an output schema reduces the need to describe return values. Slight gap in explaining kind and metric defaults, but overall sufficient.

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 baseline is 3. The description adds meaning beyond the schema by clarifying normalization (per 1,000 residents or per US$1bn GDP) and implicitly explaining the role parameter (asylum vs. origin). This adds value.

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 'render' and clearly identifies the resource as 'displacement metric for one or more countries as a chart specification'. It lists four distinct output formats, distinguishing this chart tool from sibling tools like generate_map or country_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 explains what the tool does and mentions format and normalization options, but does not explicitly state when to use this tool versus alternatives such as compare_countries, trend_analysis, or generate_map. Usage context is implied but not articulated.

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 specifying the output format (markdown) and progress reporting. No behavioral contradictions or missing critical details.

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, highly efficient sentence. It is front-loaded with the main action and lists components without unnecessary 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 the tool's complexity, full schema coverage, presence of output schema, and annotations, the description covers all essential aspects: what the report contains, output format, and progress behavior. No 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?

Schema descriptions cover 100% of parameters with clear explanations (country as name/code, year defaults). The description adds no additional meaning beyond the schema, so baseline score 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 clearly states it composes a full markdown humanitarian situation report, listing specific components (key figures, refugee trend with chart, origins, asylum decisions, demographics). This distinguishes it from sibling tools like 'country_profile' or 'generate_chart'.

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 use for comprehensive overviews but does not explicitly state when to use this tool versus alternatives like 'country_profile' or 'generate_chart'. No when-not or alternative guidance is 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 and openWorldHint=true. Description adds concrete behavioral details: output is a GeoJSON FeatureCollection suitable for viewers, and explains how the 'by' parameter affects map mapping. No contradictions.

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 output format and usage hints. Every sentence is informative and 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?

Description covers purpose, output format, parameter behavior, and usage tips. Given the output schema exists and annotations are clear, no further details needed.

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 descriptions for all 4 parameters. Description adds value by explaining the output structure (centroid points sized by displacement metric) and the meaning of the 'by' parameter values 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?

Description clearly states it generates a GeoJSON FeatureCollection of country centroid points sized by a displacement metric, and specifies the two modes (asylum/origin). This distinguishes it from sibling tools like generate_chart or export_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?

Description implies usage for creating maps of displacement data, but does not explicitly mention when to use this tool versus alternatives like export_data or generate_chart. No when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description's main contribution is detailing what information is returned (datasets, metrics, attribution, terms). It does not contradict annotations or add major behavioral context beyond 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?

Two concise sentences with no wasted words. The purpose and usage guidance are front-loaded, making it easy for an agent to quickly understand the 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?

Given no parameters, the presence of an output schema, and annotations conveying read-only and open-world nature, the description is complete. It tells the agent exactly what to expect and when to call this 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 (0 params), so the baseline is 4. The description adds value by explaining the output content, which compensates for the lack of 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 clearly states the tool's function: 'Describe the connected data providers: datasets served, metrics available, attribution and terms.' It uses a specific verb ('describe') and identifies the resource ('connected data providers'), distinguishing it from sibling tools like 'latest_statistics' or 'demographics'.

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 advises when to use it: 'Call this to learn what data exists before querying.' This provides clear context for usage, though it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that data is per year and includes coverage percentage, which is consistent. However, it does not disclose any behavioral traits beyond what annotations provide, such as data latency or filtering 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 sentence that front-loads the key purpose and data source. It is concise and free of fluff, though it could be slightly more structured with bullet points.

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 data type (requirements vs funding, coverage percentage), granularity (per year, for a country), and source. With an output schema present, the description does not need to detail return format. It is sufficiently complete for a simple retrieval tool.

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

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

Schema description coverage is 100% (all parameters described in schema). The description does not add extra meaning beyond the schema's parameter descriptions; it only mentions the country context. 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 clearly states the tool retrieves humanitarian appeal requirements vs funding received per year for a country, including coverage percentage and data source. This specific verb-resource combination distinguishes it from sibling tools like asylum_applications or conflict_events.

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. For example, it does not mention when to prefer this over compare_countries or trend_analysis for cross-country or trend purposes. No exclusions or prerequisites are provided.

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

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

Annotations (readOnlyHint, openWorldHint) indicate safe read and potentially incomplete data. Description adds that figures are 'most recent' and explains behavior based on country parameter, which is useful beyond annotations. No contradiction.

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

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

Two concise sentences with no redundant information. Front-loaded with core purpose. Every word 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?

For a simple tool with 2 parameters, no required fields, and an output schema, the description covers the essential behavior. It could mention the role parameter explicitly, but the schema covers it. Adequate for the tool's 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 100% with clear descriptions for both parameters. Description does not add new meaning beyond explaining tool behavior based on country presence. Baseline 3 is appropriate as description complements but does not significantly enhance 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?

Description clearly states the tool retrieves most recent displacement figures, distinguishing between global totals (no country) and country-specific hosted figures. The verb 'get' is implied, and the resource 'displacement figures' is specific. This differentiates from sibling tools like refugee_population or top_host_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?

Explicitly guides when to use with a country vs. without. While it does not mention alternatives or exclusions, the instruction is clear enough for an agent to decide appropriate context. The sibling list provides further options, but the description itself offers sufficient usage direction.

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

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

Annotations indicate readOnlyHint=true and openWorldHint=true, so the tool is safe and non-destructive. The description adds behavioral details beyond annotations by specifying it checks latency and reachability, providing concrete insight into what the tool does.

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 extremely concise at two sentences, with the key information front-loaded. Every sentence adds value: the first states the core function, the second gives a usage scenario. 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 the tool's simplicity (no parameters, output schema exists), the description fully covers its purpose and usage context. It tells the agent exactly what it does and when to use it, making it complete for effective invocation.

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

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

The tool has zero parameters, and the schema coverage is 100% (trivially). The description does not need to explain parameters, and the absence is noted. With 0 parameters, baseline is 4.

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 ('liveness check') and resource ('every connected data provider'), and explicitly mentions what is checked (latency, reachability). It also distinguishes itself from sibling tools, which are focused on asylum, country profiles, and trends, not provider health.

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: 'Use when queries fail to distinguish upstream outages from bad parameters.' While it doesn't include when not to use or alternatives, the context 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 already declare readOnlyHint=true, indicating a safe read operation. The description adds value by disclosing pagination ('Paginated'), default year ranges (10 years back from year_from, latest for year_to), and default limit (100). It also explains the behavior of the role and other_country parameters beyond the schema. No destructive actions are described, consistent 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 extremely concise: three sentences that cover the main purpose, role parameter, and optional cross-filter/pagination. All information is front-loaded in the first sentence. There is no superfluous text; every sentence earns its place.

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

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

Given 7 parameters, a diverse set of sibling tools, and the presence of an output schema, the description covers the key behaviors: data type, role, cross-filter, and pagination. It could mention error handling or the lack of filtering beyond country/role, but it is sufficiently complete for an agent to understand the tool's scope and basic 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 coverage is 100%, so baseline is 3. The description adds an example for other_country (e.g., Syrians in Egypt) and clarifies the role parameter with 'hosted IN' vs 'displaced FROM.' However, much of this information is already present in the schema descriptions (e.g., country ISO3 examples, year defaults). The added value is modest.

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 that the tool provides 'Yearly displacement figures for a country: refugees, asylum-seekers, IDPs, stateless and others.' This specifies the type of data and the resource (a country's displacement figures), which distinguishes it from sibling tools like asylum_applications and asylum_decisions. However, it lacks an imperative verb like 'List' or 'Get,' which slightly reduces clarity.

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 the role parameter and the optional cross-filter with other_country, giving guidance on how to query for hosted vs origin populations and cross-reference second countries. It does not explicitly state when to use this tool versus siblings (e.g., when displacement figures are needed vs asylum applications), relying on implicit differentiation. No exclusions or alternative tool names are provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context that the tool returns canonical names and ISO3 codes, and accepts free-text input, which goes 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?

Two sentences, front-loaded with purpose. Every sentence earns its place with no waste. Efficient and clear.

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 resolution tool with an output schema (not shown), the description adequately covers purpose, usage context, and basic behavior. It is complete enough to guide an AI 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?

The input schema has 100% coverage with descriptions for both parameters (query, limit). The description ties parameters to the task but does not add significant new detail beyond the schema. 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 clearly states the tool resolves free-text country queries to canonical names and ISO3 codes, with examples like 'egypt', 'DRC', 'syria'. It distinguishes from sibling tools that focus on data analysis 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 explicitly says 'Use this first when unsure how a country is spelled', providing clear guidance on when to use this tool. It does not explicitly mention when not to use it or name alternatives, but the context is sufficient.

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, covering the basic safety profile. The description adds that output includes yearly counts and recent report titles/links, which is helpful but does not disclose additional behaviors like rate limits or auth requirements. With annotations, the description's contribution to transparency is moderate.

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 consists of two short, dense sentences. The first sentence defines the tool's output in one clause; the second provides usage guidance. Every word earns its place with no redundancy or wasted 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 tool has 5 parameters, 1 required, and an output schema exists to describe return values, the description is sufficiently complete. It conveys the core purpose and a common use case. However, it could briefly mention that output schema details the structure, but this is minor given the existing schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides. The mention of 'yearly counts' implicitly relates to the year parameters, but no new semantic information is added.

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 retrieves situation reports for a country, providing yearly counts and recent report titles/links from ReliefWeb. This specific verb+resource combination, along with the mention of the source, distinguishes it from sibling tools like conflict_events or asylum_applications.

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 advises using the tool to 'ground trends and anomalies from other tools in what was actually reported at the time,' giving clear context for when to use it. While it does not list explicit alternatives or when-not-to-use scenarios, the usage guidance is strong and practical.

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 hints. The description adds value by explaining the default behavior ('by' defaults to 'asylum'), the effect of 'normalize_by' with a concrete example, and the dependency on the worldbank provider for normalization. This goes beyond what annotations provide, though it does not cover all potential behavioral nuances like 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 extremely concise, consisting of two sentences. The first sentence states the primary purpose, and the second elaborates on key parameters with an example. Every word serves a purpose, with no redundancy or unnecessary detail.

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

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

Given the tool's complexity (5 parameters, output schema present), the description covers the essential behavioral aspects: metric ranking, two main parameter groups, normalization effect, and provider dependency. The output schema handles return values, so description is complete for an agent to use the tool effectively.

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 100% coverage with descriptions. The tool's description enhances understanding by explaining the meaning and default of 'by', the impact of 'normalize_by' with a vivid example ('Lebanon and Chad ahead of large economies'), and the provider dependency. This provides meaningful context beyond the schema 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 tool ranks countries by a displacement metric for a year, specifying verb and resource. It explains the 'by' and 'normalize_by' parameters with examples, making the purpose distinct. However, it does not explicitly differentiate from sibling tools like 'refugee_population' or 'trend_analysis', preventing a score of 5.

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 usage details for parameters (e.g., default 'by' value, effect of 'normalize_by') but offers no guidance on when to choose this tool over alternatives. No explicit context for when not to use it or which sibling tool might be better suited 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 indicate readOnlyHint and openWorldHint. The description adds value by detailing analytical outputs (e.g., linear trend, CAGR) beyond the structured fields, but does not fully disclose all behavioral traits (e.g., data source, refresh frequency).

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 with no fluff. First sentence lists what the tool computes; second sentence provides default configuration. Every sentence is purposeful.

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 5 parameters, output schema, and annotations, the description covers purpose, default behavior, and analytical components. It does not need to repeat output format since an 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 100%, so baseline is 3. The description adds default metric and time range context, but does not significantly enhance understanding beyond the schema's parameter 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 analyzes displacement metric evolution for a country, listing specific outputs (yearly series, YoY changes, linear trend, CAGR, anomalous years). This distinguishes it from siblings like country_profile or demographics.

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 trend analysis but does not explicitly state when to use this tool vs alternatives like forecast or compare_countries. No exclusions or when-not guidance is provided.

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