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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered and the bar is lower. The description adds the role-scoping semantics but nothing about data source (e.g. UNHCR), reporting periodicity, gaps in coverage, or time lag that would help an agent interpret results.

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 compact sentences with the core metric front-loaded and the parameter distinction second. Slightly dense quote-wrapped phrasing ('role "asylum" (default)') but no filler 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?

An output schema exists, so return values need not be explained, and the schema documents all five parameters. What is missing is the routing information an agent needs in a 23-tool family: when this dataset is the right one versus asylum_decisions or refugee_population, and any caveats about availability across countries and years.

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, but the description genuinely refines the 'role' enum by recasting it as applications 'filed IN' vs 'filed BY nationals abroad', which differs from the schema's 'people hosted/displaced' framing and better matches the metric. It adds little for locale and the year range, which the schema already handles.

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 names a specific metric and its unit of analysis ('Individual asylum applications lodged per year') and defines the two modes of the 'role' parameter inline, which is more precise than a generic 'get asylum data'. It does not, however, explicitly contrast itself with close siblings such as asylum_decisions or refugee_population, so an agent still has to infer which of the family it wants.

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?

Usage is only implied: describing what 'role' means effectively tells the agent when to use each mode, but there is no explicit statement of when to call this tool rather than asylum_decisions, refugee_population, or latest_statistics, and no prerequisites or data-coverage caveats are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful context on what is returned (recognized, complementary protection, rejected, otherwise closed, plus recognition rate) and the default role semantics, but says nothing about coverage limitations, granularity, or rate/source 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?

Two compact clauses with the core output being front-loaded; every part contributes. Minor duplication of the role semantics that already appears in the schema description, but no filler.

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

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

With an output schema present and annotations covering safety and open-world behavior, the description need not explain returns. It supplies the category breakdown and role default, leaving only minor gaps around applicability relative to siblings.

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

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

Schema description coverage is 100%, so all five parameters including year_from/year_to defaults and the role enum are already documented. The description's restatement of the default role adds little beyond the schema, meriting the 3 baseline for a well-covered schema.

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

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

States a specific verb and resource ("decisions on individual asylum applications per year") and enumerates the outcome categories plus the recognition rate, which is more informative than a bare name restatement. It does not explicitly name the sibling it differs from (e.g., asylum_applications), so the distinction is left implicit.

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 clarifies the default of role ("asylum" = decided IN the country) but gives no explicit when-to-use guidance or routing against alternatives like asylum_applications, refugee_population, or durable_solutions. Usage is only weakly implied.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description consolidates the default behavior (role "asylum", 10-year window) into one readable sentence, which is genuinely useful, but most of its content (normalization options, worldbank requirement) is already documented in the 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?

Three tight sentences, front-loaded with the core action and scope, then defaults, then the advanced normalization option. 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 an output schema present, return values need not be explained, and the description covers action, scope, defaults, and the key optional mode. It could be slightly stronger by pointing to which sibling tools handle adjacent needs (e.g. single-country profiles or rankings).

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%, including enum meanings and defaults, so the schema carries parameter semantics. The description restates country count, the default metric, and normalize_by targets, adding no format or syntax beyond what the schema already documents — baseline 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?

States a specific verb (compare) and resource (a displacement metric) with explicit scope: 2–5 countries over a year range. The multi-country comparison framing distinguishes it from per-country siblings like country_profile and search_country without needing to name them.

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?

Gives clear default context (refugees hosted, role "asylum", last 10 years) and explains when to reach for normalize_by (to compare per-capita/per-GDP rather than absolute counts). It stops short of naming alternative tools or stating when not to use this one.

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 safety and open-world behavior are covered. The description adds genuine context — dataset provenance (ACLED via HDX) and annual granularity, which is non-obvious given year_from/year_to — but says nothing about coverage gaps, lag, or update cadence.

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 tight sentences with the core purpose front-loaded and the source in parentheses; no filler. The pairing sentence is slightly tangential but earns its place as routing guidance.

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

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

An output schema exists, so return-value detail is unnecessary, and the schema fully documents all four parameters. Purpose, source, granularity, and a sibling-pairing cue are present; only the explicit alternative conditions are missing.

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

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

