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 adds real scope context — this is applications lodged, not decisions or refugee stock — but says nothing about coverage gaps, data provenance, or rate/auth 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?

Two short sentences with the measurement grain front-loaded and the mode disambiguation second. There is a small formatting defect (unbalanced quote before the first 'asylum'), but no wasted content.

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, all five parameters are fully documented, and annotations carry the safety profile. The description only needed to add grain and the role disambiguation, which it does.

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 role explanation in the description largely restates the schema's own enum text ('hosted IN' vs 'filed BY'), adding only mild framing rather than new operational 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+unit ('Individual asylum applications lodged per year'), which separates it from flow/stock siblings like refugee_population and asylum_decisions. It does not name any sibling explicitly, so the differentiation is inferential rather than stated.

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 what the two role modes mean and which is the default, which implies when to pick each, but gives no explicit 'use X instead when...' routing against siblings such as asylum_decisions or refugee_population. Usage is implied rather than directed.

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, and the description adds genuinely new context: what gets returned (recognized, complementary protection, rejected, otherwise closed) and a derived recognition rate. It does not disclose the data source, reporting lag, or how year defaults behave when no data exists, but it goes beyond restating 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 clauses with zero waste: outcomes and metric first, the default-role caveat last. Nothing is buried and nothing is repeated from the schema.

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?

Five parameters are fully documented and an output schema exists, so return structure needn't be explained. The only real gap is the absence of any guidance on choosing this tool over the adjacent applications/solutions tools, which matters given a dense sibling set.

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 already carries its own documentation and the baseline is 3. The description adds a small interpretive gloss on role ("decided IN the country"), which sharpens the distinction between decisions and the schema's "hosted IN the country" wording, but adds nothing about year range or locale.

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 (asylum decisions) and enumerates the outcome categories plus the derived recognition rate, so an agent knows it returns decision outcomes rather than application counts. It doesn't name the sibling it differs from (asylum_applications), leaving the distinction to be inferred.

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 rather than stated — the categories and recognition rate signal an analysis of decision outcomes, but there is no explicit when-to-use, when-not-to-use, or pointer to asylum_applications or durable_solutions. The closing note about role 'asylum' being the default is a semantic clarification, not routing 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 profile is covered. The description's default behavior (asylum role, 10-year window) largely duplicates defaults already documented in the schema, and it adds no detail on rate limits, provider fallback, or what happens when a country is unknown.

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 compact sentences, front-loaded with the core comparison scope followed by defaults and the normalization option. No filler or restatement 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?

With an output schema present, return values need not be explained, and the 7 parameters are fully documented in the schema. The description is sufficient to call the tool correctly, though it could mention locale behavior or metric availability to be fully self-contained.

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 every parameter carries an enum or a documented default, so the schema does the heavy lifting. The description restates the 2–5 country bound and the normalize_by meaning but adds no syntax or edge-case guidance beyond the schema.

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

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

The description names a specific verb and resource — comparing a displacement metric across 2–5 countries over a year range — which is concrete enough to distinguish it from single-country siblings like country_profile or search_country. It stops short of explicitly naming the alternatives (trend_analysis, top_host_countries) that an agent might confuse it with.

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 scope statement and the stated defaults (refugees hosted, last 10 years), so an agent knows what happens with no arguments. However, there is no explicit when-to-use / when-not guidance and no routing to alternatives such as trend_analysis or top_host_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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and openness are covered. The description adds the data source (ACLED via HDX) and the annual aggregation level, but does not disclose coverage limits, data freshness, or what the annual counts represent beyond the metric names.

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 purpose and followed by the analytical pairing. Every clause contributes information and there is 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, the description need not explain return values, and all four parameters are documented in the schema. It provides source and pairing context, though it could do more to state geographic/coverage limitations for an open-world dataset.

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 fully documents country, year_from, year_to, and locale. The description only reinforces the country and annual scope; it adds no parameter-level meaning beyond what the schema already provides, making the baseline 3 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 states a specific resource and metric: annual conflict event counts and fatalities for a country, sourced from ACLED via HDX. It distinguishes itself from generic country tools by naming the data domain, though it does not explicitly contrast with the closest siblings.

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

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

