unhcr-refugees-mcp-server

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: staged results expire, listing can be disabled in unauthenticated HTTP deployments, and completeness of the upstream fetch is surfaced. It does not mention pagination or size limits, keeping it short of 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?

Purpose is front-loaded and the two sentences are dense with useful content. The opening sentence is somewhat convoluted with its em-dash aside ('— any response carrying a dataset handle staged its full result here —'), but nothing is padding.

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 explained, yet the description enumerates the entry fields (source tool, query params, creation/expiry, row count, completeness, column schema), which is slightly redundant but helps the agent know what it can rely on. The full describe→query workflow is covered.

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

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

Schema coverage is 100% and the single 'name' parameter is fully documented in the schema, including the pattern and the listing fallback. The description restates the staging origin (dataset.name / register_as name) and the listing-off case rather than adding new 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?

States a specific verb+resource ('Describe a dataframe (df_XXXXX_XXXXX) staged by the unhcr_get_* tools') and explicitly names the sibling it feeds into (unhcr_dataframe_query). An agent can distinguish it from the query tool and from the unhcr_get_* producers 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?

Gives explicit routing: 'Read the columns here before writing SQL for unhcr_dataframe_query.' It also states the when-not condition — omit name to list, but name is required in deployments serving unauthenticated HTTP callers. Both the action and the exclusion are spelled out.

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/idempotentHint/openWorldHint, but the description adds substantial non-obvious behavior: the full list of rejected statements (writes, DDL, COPY, PRAGMA, ATTACH, external functions, catalogs), the single-string-literal gate, and register_as semantics including fresh TTL, 1M-row staging budget, eviction of the oldest dataframes, and non-save on overflow.

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 core action, then the prerequisite, then constraints, then the optional save behavior. The enumeration of rejected constructs is long but each item carries real invocation-relevant information; only the trailing rate-recomputation sentence feels like an aside rather than core 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?

With an output schema present, return values need no explanation, and the description still covers constraints, prerequisites, staging-budget side effects, and the chaining path via register_as. An agent has everything needed to call this correctly and safely.

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 parameter descriptions are already rich (clamping behavior, row_limit caps, register_as naming pattern). The description's mention that register_as 'saves the result as a new dataframe with a fresh TTL' largely restates the schema, so it adds only marginal meaning; the rate-averaging note is analytical advice rather than parameter semantics.

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

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