Schema description coverage is 100%, including locale semantics and year-range defaults, so the schema carries the parameter burden. The description adds no syntax or format detail beyond implying an annual time range; 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?

States a specific verb/resource pair — annual conflict event counts and fatalities scoped to a country — and names the data source (ACLED via HDX). It does not explicitly contrast itself with neighbors like situation_reports or latest_statistics, so it stops short of a 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 second sentence gives a pairing hint (use alongside refugee_population/trend_analysis to relate violence and displacement), which implies a workflow context. However, there is no explicit when-to-use/when-not or differentiation from the other data-retrieval siblings, so guidance remains implied.

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 profile is covered by structured data. The description adds useful content about which datasets are merged and that figures are 'latest', but says nothing about rate limits, data recency lag, or coverage caveats. Baseline 3 is appropriate with annotations carrying the safety burden.

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

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

A single dense sentence with the scope front-loaded ('One-call humanitarian snapshot of a country') and the returned contents listed after a colon. Every clause earns its place; no filler or repetition of the title.

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

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

An output schema exists, so return-value shape need not be explained, and the description adequately frames a read-only aggregate. It stops short of noting staleness of the 'latest' data or the comparative use case versus compare_countries, which would make it fully self-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% with only 2 parameters, and the schema itself documents the ISO3/name acceptance pattern and the locale enum in detail. The description adds no syntax, format or default information beyond what the schema already 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?

Names the resource (a country) and enumerates the three payloads returned: hosted displaced population by category, population displaced FROM the country, and top origin countries. This clearly distinguishes it from siblings like search_country, compare_countries and refugee_population, though the verb is implicit ('snapshot') rather than an explicit retrieval verb.

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 phrase 'one-call' implies this consolidates data that siblings such as refugee_population, top_host_countries and demographics expose separately, so a reader can infer when to prefer it. However, there is no explicit when-to-use/when-not-to-use statement nor a named alternative, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered by structured data. The description adds a genuine data-availability caveat (recent years only), but says nothing about coverage gaps across countries or what happens when no breakdown exists. Useful but not rich.

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

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

Two tight sentences with zero filler; the core purpose comes first and the role semantics and data caveat follow. Every clause carries information an agent needs.

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

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

With an output schema present, return values need no explanation, and the country/role/locale parameters plus the data-recency constraint are covered. Only the behavior when data is unavailable for a given country is left unaddressed.

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 restates the role semantics already in the schema and adds the default value ('asylum') and the recency limitation, which is a modest increment rather than new syntax or format detail.

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

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

States a specific verb and resource: the latest age/sex breakdown of displaced people linked to a country, with the role filter spelled out. It is distinguishable from prose-heavy siblings like refugee_population or country_profile, though it does not explicitly name an alternative tool.

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

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

Gives a clear usage condition via the role semantics and the default ('asylum'), plus an implicit when-not: UNHCR only publishes demographics for recent years, so historical queries won't work. No sibling tool is named as the alternative for related questions.

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 only cover readOnlyHint and openWorldHint, so the description carries real weight: it discloses that values are period totals rather than point-in-time stocks, and that normalize_by requires the worldbank provider. It stops short of describing pagination or coverage limits, but the flow semantics are the key non-obvious trait.

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?

Core concept (flows vs stocks) is front-loaded and the three dense sentences are mostly load-bearing. The role parenthetical duplicates schema content and makes it slightly heavier than needed.

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 7-parameter tool with an output schema, the description covers the unusual semantics (flows, role inversion, cross-country filtering, normalization) that an agent could otherwise misread. Return values are properly left to the output schema.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema. The description's role explanation and the other_country example largely restate the enum descriptions, adding only marginal value beyond the structured fields.

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

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

States a specific resource (UNHCR durable solutions) and enumerates its components (refugee returns, resettlement, naturalisation, IDP returns). The explicit 'FLOWS during each year (not end-year stocks)' note distinguishes it from stock-oriented siblings like refugee_population without the agent needing to open the schema.

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

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