It suggests pairing with refugee_population/trend_analysis to relate violence and displacement, which implies a useful analytical context. However, it gives no explicit when-to-use versus alternatives, no exclusions, and no guidance on choosing this over latest_statistics or country_profile.

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 context about the composite nature of the response ('one-call', 'latest', 'by category'), though it does not discuss data freshness, sourcing, or limitations.

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

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

A single, front-loaded sentence that efficiently communicates the tool's scope. Every clause adds information about what is included, with no redundant or filler 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 that annotations cover safety, an output schema exists, and parameters are fully documented, the description is largely complete. The main missing element is guidance on how this tool relates to the many sibling tools, which would help an agent select it 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%, so both parameters (country and locale) are already fully documented. The description does not add any parameter-level meaning beyond what the schema provides, making the baseline 3 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 names a specific resource (country) and enumerates the three data components returned: hosted displaced population by category, population displaced from the country, and top origin countries. It is clear what the tool does, but it does not explicitly differentiate itself from siblings like refugee_population, top_host_countries, or 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?

The phrase 'One-call humanitarian snapshot' implies this tool is useful for a quick overview instead of multiple calls, but there is no explicit guidance on when to use it versus alternatives. With many sibling tools covering overlapping country data, the lack of routing guidance is a notable gap.

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 genuinely useful behavioral context beyond that: the recency/coverage constraint and the meaning of the default role value, which the agent would otherwise have to guess.

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

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

Two dense sentences, front-loaded with the core purpose and followed by the scoping/coverage caveat. No redundant phrasing or filler.

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

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

An output schema exists so return values need not be explained, and all three parameters are documented. The coverage caveat and role semantics round it out; only the absence of sibling routing guidance leaves a small gap.

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 both enum parameters (role, locale) carry their own descriptions, so the schema does the heavy lifting. The description's role gloss largely restates the schema, adding no format or edge-case detail, which is the baseline case.

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 gives a specific resource and dimension ('latest age/sex breakdown of displaced people') and defines the country scoping via the role parameter, which distinguishes it from aggregate tools like refugee_population. It does not explicitly name any sibling as an alternative, so differentiation relies on the agent's 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 states the default role ('asylum') and a real usage boundary ('UNHCR publishes demographics for recent years only'), which implies when not to use the tool. However, no alternative tool or when-to-use-this-over-siblings guidance is given.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added value is the flow semantics and the note that a period total is reported — genuinely useful context a caller could not infer. It also discloses the provider dependency for normalization. Minor gaps remain (coverage/sparsity of UNHCR reporting for some countries, what a missing year yields), so 4 not 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?

Front-loaded with the resource and the flow-vs-stock caveat before the role mechanics, so the most important disambiguation lands first. Dense with parentheticals and slightly crowded in the second half, but every sentence carries information and nothing is 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 7 parameters, an output schema, and read-only annotations, the description covers the non-obvious decisions (role direction, flow totals, normalization provider requirement, cross-country filter). Year range and locale are left to well-documented schema entries, which is appropriate. It stops short of saying how incomplete country coverage is handled by this open-world 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 coverage is 100%, so the baseline is 3; the description earns above that by re-explaining role with worked semantics ("returns home, resettled/naturalised abroad" vs "resettled TO it, naturalised IN it") and by giving a concrete other_country example (Syria + Lebanon → Syrians returning from Lebanon). It matches rather than merely restates the schema's role wording, adding interpretation 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 specific resource (UNHCR durable solutions: refugee returns, resettlement, naturalisation, IDP returns) and immediately clarifies it reports FLOWS per year rather than end-year stocks. That flow-vs-stock distinction is exactly what separates it from portfolio siblings like refugee_population, so an agent can route 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?