The description states a specific verb and resource ('Run a single-statement SELECT against the dataframes staged by the unhcr_get_* tools') and scopes it to staged dataframes, which cleanly separates it from the unhcr_get_* staging tools and unhcr_dataframe_describe.

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 prescribes the workflow order explicitly ('Check a dataframe's columns with unhcr_dataframe_describe first') and names register_as as the path for chaining analyses. The rejection list tells the agent precisely which SQL constructs will fail, which is actionable 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?

Annotations already establish readOnly, idempotent, open-world, so safety is covered. The description adds real behavioral value beyond that: it warns that case counts are never added to person counts and that each row declares its unit, and that the stage split prevents new claims being merged into old appeals. It omits discussion of rate limits or response size behavior, which the schema covers.

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 purpose and scope, then the unit-mixing caveat, then the helper-tool pointer. Dense but every sentence carries a distinct payload; the first sentence is long but earns its length by packing scope, dimension, and default behavior.

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 10-parameter, all-optional aggregation tool with a full output schema and supporting annotations, the description supplies the key interpretive context (unit mixing, default stage split, code decoding). Nothing critical is missing, though it does not touch on the clamping/disclosure mechanics that an agent would only learn from 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 documents all ten parameters in detail (clamping, expand rejection rules, ISO3 rewriting, enum codes). The description reinforces the default stage split and code-decoding path but adds little syntax or format meaning beyond what the schema states; 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 and resource ('Get asylum applications lodged per year'), gives the temporal scope (2000 to latest), and names the two filterable dimensions (origin and/or asylum). An agent can distinguish this from the sibling unhcr_get_asylum_decisions purely from the 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?

Explains the default splitting behavior and routes to unhcr_list_reference (topic asylum_codes) for decoding stage/authority/decision-level codes, which is actionable context. It does not, however, explicitly say when to prefer this tool over unhcr_get_asylum_decisions or unhcr_get_demographics, so the guidance is clear but not exclusionary.

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 (readOnly, idempotent, openWorld). The description adds substantive behavioral context beyond them: rates are computed over substantive decisions with otherwise-closed cases excluded, all decision levels are summed by default with each row listing its levels, and cases vs persons are never combined. This materially helps correct interpretation.

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 resource and scope, then defaults and the important caveat. Dense but every sentence earns its place; the multi-clause sentences are slightly heavy 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, return values need no explanation. The description supplies the defaults, the rate-computation caveat, and the splitting nuance an agent needs to call this correctly, though pagination/limit behavior is left entirely 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the default summing of decision levels, the risk that appeal-stage rows double-count, and the interplay of split_by/decision_levels for first-instance rates. It does not walk through each parameter, but it enriches the most consequential ones.

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 ('Get asylum decisions per year ... by country of origin and/or asylum') and enumerates the decision categories returned, plus the derived rates. An agent can tell this apart from siblings like unhcr_get_asylum_applications without opening either 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 concrete conditional guidance: use split_by decision_level or filter decision_levels to FI to get first-instance rates, and notes that appeal-stage decisions overlap with first-instance populations. Does not explicitly name sibling tools or exclusions, but the when-to-use context 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?

Beyond the readOnly/idempotent annotations, the description discloses substantive behavioral traits: coverage is partial, each row carries the share of its total that UNHCR could disaggregate by sex, age bands are null where no breakdown exists, and the figures may diverge from a sibling data source. These caveats materially affect interpretation of 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?

Three tightly packed sentences, front-loaded with what the tool returns, then coverage caveats, then the cross-tool reconciliation warning. No sentence is filler and each adds decision-relevant 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?

An output schema exists, so return-value explanation is not the description's burden. For a 9-parameter, all-optional read tool, the description supplies the critical interpretation context (partial disaggregation, null age bands, provenance mismatch) that an agent needs to use 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 coverage is 100%, so the schema already documents every parameter including code formats, expand semantics, clamping, and sorting. The description adds the year-window origin (2001) and the age-band cohorts, but no syntax or behavior beyond the schema, so the baseline 3 is appropriate.

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

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

States a concrete verb and resource (year-end stocks) plus the exact disaggregation dimensions (population type, sex, age band) and the geographic axes (origin and/or asylum), with the time span (2001 to latest). It explicitly names the sibling unhcr_get_population as a distinct data source, so an agent can separate the two without opening either 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 context for what the tool is for and warns that its totals come from a separate collection and may not reconcile with unhcr_get_population, which helps an agent choose between them. It stops short of an explicit 'use X instead when you want whole-population totals' rule, so the alternative selection is implied rather than 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 read-only/idempotent, and the description adds genuinely non-obvious semantics: stocks count people in a situation on 31 December rather than arrivals, UNRWA and IDMC series appear as separate columns beside each row, and nowcast is a current-year snapshot independent of the year window. These are behaviors an agent could not infer from 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?

Front-loads the resource and its scope before moving to caveats and sibling routing. It is a dense paragraph rather than a list, but nearly every clause carries distinct semantic information (stocks-vs-flows, separate series, nowcast, demographics alternative).

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 full annotation coverage, the description supplies exactly the missing pieces: what the counts mean, which series are bundled in, and which sibling to use for demographic breakdowns. Return values are covered by the output schema, so nothing essential is 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 coverage is 100%, so baseline is 3; the description still adds meaning by explaining what include_nowcast produces ('UNHCR's current-year estimate by asylum country') and that an unfiltered dimension is summed unless expanded. It does not elaborate on limit/stage/sort_by beyond the schema text.

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?

Opens with a specific verb+resource ('Get UNHCR year-end displacement stocks') and enumerates exactly which series are covered (refugees, asylum-seekers, OIP, IDPs, stateless, OOC, host communities, returns). It also distinguishes itself from siblings by naming unhcr_get_demographics as the tool for sex/age breakdowns.

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 routing rule: 'for sex and age breakdowns, use unhcr_get_demographics', plus a conditional usage hint for include_nowcast. It does not address overlap with other count-oriented siblings like unhcr_get_solutions or unhcr_get_asylum_applications, so it falls short of full when/when-not coverage.

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 readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the coverage window (1959 to latest), the per-column meaning of the asylum dimension, and the critical null-vs-zero semantics. It does not mention pagination/clamping or rate limits, but the important semantic traps are disclosed.

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

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

Three sentences, no filler; the scope and the four measures are front-loaded, followed by the two highest-risk clarifications (asylum column semantics, null vs zero). Every sentence carries information an agent would otherwise have to guess.

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, 100% parameter coverage, and read-only annotations, the description only needs to resolve domain traps — and it does: the per-column asylum semantics and null-not-zero convention are the two most likely sources of misinterpretation. Nothing essential for 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 baseline is 3, but the description adds real meaning by explaining that 'asylum country' denotes a different country per measure (returned-from, resettlement destination, naturalising country, IDP return on origin) — a semantic distinction the schema only partially implies. It does not elaborate on expand/sort_by/stage behavior, which stays 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?

States a specific verb and resource ('Get durable solutions per year ... by country of origin and/or asylum') and enumerates the four measure columns (returned refugees, resettlement, naturalisation, returned IDPs), which implicitly but clearly separates it from siblings like unhcr_get_population, unhcr_get_asylum_applications, and unhcr_get_demographics. An agent can tell what data this 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?

The description never states when to choose this tool over alternatives or what conditions make it the right call. Routing hints (resolve names via unhcr_list_reference, join via unhcr_dataframe_query) exist only in the parameter schema, not the description, so the description itself offers no usage 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds content-scope context (what vocabulary is decoded) but no behavioral detail such as caching, latency, or result completeness beyond the structured fields.

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 purpose and followed by the practical name_contains use case. Dense but every clause maps to a covered topic or usage instruction; 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?

An output schema exists so return-value detail is unnecessary, and the description covers the topic space and the code-conversion use case. Adequate for a reference-lookup tool, though it could note whether results are static or refreshed.

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 nested enum descriptions already document each topic exhaustively. The description echoes the topic list and mentions name_contains' role, adding only a light usage hint over what the schema provides, so 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 ('Decode') and resource ('the vocabulary the unhcr_* tools take as input'), then enumerates exactly what it returns: countries/codes, regional bureaus, dataset year coverage, population types, and asylum codes. This clearly distinguishes it from the data-returning siblings like unhcr_get_population or unhcr_get_asylum_applications.

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

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

Gives a concrete usage path: 'Filter countries with name_contains to turn a country name into the ISO3 code that origin and asylum take,' which tells the agent why it would call this before other tools. It stops short of explicitly stating when NOT to use it or naming a sibling as an alternative.

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