unhcr-refugees-mcp-server

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

Annotations already cover read-only, idempotent, closed-world behavior, but the description adds real context: listing may be turned off for unauthenticated HTTP deployments, and entries carry creation/expiry time and a fetch-completeness flag. That is meaningful beyond the annotations, though permissions/error behavior is not discussed.

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 what is described and what is returned in two dense sentences with no filler. Slightly long, but every clause (source, listing constraint, entry fields, query follow-up) earns its place.

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

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

With an output schema present, return values need not be explained, and the description still covers the listing caveat, entry contents, and the follow-up workflow. Nothing needed to invoke it 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% and the single param already documents the pattern, the register_as/dataset.name source, and the omit-to-list semantics. The description mostly restates this, so the baseline 3 applies.

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

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

Names a specific verb (describe) and resource (dataframe staged by unhcr_get_* tools), and distinguishes the list-all mode. It also names the sibling unhcr_dataframe_query, so an agent can tell it apart from the query tool without opening schemas.

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

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

Explicitly instructs 'Read the columns here before writing SQL for unhcr_dataframe_query', giving a clear when-to-use and the alternative. It also states the deployment condition under which listing is unavailable and name becomes required.

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/idempotent/openWorld, but the description goes well beyond them by enumerating exactly what is rejected (writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file functions, system catalogs) and by disclosing the eviction/TTL/staging-budget side effects of register_as. That is the kind of behavioral context an agent cannot infer from readOnlyHint=true.

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

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

Front-loaded with the core action, then constraints, then the optional register_as behavior and the rate-column caveat. Every sentence carries information, though the denial list and budget details make it denser than strictly needed for scanning.

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-shape explanation is unnecessary; the description covers the remaining gaps an agent needs — read-only enforcement, staging budget, eviction, TTL, and the recommended sequencing with unhcr_dataframe_describe.

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 sql/preview/row_limit semantics are already fully spelled out in the schema. The description restates register_as's TTL behavior but adds no format, unit, or edge-case detail beyond what the schema provides.

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

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

States a precise verb and resource ('Run a single-statement SELECT against the dataframes staged by the unhcr_get_* tools'), and distinguishes itself from the sibling fetchers and from unhcr_dataframe_describe by naming both roles. An agent can tell this is the query layer over staged data without opening a 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 prerequisites and routing: check a dataframe's columns with unhcr_dataframe_describe first, and use register_as to chain analyses. It also names the correct analytical practice for rate columns ('recompute rates from summed counts rather than averaging rate columns'), which is a when-to-do-what instruction, not just a description.

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, idempotent, open-world, but the description goes further by explaining that counts of cases are never added to counts of persons, that each row states its unit, and that stage splitting by default prevents aggregation errors. It also mentions decoding with unhcr_list_reference. No contradictions with annotations.

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

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

Two sentences, front-loaded with purpose and key behavioral caveats. No redundant wording, though slightly dense. Each sentence carries substantive information.

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

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

Given 10 parameters (0 required), rich schema descriptions, and an output schema, the description is mostly complete. It covers the core operation, default behavior, unit distinction, and decoding. It could mention the split_by default more explicitly, but the schema covers that. No missing critical info for invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds a high-level rationale for default stage splitting and references the decode tool, but does not provide additional syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('lodged per year ... by country of origin and/or asylum') with explicit temporal scope (2000 to latest year). It also distinguishes itself from unhcr_get_asylum_decisions by being about applications, not decisions.

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

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

The description implies usage (to get application counts by origin/asylum, to decode codes use unhcr_list_reference) and names a sibling for decoding, but it does not explicitly state when to use this tool over unhcr_get_asylum_decisions or other unhcr_get_* siblings. The 'so new claims are not added to appeals of old ones' hint is useful but not a direct usage guideline.

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 read-only/idempotent/openWorld, so the bar is lower, yet the description adds real behavioral context: rates are computed over substantive decisions with otherwise-closed cases excluded, defaults sum all decision levels, and 'cases and persons are never added together.' It does not touch staging/pagination behavior, which the schema handles.

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 what is retrieved before the caveats, and every clause carries information (rate definitions, appeal-stage caveat, cases-vs-persons rule). It is dense and reads as one long paragraph, but nothing is redundant with structured fields.

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 analytical query tool with an output schema and full schema coverage, the description supplies the conceptual layer an agent needs: metric definition, exclusion rule, default aggregation, and the decision-level caveat. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description lifts key parameters out of the schema by explaining the consequence of defaults ('all decision levels are summed and each row lists the levels it includes') and linking split_by/decision_levels to first-instance rates. That is meaning beyond raw field documentation.

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

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