Gives clear operational context for the key decision point: role "origin" (default) covers solutions for people FROM the country, role "asylum" covers people resettled to / naturalised in it, with concrete glosses in parentheses. It also flags the worldbank dependency for normalize_by. It does not explicitly name a sibling alternative or a when-not-to-use case, which keeps it at 4 rather than 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds one genuinely useful constraint — geojson only makes sense with group_by, since rows map to countries — but says nothing about output size, truncation at the limit cap, or manifest/codebook side effects beyond what the schema states.

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 format contract front-loaded and the usage cue second. The parenthetical geojson caveat is slightly awkward but carries real information, so nothing is wasted.

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 full output schema, 100% parameter coverage and annotations in place, the description only needs to frame purpose, formats and usage, which it does. Minor gaps around result size and how include_manifest/include_codebook affect the payload are left to 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 baseline would be 3. The description earns a bump by documenting a cross-parameter dependency (format=geojson requires/implies group_by) that no single parameter description conveys.

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 (export normalized records) and enumerates the four output formats, so the agent knows exactly what it produces. It does not name the closest siblings (export_report, generate_chart, generate_map), so differentiation 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?

"Use this when the user wants raw data to download or paste elsewhere" gives a clear use condition that implicitly separates it from report/chart/map generators in the sibling list. It offers no explicit when-not rule or named alternative.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that PDF is produced by a local headless Chrome/Chromium/Edge with a documented HTML fallback if none is present, that HTML is a single self-contained file with embedded fonts, inline SVG and citations, and that the result is a resource link unless `inline` is true. These are exactly the operational facts an agent needs before invoking.

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

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

A single front-loaded paragraph that leads with what the document is and the two input modes, then format behavior, then return shape. Dense with parentheticals but nearly every clause carries operational information; a minor trim of the format parenthetical would help.

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

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

With 9 optional parameters, an output schema, and annotations in place, the description covers the remaining burdens: input-mode selection, format semantics and fallback, RTL behavior, and the link-vs-inline return contract. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: `format` defaults to html and what pdf entails, `inline` switches between resource link and embedded file, and `locale: "ar"` yields right-to-left rendering. Only `title`, `year_from`/`year_to` and `include_manifest` are left entirely to 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: renders a print-ready self-contained document from either a country report or arbitrary markdown. The two input modes are explicit, which implicitly separates it from content-generating siblings like generate_country_report. It does not, however, contrast itself with export_data, the other export-oriented sibling.

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?

Clear routing rules: pass `country` for a full country report, pass `markdown` for output from trend_analysis or durable_solutions, and default to html. No explicit when-not-to-use or alternative-tool guidance (e.g. when to prefer export_data or generate_country_report) is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful context: the data provenance (IPC via HDX) and the definition of the headline phase 3+ 'crisis or worse'. It doesn't mention coverage gaps, staleness, or what 'latest available' means in practice, so it adds some but not rich context.

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

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

Two tight sentences, front-loaded with the resource and metric, then the headline definition and source. Nothing wasted and no backward reference 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?

Output schema exists, so return values needn't be explained, and the description supplies the source, the phase breakdown and the headline metric. Only gap is any caveat on data coverage/recency for a tool marked openWorld, which is minor.

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% — country accepts name or ISO3, year defaults to latest, locale enum documented — so the schema already carries parameter meaning. The description adds nothing parameter-specific; 'for a country' merely restates the required param. 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: 'Latest IPC food-insecurity phase breakdown for a country', naming the metric (people per phase 1-5) and headline indicator (phase 3+). An agent can tell this apart from conflict_events or humanitarian_funding by the IPC framing, 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?

The description gives no when-to-use, when-not-to-use, or alternative routing. It implies this is the food-security lookup, but an agent comparing against conflict_events, humanitarian_funding or country_profile gets no guidance on which to pick.

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 say readOnly/openWorld; the description adds the estimation basis (last 10 years), interval levels, structural-break detection and reporting, the minimum-data condition for since_break, and an explicit epistemic caveat. That is exactly the behavioral context an agent needs to interpret and present the output responsibly.

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 dense sentences, front-loaded with what the tool computes, then the break handling, then the caveat. No filler and nothing redundant with the schema.

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; the description covers method, data window, break behavior, optional charting and the mandatory caveat. Nothing material is missing for correct invocation and interpretation.

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 still adds value by explaining the 1–5-year horizon, the 10-year fitting window, and what since_break actually does to the fit. It does not clarify metric options or chart payload differences beyond what the schema already states.

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 ('naive linear projection of a displacement metric 1–5 years ahead') plus the method (OLS, last 10 years, 80%/95% intervals). It does not name or contrast with the sibling 'trend_analysis', so an agent still has to infer which one to pick when both could apply.

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 operative guidance: since_break=true fits only post-break data (needs ≥3 years), and the result must always be presented with the 'not a UNHCR planning figure' caveat. It stops short of explicit exclusions or pointing to trend_analysis as the descriptive alternative.

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

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