Clearly frames the tool's domain by contrasting annual flows against end-year stocks, which steers the agent away from refugee_population. It explains role=origin vs asylum selection, but names no explicit when-not conditions or alternative 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 and openWorldHint, so the safety profile is covered. The description adds a genuinely useful behavioral constraint not in the schema: geojson only makes sense when group_by is set because rows map to countries. It omits other non-obvious behaviors (e.g., manifest attached by default), so not a 5.

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, zero waste. The format list and the geojson caveat come first, then the usage trigger, so the most decision-relevant information is front-loaded.

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

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

With 11 parameters, an output schema, and readOnly/openWorld annotations, the description only needs to resolve format choice, the geojson caveat, and the usage context, which it does. Defaults (limit 500, manifest true) and all field semantics live in the schema, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds that by documenting a cross-parameter interaction — the geojson/group_by coupling — that the schema does not express, adding real meaning beyond the field-level 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?

States a specific verb ('Export') plus the resource ('normalized records from any dataset') and enumerates the output formats, including a real caveat about geojson. It does not name or differentiate against the obvious sibling export_report, so an agent must infer the raw-vs-formatted distinction.

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?

"Use this when the user wants raw data to download or paste elsewhere" gives a clear usage trigger. However it provides no explicit when-not or names the alternative (export_report), leaving the raw-vs-report boundary to inference.

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

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

Annotations already declare read-only and open-world, and the description adds substantial behavior beyond them: HTML is one self-contained file with embedded Arabic/Latin fonts, inline SVG charts, citations and the manifest; PDF is rendered by local headless Chrome/Chromium/Edge and silently degrades to HTML with an explanation if unavailable; Arabic locale is right-to-left. It also discloses the return shape (a resource link unless `inline` is true).

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 dense paragraph, but it is front-loaded with the core purpose followed by format, locale, and return semantics in a sensible order. Every clause carries information; it is slightly long and clause-heavy but not padded.

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 9-parameter, no-required-parameter tool with an output schema, the description covers the input modes, format trade-offs and fallbacks, locale/RTL behavior, and the return mechanism. Nothing an agent needs to invoke it correctly is missing, and return-value detail is rightly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: `country` and `markdown` are mutually exclusive inputs, and `inline` toggles between an inline file and an `export://` resource link. It also restates the html default and the PDF fallback behavior, which enriches `format` beyond its enum description.

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

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

States a specific verb (export) and a precisely scoped resource (a print-ready, self-contained document), then names the two input modes: a full country report via `country`, or another tool's markdown via `markdown`. This distinguishes it cleanly from `generate_country_report` (which produces the report) and `export_data` (which exports data, not a formatted document).

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?