States a specific verb and resource (asylum decisions per year by origin and/or asylum country) and enumerates the outcome categories returned, so an agent can distinguish it from unhcr_get_asylum_applications without opening the schema. The scope of what is retrieved is unambiguous.

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 guidance: default summing of decision levels, and the instruction to 'split_by decision_level or filter decision_levels to FI for first-instance rates' when appeal-stage cases would contaminate the result. It stops short of naming sibling tools (e.g., unhcr_get_asylum_applications) as alternatives or stating when not to use this tool.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld), and the description adds genuinely non-schema behavior: partial coverage, per-row disaggregation share, null age bands, and divergence from unhcr_get_population. It stops short of describing output shape or staging behavior in narrative form, but the caveats delivered are substantive.

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, all front-loaded with the operation and its scope before the coverage caveats. Dense but every clause carries information; only marginal tightening is possible.

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

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

An output schema exists, so return values need not be explained, and the description supplies the coverage caveat and sibling distinction an agent needs to interpret results correctly. It could still note the timeframe/limit interaction, but it is essentially complete for this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including code formats, clamping, and expand rules. The description adds essentially no parameter meaning beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific verb and resource (year-end stocks by population type, sex, age band) plus the dimensions of disaggregation and the source collection, and it explicitly contrasts itself with unhcr_get_population. An agent can distinguish it from siblings without opening schemas.

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 routes the agent to unhcr_get_population for consistent totals and notes that these numbers need not match, implying when to prefer each. However, it never states a positive when-to-use condition (e.g. 'use this when you need sex/age breakdowns'), so the guidance is contextual rather than explicit.

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

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

Annotations already establish read-only, idempotent, open-world behavior, so the description is free to add substantive context: stock-vs-arrival semantics, the December 31 snapshot, treating UNRWA and IDMC figures as separate side-by-side series, and nowcast's lack of an origin dimension. It stops short of describing pagination/staging behavior or output shape, but the annotations and output schema cover much of that.

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

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

Purpose and scope are front-loaded in the first sentence, with caveats (stock definition, side-by-side series, nowcast, demographics hand-off) following in a logical order. It is dense and somewhat long, but each sentence carries distinct information rather than 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 need no explanation. The description covers dimensions (origin/asylum), the stock concept, the special-cased series, the nowcast edge case, and the sibling to use for demographic breakdowns — enough for an agent to call it correctly without opening 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 schema already documents all nine parameters including enums, formats and clamping rules. The description largely restates the include_nowcast flag rather than adding syntax or format detail the schema lacks; baseline 3 applies when the schema does the heavy lifting.

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 (year-end displacement stocks by country of origin/asylum) plus the exact series included, which lets an agent separate it from siblings like unhcr_get_solutions and unhcr_get_demographics. It also disambiguates stocks from flows ('count people in a situation on 31 December, not arrivals').

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 conditional guidance: set include_nowcast for the current-year estimate and use unhcr_get_demographics for sex/age breakdowns. It does not, however, state when to prefer this tool over unhcr_get_solutions or the asylum-applications/decisions tools, so routing across the remaining siblings is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so credit goes to the extra interpretive context the description supplies: that 'asylum' denotes a different country per measure (returned-from, resettled-to, naturalising country) while IDP returns sit on the origin country, and that null means 'not collected', not zero. These are non-obvious data behaviours that prevent real misinterpretation.

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 leads, and all three sentences carry information that is not restated structurally — nothing is padding. The middle sentence about asylum meaning per column is dense and would read better as a short list, but the ordering is logical and front-loaded.

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

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

With an output schema present, a fully documented 8-parameter schema and annotations covering read-only/idempotent behaviour, the description only needed to supply purpose, dimension semantics and null handling — all of which it does. An agent has everything required to call and interpret this tool 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 the baseline is 3; the description adds meaning beyond the schema by explaining the conceptual asymmetry of the origin/asylum dimensions and how they relate to the returned measures, which the schema's per-parameter text does not convey. It adds no detail on limit/stage/sort_by beyond what the schema already documents.

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') and immediately enumerates the four measures it returns (returned refugees, resettlement, naturalisation, IDP returns), which cleanly separates it from siblings like unhcr_get_population, unhcr_get_demographics and unhcr_get_asylum_applications. The year coverage (1959 to latest) and the origin/asylum slicing dimensions are 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?

Usage is only implied through content — the agent can infer this is the tool for durable-solutions figures, but there is no explicit when-to-use/when-not statement and no sibling is named as an alternative for population, demographics or asylum-applications data. The only routing hint (resolve names via unhcr_list_reference) lives in the schema, not the description.

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.