Annotations already declare readOnly and openWorld, so the bar is lower, yet the description adds real behavioral context: a provider dependency for normalization, and format-specific rendering limits for changepoint markers (SVG and vega-lite native, Chart.js only via chartjs-plugin-annotation). It does not cover failure modes, e.g. what happens when a metric is unavailable for the requested role, which keeps 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?

Four dense sentences, no preamble, with the core action front-loaded and option details after. The format enumeration is essentially a list but every item carries differentiating information (versions, artifact type), so nothing is wasted.

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

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

With 10 parameters, full schema coverage, an output schema, and readOnly/openWorld annotations, the description covers the gaps structured fields cannot: per-format rendering capability and provider dependency. It stops short of describing behavior for invalid or unavailable metrics, which is the main remaining unknown for a 10-parameter 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 coverage is 100%, so the baseline is 3; the description earns above that by adding meaning the schema lacks — the plugin requirement for chartjs changepoints and the concrete version artifacts per format. It repeats the normalization denominators already documented in the schema, which limits the upside.

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: 'Render a displacement metric for one or more countries as a chart specification.' The four output formats and their concrete artifacts (Chart.js v4 config JSON, vega-lite v5 spec, mermaid xychart block, standalone SVG) make it unmistakably a charting tool rather than a map (generate_map) or a data comparison (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?

Usage is implied by the resource — you call this when you want a chart — but the description never states when to prefer it over generate_map, trend_analysis, or compare_countries, nor any prerequisites. The only conditional guidance is per-option (normalize_by requires the worldbank provider, show_changepoints works differently per format), not tool-selection 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 only cover readOnlyHint and openWorldHint; the description adds genuinely new behavior: output is markdown, a chart is embedded, and it streams "reports progress while assembling," which tells the agent to expect progressive output. It stops short of saying how long or how expensive a full report is, or whether failures partially stream.

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

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

A single sentence that front-loads the action and output artifact, then lists sections in the order they appear. No filler, nothing redundant with 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 values need no explanation, and the description covers the composite sections that matter for deciding whether one call replaces several. For a read-only generation tool with full schema coverage, nothing needed 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 country, locale, year_from and year_to are already fully documented at the field level. The description adds nothing about them — not even that the year range drives the trend chart — 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?

Uses a specific verb ("Compose") on a specific resource ("full markdown humanitarian situation report for a country") and enumerates the sections included, which separates it from aggregating siblings like country_profile or latest_statistics. It never names a sibling tool outright, so the differentiation is inferential rather than explicit.

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

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

The content list implies when this is the right tool (a narrative report rather than raw statistics), but there is no explicit "use this when…" or "use X instead for…" guidance against siblings such as situation_reports, export_report, or generate_chart. The agent must infer the routing from the phrasing alone.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description adds real value by disclosing the exact return shape (FeatureCollection of centroid points) and what sizing represents. It omits pagination/truncation behavior and how the limit interacts with the map, which would fully close the loop.

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 output artifact before the practical hint. It is tight, though the trailing by= clause is redundant with the schema and could have been spent on something the structured fields don't already say.

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 detailed, and the description still characterizes the payload usefully. For a read-only generator with five fully documented, all-optional parameters, an agent has enough to call it correctly; only the limit-to-map interaction is 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% and each parameter already carries a rich description including enum meanings, defaults, and bounds. The description's by="asylum"/by="origin" sentence restates what the schema says verbatim 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?

States the concrete artifact produced — a GeoJSON FeatureCollection of country centroid points sized by a displacement metric — which is more specific than the name alone. It also conveys the format's interoperability intent (geojson.io, Leaflet, Kepler). It does not explicitly contrast itself with generate_chart or other output siblings, so an agent must infer 'map vs chart' from the format description.

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 rather than stated: the viewer list tells the agent this is for visual map consumption, but there is no explicit 'use this when you need a geographic visualization instead of generate_chart' or any exclusion. The by= guidance is usage-relevant but duplicates the schema enum.

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 known. The description adds that results include attribution and terms of use, which is useful behavioral context, but says nothing about freshness, caching, or whether the provider list is static or live.

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: what it returns first, then the call condition. 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?

One optional parameter with a fully documented schema, an output schema covering return shape, and annotations covering safety. Nothing an agent needs in order to invoke this correctly is missing.

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

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

The single locale parameter has 100% schema description coverage, including enum values and the note that structured fields stay in English. The description adds no parameter guidance, which is acceptable given the schema does the work, 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?

"Describe the connected data providers" names a specific verb and resource, and the follow-on clause enumerates the content returned (datasets, metrics, attribution, terms). It implies a discovery role distinct from the data-query siblings, though it never names one 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?

"Call this to learn what data exists before querying" gives a concrete usage context and sequencing relative to the query tools. It stops short of stating when not to call it or naming a specific alternative, but the condition is clear.

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 genuinely useful provenance (OCHA FTS via HDX) and confirms the returned granularity, but says nothing about coverage gaps (countries without an appeal), latency, or upstream data 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?

A single front-loaded sentence that identifies the metric, the unit, the scope and the source with no filler. Nothing in it is redundant.

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 source attribution plus coverage percentage give the agent enough to call it confidently. The only real gap is behavioral edge cases, such as how a country-year with no appeal is represented.

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 country, year_from, year_to and locale are all documented in the schema itself, including defaults and the ISO3/name flexibility. The description only echoes the country and per-year scoping and adds no new semantics beyond that, which is the baseline 3 for a fully documented schema.

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

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

The description names a precise metric pair (appeal requirements vs funding received), the unit of aggregation (per year), and the geography (a country), plus the coverage percentage. It is far more specific than a tautology and clearly distinct from siblings like country_profile or food_security, though it never explicitly contrasts itself with 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?

Usage is only implied: an agent can infer this is the tool for funding-gap questions, but there is no explicit when-to-use statement, no when-not, and no pointer to an alternative sibling when the user wants, e.g., general country context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the description only needs to add context. It adds the scope split (global vs country) but says nothing about data vintage despite the 'most recent' claim, nor about whether origins data is included. No contradiction with annotations.

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

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

Two short sentences, zero filler, with the scope distinction front-loaded in the second sentence. Nothing could be removed without losing routing information.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers the primary global/country path. The gap is the role parameter: the description frames the output as "hosted figures", which may steer an agent away from role=origin even though the schema supports it. Adequate for the common case, incomplete at the edges.

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 role, locale, and country are all fully documented in the schema. The description reinforces the country/no-country behaviour but adds no syntax or semantics beyond it, and its phrase "hosted figures" actually engages the role parameter only obliquely. Baseline 3 is correct when the schema carries the load.

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 (displacement figures) with an explicit recency qualifier and states the two scoping modes (per-country vs global). It is clear what the tool returns, but it never differentiates itself from near-neighbours like refugee_population, top_host_countries, or country_profile, so an agent must infer the boundary.

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?

"With a country... Without..." does route the caller between two shapes of the same call, which is genuine usage guidance. However, there is no when-to-use-this-vs-that guidance against the many overlapping siblings, and no mention of when the role parameter (asylum vs origin) matters.

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 declare readOnlyHint and openWorldHint. The description adds genuinely non-obvious behavior: the server keeps a snapshot cache and/or returns it to the caller, so state persists between calls, and that it never contacts anyone. That is real value beyond the annotations, though it says nothing about failure modes or event ordering.

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 scope before the return-value and read-only details. Density is high but each clause (comparison modes, return shape, read-only guarantee) carries weight.

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, nested objects and an output schema, the description supplies the mental model the schema cannot: two comparison modes, alert-ready events with stable ids, and snapshot persistence. An agent could call it correctly from this plus the schema; only edge behavior (empty results, stale snapshots) is 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 every parameter, enum and default is already documented inline. The description only gestures at snapshot comparison and thresholds generically; the baseline of 3 applies when the schema carries the parameter 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 states a concrete verb and resource: it checks a country's UNHCR displacement figures for changes, comparing year-over-year movement and earlier snapshots. That is more specific than the title 'Monitor changes'. It stops short of naming any sibling (e.g. trend_analysis or latest_statistics) so an agent still has to infer the boundary.

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?

"Changes worth attention" plus the snapshot-vs-previous-call workflow gives clear context for when to reach for this tool. The snapshot precedence rule is reinforced ('against an earlier snapshot'), but no alternative tool is named and no explicit when-not-to-use condition is stated.

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 description's job is lighter; it adds that the check spans ALL providers rather than one, and that results cover latency and reachability. It does not mention cost, latency of the call itself, or partial-failure semantics, but output is covered by an output 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?

Two short sentences, zero filler, with the scope stated first and the usage condition second. Nothing here could be cut without losing 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?

For a read-only, no-required-param diagnostic tool with an output schema, the description covers what is checked and when to call it. Only marginal gaps remain around how degraded providers are reported, which the output schema likely handles.

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 single parameter (locale) is 100% documented in the schema, including the Arabic/enum behavior and that structured fields stay English. The description adds nothing about it, which is acceptable given full schema coverage but earns only the baseline.

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

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

States a specific verb and resource ('liveness check of every connected data provider') plus the dimensions checked (latency, reachability). No sibling tool in the list does anything comparable, so an agent can route to it unambiguously.

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 an explicit trigger: use when queries fail and the cause is ambiguous between an upstream outage and bad parameters. It stops short of naming when-not-to-use or an alternative diagnostic path, but the positive condition is clear enough to act on.

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/access profile is covered. The description's only behavioral addition is the trailing 'Paginated.', which largely restates the page/limit parameters already documented in the schema; it says nothing about data recency, source, or coverage limits of the underlying displacement series.

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?

Four tight sentences, front-loaded with what the data is, then the role switch, then the cross-filter, then pagination — no filler. The role sentence duplicates the enum description in the schema, which is the only redundancy.

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

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

With an output schema present and complete parameter documentation, the description only needs to establish scope and query combinations, which it does. Minor gap: no mention of the underlying dataset/recency or what happens when a country-year has no displacement figures.

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 every parameter carries an enum or example, so the schema does the heavy lifting. The description reinforces role and other_country with an illustrative pairing, but adds no format or edge-case detail (e.g. ISO3 vs name normalization, behavior when other_country's role is ambiguous) beyond what the schema states.

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 and measurement type — yearly displacement stock figures (refugees, asylum-seekers, IDPs, stateless, others) for one country — which is enough to tell it apart from count/applications tools. It never explicitly contrasts itself with siblings such as asylum_applications, asylum_decisions, or country_profile, so it stops short of full differentiation.

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 spells out the two operating modes (role='asylum' hosted vs role='origin' displaced) and the optional cross-filter pattern with a concrete example ('Syrians hosted in Egypt'), which is real usage guidance. It gives no exclusions — nothing says when to prefer asylum_applications or country_profile instead.

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 that matching is free-text/fuzzy resolution against aliases, but says nothing about behavior on zero matches or how many candidates come back, which matters most for a resolver step that gates downstream calls.

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, both earning their place: the first defines input-to-output, the second places the tool in the workflow. No restatement of the title or name.

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 all three parameters documented, the description covers what an agent needs to call it. The remaining gap is the no-result case, which is the primary failure mode for a normalization step feeding ~20 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 coverage is 100%, so baseline is 3. The parenthetical examples ('egypt', 'DRC', 'syria') genuinely illustrate the accepted input space – lowercase spelling variants and acronyms – going beyond the schema's generic 'name fragment, ISO2/ISO3 code or alias' wording.

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 ('Resolve a free-text country query to canonical names and ISO3 codes') and gives concrete input examples. It is clearly distinguishable from data-retrieval siblings like country_profile or compare_countries, which consume country identifiers rather than produce 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?

"Use this first when unsure how a country is spelled in the data" gives an explicit trigger and a workflow position (before the data tools). No alternative is named or exclusion stated for the case where the agent already knows the ISO3 code, but the implied ordering is clear.

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 and open-world nature are covered. The description adds real value with the ReliefWeb provenance and by clarifying the response mixes unfiltered aggregates with a short list of recent items, but it says nothing about result size, recency lag of the source, or rate limits.

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

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

Two sentences, zero filler, with the resource and payload front-loaded before the usage note. Every clause earns its place and nothing is repeated from 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?

With an output schema, full parameter documentation and read-only annotations, the agent has everything needed to call it. The remaining gap is scope framing — how far back yearly counts extend and how current the listed reports are — which the description leaves to the defaults 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%, including enums, defaults and bounds, so the baseline is 3. The description only implies the country parameter through 'about a country' and adds no semantics for query, locale, or the year range that the schema does not already spell out.

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 concrete verb and resource — situation reports published about a country — plus what they contain (yearly counts, recent titles and links) and the data source (ReliefWeb). It implicitly separates itself from profile/trend tools by positioning itself as the source-of-record layer, though it never names a sibling 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?

Gives a clear positive use case: grounding trends and anomalies surfaced by other tools in what was actually reported at the time. It never states when not to use it or names a specific alternative (e.g. country_profile vs. trend_analysis), so the routing signal stops short of 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 and openWorldHint, so the safety profile is covered. The description adds interpretive context (normalized rankings surface small hosts like Lebanon and Chad) but says nothing about data availability, provider failure behavior, or rate/response characteristics for the open-world data source.

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 followed by mode selection and normalization. The closing clause about Lebanon and Chad is motivational rather than strictly necessary but is short and aids interpretation.

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

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

An output schema exists, so return values need no explanation, annotations cover safety, and all six parameters are schema-documented. The only real gap is the un-enumerated metric parameter, where the agent still cannot tell which metric strings are accepted.

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 coverage the baseline is 3, but the description adds value the schema omits: it declares the default for by ("asylum") and explains what the normalized numbers mean in practice. The free-form metric parameter's valid values remain unexplained in both places.

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 ("Rank countries by a displacement metric for a year") and immediately defines the two ranking modes, host vs origin. It is distinguishable from siblings like country_profile or compare_countries by being an explicit ranking operation, though no sibling is named.

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 selection logic between the two modes ("by='asylum' (default) ranks host countries; by='origin' ranks countries people fled from") and when to add normalize_by. It lacks exclusions or pointers to alternative sibling tools for related questions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds real substance: the statistical method (exact penalised segmentation), the anomaly basis (z-scores of yearly changes), and the default window. It does not disclose data source, coverage limits, or failure behavior for sparse series, keeping it below 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?

A single dense sentence that front-loads the output inventory and saves the tuning advice for last; nearly every clause earns its place. It is packed tightly enough that it reads as a list rather than prose, which is a minor cost but not wasteful.

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 the safety profile, the description only needs to explain scope, defaults, and method — all of which it does. The remaining gap is routing: it doesn't state how this differs from 'forecast' or 'monitor_changes' for an agent choosing among similar analytical 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the default metric is refugees, the default window is the last 10 years, and year_from has a documented effect (wider range improves changepoint power). That is genuine parameter-level guidance beyond the field 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 ('Analyse how a displacement metric evolved') plus the resource (a country's yearly series) and enumerates the exact computations produced: YoY changes, slope/R², CAGR, z-score anomalies, changepoints. This is clearly distinguishable from siblings like forecast (prediction) or compare_countries (cross-country).

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 concrete default scope ('refugees hosted, last 10 years') and actionable guidance ('widen year_from for better changepoint power'), which tells an agent how to tune the call. It stops short of explicitly naming when to prefer 'forecast' or 'country_profile' instead, so no exclusion guidance.

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