Gives clear usage context: pass `country` for a full report, pass `markdown` for output from tools like `trend_analysis` or `durable_solutions` (and says to omit `country` in that case). It does not, however, explicitly contrast itself with the closest sibling, `generate_country_report`, or state when not to export (e.g. for machine-readable 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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value with data provenance ('IPC via HDX'), the 'latest available' default, and the definitional note that phase 3+ is the headline, but says nothing about rate limits, coverage gaps, or whether a country can lack an IPC analysis.

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 tight sentences with zero filler; the metric and scope are front-loaded, and the trailing provenance tag ('Data: IPC via HDX') is short and earns its place by signaling the open-world source.

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

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

An output schema exists, so return-value explanation is not required, and annotations plus a 100%-described 3-param schema cover the rest. The description supplies the interpretive context (phase scale, headline phase 3+) an agent needs to call and explain results correctly.

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

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

Schema description coverage is 100% — year (default latest), locale (en/ar with RTL note), and country (name or ISO3) are all documented in the schema itself. The description adds no parameter-level syntax or format detail beyond that, 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?

States a specific resource (IPC food-insecurity phase breakdown) with the exact output shape (people per phase 1–5) and the headline metric (phase 3+ 'crisis or worse'). This is unambiguous and clearly separable from generic siblings like latest_statistics 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 trigger context is implied by 'Latest ... for a country' — an agent can infer this is the tool for food-insecurity questions about a specific country. However, there is no explicit when-to-use/when-not guidance and no sibling is named as the alternative (e.g., for non-IPC hunger indicators or cross-country comparison).

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 cover the safety profile (readOnlyHint, openWorldHint), lowering the bar, and the description adds substantial method transparency: OLS prediction intervals at 80%/95%, automatic detection and reporting of structural breaks, and the since_break fitting behavior. It does not mention data source, computational cost, or fallback when history is insufficient, keeping it from a 5.

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

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

Three tight sentences with the core purpose front-loaded, followed by statistical detail and the caveat. Every sentence carries weight, though the density of clauses makes it slightly heavier than necessary.

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 7-parameter, read-only forecasting tool with an output schema already covering return structure, the description supplies the semantic framing an agent needs: method, interval semantics, break handling, and an explicit caveat. Nothing critical is missing, though failure/edge-case behavior is not mentioned.

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

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

With 100% schema description coverage the schema already documents every parameter, so baseline is 3. The description's references to since_break, chart types and the horizon largely restate what the schema already says, adding little new syntax or format 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?

States a specific verb+resource with method and scope: 'Naive linear projection of a displacement metric 1–5 years ahead, based on the last 10 years.' This clearly separates it from siblings like trend_analysis (historical description) and latest_statistics. It does not name any sibling explicitly, so it falls just short of a 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?

It gives genuine usage context for one parameter ('since_break=true fits only the data after the latest break') and a presentation rule ('always present it with that caveat'). However it never states when to reach for this tool versus trend_analysis or other forecasting-adjacent siblings, so the guidance is implied rather than 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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavioral detail beyond the schema: the per-format rendering of changepoints (svg, vega-lite; Chart.js via chartjs-plugin-annotation) and the normalize_by scaling behavior.

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

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

Three tight sentences, front-loaded with the core action before format/option details. Little waste, though the format list partially duplicates schema enum descriptions.

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 covering return values and annotations covering the safety profile, the description supplies the remaining context (formats, normalization, changepoints). Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters with enums and ranges. The description largely restates format and normalize_by semantics rather than adding new meaning, 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 states a specific verb and resource: 'Render a displacement metric for one or more countries as a chart specification.' The purpose is unmistakable and clearly distinct from generate_map or generate_country_report, though no sibling is named explicitly.

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?

Usage is implied by the task ('render ... as a chart specification') and format choices are enumerated, but there is no explicit when-to-use vs when-not guidance or named alternative tool. An agent must infer that this is the charting tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that it 'Reports progress while assembling,' a useful behavioral trait (long-running with progress updates), but it does not disclose auth needs, rate limits, or performance characteristics 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 sentences, front-loaded with the core action and content list, followed by a progress note. 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?

For a multi-section report generator with an output schema, the description sufficiently conveys the content and the progress behavior. It omits any caveats about data availability or runtime, but those are minor given the annotations and 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 coverage is 100%, so the schema documents all four parameters (locale, country, year_from, year_to). The description adds no parameter-level meaning beyond what is already in 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?

Composes a full markdown humanitarian situation report for a country and enumerates its sections (key figures, refugee trend with chart, origins, asylum decisions, demographics). The verb and resource are specific, though it does not explicitly distinguish itself from siblings like situation_reports or export_report.

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 when-to-use guidance or alternatives are provided. The description states what the tool does but not when an agent should choose it over country_profile, situation_reports, or export_report.

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 safety is covered. The description adds genuinely new behavioral context: the output is a static FeatureCollection of centroids with point size as the encoding channel, which tells the agent what can and cannot be done with the result. It omits any note on limits or cost, but nothing contradicts 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, zero filler, and the most decision-relevant fact (the output format) is front-loaded before the viewer hints and the parameter note.

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

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

With an output schema present, return values need not be spelled out, and all five optional params are fully documented in the schema. The description covers the conceptual shape of the output and the by semantics; it could go slightly further on defaults (latest year, top 25) but those live in the 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 schema already defines all five parameters including the by enum and locale. The description restates the by semantics ('asylum' maps host countries, 'origin' maps origins) without adding syntax or format detail, 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 names the precise artifact produced (a GeoJSON FeatureCollection of country centroid points, sized by a displacement metric), which is a specific verb+resource rather than a restatement of the name. That output form also implicitly separates it from sibling generators like generate_chart and generate_country_report.

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

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

It gives downstream consumption guidance ('drop it into any GeoJSON viewer — geojson.io, Leaflet, Kepler') and disambiguates the by enum, but never states when to pick this over generate_chart or compare_countries. Usage is implied by the output type rather than stated as a selection rule.

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 safety and scope are covered. The description adds the content categories returned, but says nothing about auth needs, rate limits, or caching. With annotations carrying the safety profile, this is adequate but not rich.

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

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

Two sentences, no filler, with the resource and return contents front-loaded before the usage instruction. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the description already sketches the payload categories. For a zero-required-param discovery tool this is close to complete, though it could note the relationship to provider_health.

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% and the single locale parameter is fully documented in the schema, including enum semantics and RTL behavior. The description never mentions locale, so it adds nothing beyond the schema; 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?

States a specific verb (describe) and resource (connected data providers), then enumerates what is returned: datasets served, metrics available, attribution and terms. This clearly separates it from the data-querying siblings like search_country 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?

"Call this to learn what data exists before querying" gives an explicit trigger condition and sequencing relative to the query tools. It does not name a specific alternative such as provider_health, so the routing is clear but not exhaustive.

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 profile is covered. The description adds useful context on the data provenance and what the payload compares, but says nothing about granularity of rows, missing-data behavior for countries without appeals, or volume of results returned.

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 dense sentence with the resource and its key derived metric front-loaded, and no filler. It is slightly telegraphic (no leading verb), but every clause earns its place.

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

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

With an output schema present, return-shape explanation is unnecessary, and annotations cover the read-only profile. The description supplies the source and the two quantities being compared, which is enough for an agent to call this correctly; only usage routing and data-coverage caveats are absent.

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%, and the schema documents country formats, the locale enum, and the year_from/year_to defaults, so the description is not needed for parameter meaning. It adds only the implicit notion of a per-year series, which is baseline-level 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?

Names the exact resource and comparison ('appeal requirements vs funding received per year') plus the derived metric (coverage percentage) and the upstream source (OCHA FTS via HDX). This is clearly distinguishable from siblings like food_security, refugee_population, or country_profile without opening any schema.

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

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

The description says what the data is but never when to reach for this tool over alternatives such as country_profile or latest_statistics, nor any prerequisite or scope caveat. Usage is only inferable from the resource name.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the useful behavioral fact that output scope depends on whether country is supplied, but it omits data freshness/update cadence and says nothing about the return structure or failure modes.

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

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

Three short front-loaded fragments with no filler, and the global-vs-country distinction is stated up front. Slight redundancy with the schema's country parameter description keeps it from a 5.

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

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

An output schema exists, so return values need not be explained. However, for a tool whose selling point is being the 'most recent' figures, the description never states what 'latest' means (reference date, update frequency, dataset vintage), and the role=origin case is silently unaddressed.

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 role, locale, and country parameters are already fully documented in the schema, which sets the baseline at 3. The description only partially reinforces this—'latest hosted figures' loosely matches role=asylum and arguably understates role=origin (displaced FROM the country), which the schema covers far better.

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

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

States a specific verb+resource ('Most recent displacement figures') and immediately narrows scope by country presence/absence. It does not name or differentiate itself from close siblings such as refugee_population, country_profile, or trend_analysis, so the agent must infer which one to choose.

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

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

It gives the two invocation shapes (with country vs. without) but frames them as parameter behavior rather than as when-to-use guidance against alternatives. No exclusions or sibling routing are provided, so usage is only implied.

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 readOnlyHint=true. The description adds value beyond that: it confirms no one is contacted, explains that a snapshot baseline is persisted in server cache and/or returned to the caller, and notes the output carries stable ids and severities. The storage side effect and id stability are behavioral details the annotations do not cover.

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

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

Three sentences, front-loaded with the core comparison purpose before the output and read-only notes. The first sentence is dense but every clause earns its place; no filler.

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

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

For an 11-parameter tool with an output schema and annotations, the description covers the comparison logic, the snapshot lifecycle, and the read-only guarantee adequately. Because a return-value schema exists, it need not describe outputs in detail. Minor gap: no explicit routing to sibling tools.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters including enums (role, locale), defaults, and the snapshot object structure. The description's comparison semantics (latest vs previous year, thresholds, revisions) add narrative context but no parameter-level syntax or format beyond what the schema provides. 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 states a specific verb and resource: it checks a country's UNHCR displacement figures for changes, comparing the latest year to the previous one and detecting releases/revisions against a snapshot. The scope is clear and concrete. It does not, however, explicitly differentiate itself from siblings like trend_analysis or latest_statistics, leaving that to inference.

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

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

It clearly conveys the context of use ('changes worth attention', comparing against a stored or passed snapshot) and explains the round-trip baseline mechanism for repeated calls. There is no explicit statement of when NOT to use it or a named alternative to prefer, so it stops short of full when/when-not 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral scope beyond that by specifying that it checks every connected provider and includes latency and reachability, though it does not discuss failure modes, performance cost, or partial-outage semantics.

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 tightly written sentences: one defines the operation and its scope, the second supplies the diagnostic use case. Nothing is wasted and the purpose is front-loaded before the usage condition.

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 low complexity, rich annotations, full schema descriptions, and existing output schema, the description provides everything an agent needs to select and invoke the tool correctly. It covers what is checked and the situation that calls for it without needing to restate return values or optional locale details.

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 has 100% description coverage for the single optional locale parameter, including enum values and output-language behavior. The description adds no parameter-level information, so the baseline of 3 is appropriate because the schema already carries the full explanatory burden.

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 a specific operation: a liveness check across every connected data provider, with latency and reachability called out as checked dimensions. It is distinguishable from the data-retrieval and export siblings in substance, but it does not explicitly name or contrast itself against any sibling tool, keeping it at a 4 rather than a 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?

It gives a concrete condition for use: when queries fail and the agent needs to tell upstream outages apart from bad parameters. This is clear and actionable, but it does not state when not to use the tool or name an alternative diagnostic path, so it falls short of the 5-level rubric.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered elsewhere; the description still adds real context the annotations do not: the result set is yearly series across five displacement categories, role inverts the direction of the data, results are paginated, and a second country can be cross-filtered. It stops short of noting coverage caveats, rate limits, or data vintage.

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

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

Three short sentences, front-loaded with what the tool returns, then the role switch and cross-filter, then pagination. No filler and nothing buried.

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 8 parameters, an output schema, and an open-world read annotation, the description covers the essentials an agent needs to call it correctly. It omits only secondary context such as the data source/vintage or the fact that year_from/year_to default to a 10-year window rather than the full history.

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's role and other_country explanations largely restate what the schema already documents in detail (including the same Egypt/Syria example), adding little semantic value 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?

"Yearly displacement figures for a country: refugees, asylum-seekers, IDPs, stateless and others" gives a concrete resource and enumerates the metric families returned, so an agent knows exactly what data comes back. It never names a sibling (e.g. asylum_applications, top_host_countries) to disambiguate against, which keeps it short of a 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 role semantics are spelled out with the default stated ("asylum" (default) = hosted in the country; "origin" = displaced from it) and a worked cross-filter example is given, so the agent knows which mode to pick for a given question. There is no guidance on when to prefer this tool over the related asylum/durable_solutions tools, so no exclusions or alternatives are covered.

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 profile is covered. The description adds that resolution yields canonical names plus ISO3 codes, but says nothing about matching behavior (fuzzy vs exact), multiple-match/disambiguation handling, or ranking — useful context that would lower ambiguity for a resolver tool.

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, zero waste. The resolution behavior is front-loaded and the usage cue follows immediately.

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

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

With an output schema present, return values need not be described, and all three parameters plus annotations are documented. The one gap is disambiguation behavior when a query matches several countries, which an agent calling a resolver would benefit from knowing.

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%, documenting query, limit (max 20, default 5), and locale (en/ar with RTL note), so the baseline is 3. The description's examples ("egypt", "DRC", "syria") loosely illustrate that query accepts fragments and abbreviations, but add no syntax or format 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?

States a specific verb (resolve) and resource (free-text country query) and names the output form — canonical names and ISO3 codes — with three concrete query examples. It does not explicitly differentiate itself from country-consuming siblings like country_profile or compare_countries, so it falls short of a 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?

"Use this first when unsure how a country is spelled in the data" gives a clear triggering condition and positions the tool as a pre-step. It names no alternatives or when-not conditions (e.g., when an ISO3 is already known), so it stops short of explicit routing.

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 profile and external-source nature are partly covered. The description adds the provenance (ReliefWeb) and the fact that the returned titles/links are 'most recent', which is useful context, but says nothing about rate limits, coverage gaps, or freshness lag 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 sentences, zero filler: the first front-loads what is returned and the second supplies the usage rationale. Every clause earns its place.

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

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

With an output schema present, the description need not explain return values, and annotations cover the read-only/open-world profile. It states source and purpose adequately; only the relationship to the many sibling analysis tools remains slightly underspecified.

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% and all six parameters, including the locale enum and the year/max_reports bounds, are documented in the schema itself. The description adds no additional parameter meaning (e.g. it never clarifies the query filter or the year defaults), so the baseline of 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 names a specific resource ('situation reports published about a country') and precisely enumerates the payload ('yearly counts plus the most recent report titles and links'), even citing the source (ReliefWeb). It does not explicitly contrast itself with any sibling tool, so it stops short of the top tier, but an agent can still tell what it returns without opening the schema.

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

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

'Use it to ground trends and anomalies from other tools in what was actually reported at the time' gives a clear situational trigger and implies it complements rather than replaces analysis tools like trend_analysis or conflict_events. It gives no explicit when-not or named alternative, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, external-data read. The description adds the normalization semantics (population/gdp denominators) and a concrete example of the ranking effect, but says nothing about pagination, ranking ties, or the normalize_by worldbank provider dependency beyond what the schema already notes. Adequate but not rich.

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

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

Three sentences, front-loaded with the core operation before the parameter nuances. The closing example ('Lebanon and Chad ahead of large economies') is illustrative but borderline flourish rather than essential instruction.

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

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

An output schema exists, so return values needn't be described, and annotations cover the safety profile. The description covers the main parameter-driven modes; only the metric parameter's accepted values and the worldbank provider requirement for normalization rely entirely on the 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 coverage is 100%, so the baseline is 3. The description restates much of what the schema already says ('asylum' ranks hosts, 'origin' ranks origins) and adds only the default for by and the illustration of normalization; it does not explain metric, limit, or locale 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?

States a specific verb and resource ('Rank countries by a displacement metric') and immediately clarifies the two modes via the by parameter, so an agent distinguishes this from siblings like refugee_population or compare_countries. The title and description align, with no tautology.

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 tells the agent when to use by="asylum" versus by="origin" and when to set normalize_by. It gives clear context for the parameter-driven use cases but does not compare against sibling tools (e.g. when to prefer compare_countries or trend_analysis), so no explicit alternative routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. Beyond those, the description adds a genuine methodological caveat — that changepoint power depends on extending year_from — but the rest of the sentence just enumerates returned statistics, which duplicates the output schema, and nothing is said about cost or data coverage 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?

A single dense sentence, front-loaded with the core action followed by the output enumeration and the one actionable tip. Every clause carries information, though the long list of statistics partially duplicates what the output schema already declares.

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 100%-covered schema and an existing output schema, the description need not explain return values, yet it still sketches them for orientation and adds the changepoint-window caveat. Nothing essential for invoking the tool correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by linking the year_from parameter to the analytical quality of changepoint detection, a relationship the schema does not express, and by restating the metric/role defaults in prose context.

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

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

States a specific verb and resource ('Analyse how a displacement metric evolved for a country') and enumerates the exact analytical outputs: yearly series, YoY changes, linear trend with slope/R², CAGR, z-score anomalies, and changepoints. This is clearly distinct from siblings like forecast (prediction) or monitor_changes (short-term deltas).

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 default operating behaviour ('Default: refugees hosted, last 10 years') and one conditional tip ('widen year_from for better changepoint power'), which implies when the tool is appropriate. However it never names an alternative sibling (forecast, compare_countries, monitor_changes) or states when NOT to use this tool, so routing guidance is left to inference.

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