This server gives AI assistants direct access to WHO Global Health Observatory (GHO) data via MCP tools for discovery, metadata, data retrieval, comparison, and export.
Discover indicators, topics, dimensions, country codes, income groups, and curated country groupings.
Fetch indicator metadata and inspect available disaggregations (sex, age, residence, etc.).
Query indicator data with filters for country/region/income group, year range, sex, and custom dimension filters.
Compare multiple countries or groups over time, returning tidy rows or CSV, with automatic chunking for large country sets.
Generate country health-system profiles with headline indicators and explicit population/selection status.
Run expert OData queries for advanced disaggregations not covered by friendly tools.
Use curated resources and prompts for comparative health-systems analysis.
Provides tools for accessing and analyzing global health data from the World Health Organization's Global Health Observatory, including indicator discovery, country profiles, cross-country comparisons, and metadata for citation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gho-mcp compare life expectancy in Brazil and Argentina"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that gives AI assistants like Claude direct access to the World Health Organization's Global Health Observatory (GHO), built for comparative health systems research.
gho-mcp wraps the WHO GHO OData API (https://ghoapi.azureedge.net/api) in a small set of task-shaped MCP tools so an AI assistant can answer questions like:
"Build me a comparative health systems profile for Peru."
"Plot maternal mortality across the Andean countries since 2010."
"What's the UHC service coverage gradient by World Bank income group?"
"Does the tobacco indicator support sex disaggregation?"
Country names, ISO3 codes, WHO region codes (AFR, AMR, etc.), and World Bank income-group codes (WB_HI, WB_UMI, etc.) are all accepted interchangeably. CSV export is built in.
Related MCP server: OECD-Search
Raw API access for global health data is technically possible from an AI assistant with tool access, but in practice it's painful: indicator codes are cryptic (WHOSIS_000001 is "life expectancy at birth"), countries must be ISO3 codes, OData filter syntax is unforgiving, and every cross-country comparison becomes a loop. gho-mcp collapses the friction so an LLM can stay focused on the analysis.
The tool design reflects how comparative-health-systems researchers actually work: country profiles, regional and income-group benchmarks, sex-disaggregated time series, and metadata for citation.
Requires Python 3.11 or newer and an MCP client that can launch local
stdio servers. Check python3 --version (Windows: py -3 --version) and use
a supported interpreter before creating the environment. No WHO API key is required.
The shell examples below use macOS/Linux.
Install 0.7.0 from PyPI in a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install mcp-server-gho==0.7.0On Windows PowerShell, use:
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install mcp-server-gho==0.7.0The same wheel and source archive are also available in the GitHub release.
For an editable source installation:
git clone https://github.com/Decilion/gho-mcp.git
cd gho-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .Use the absolute path to the executable in the environment where you installed
this package: .venv/bin/gho-mcp on macOS/Linux, or
.venv\Scripts\gho-mcp.exe on Windows. In JSON, escape Windows backslashes,
for example C:\\Users\\you\\project\\.venv\\Scripts\\gho-mcp.exe.
Merge the entry into any existing mcpServers object instead of replacing it.
Claude Code:
claude mcp add --transport stdio --scope user gho -- /absolute/path/to/.venv/bin/gho-mcp--scope user makes the server available across Claude Code projects.
Use --scope local if you want it only in the current project.
Claude Desktop: add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"gho": {
"command": "/absolute/path/to/.venv/bin/gho-mcp"
}
}
}Codex CLI:
codex mcp add gho -- /absolute/path/to/.venv/bin/gho-mcpThis writes an entry to ~/.codex/config.toml. List or remove with codex mcp list / codex mcp remove gho.
Other MCP-compatible clients (Cursor, Cline, Continue, etc.): point them at the gho-mcp console script in your venv. The MCP protocol is the same across clients; only the registration UI differs.
Restart your client. The gho server should appear with all tools, the gho://topics/{topic_id} resource, and the compare_health_systems prompt available.
python -m pip show mcp-server-ghoOn Windows, use .\.venv\Scripts\python.exe -m pip show mcp-server-gho.
After registering and restarting your client, ask it to call gho's
topics_index tool. This checks the connection without fetching WHO data.
The server exposes 15 tools. Running gho-mcp alone in a terminal
starts a stdio process that waits for an MCP client; it is not a web server.
If the server is missing, verify the absolute executable path, install into that same environment, and restart the client. If WHO is temporarily unavailable, retain the error and retry later; an upstream failure does not mean no data exists.
Version 0.7.0 includes the September 2026 correctness and reliability fixes
listed in the changelog. Upgrade from
PyPI with python -m pip install --upgrade mcp-server-gho,
or update an editable source checkout as follows.
The unpinned upgrade command selects the newest compatible PyPI release.
Use mcp-server-gho==0.7.0 to reproduce the version documented here.
From your existing clone, with its virtual environment active:
git pull --ff-only
python -m pip install -e .Restart the MCP client so its server process loads the updated code and tool
schemas. Installation resolves declared dependencies: both servers require
mcp>=1.15.0,<2 and httpx>=0.27.0; GHED additionally requires
openpyxl>=3.1.0 and filelock>=3.16,<4.
Comparisons and CSV exports retain the existing columns and append
spatial_dim_type, time_dim_type, dim1_type, dim1, dim2_type, dim2,
dim3_type, and dim3. Latest-year selection now preserves each complete
population combination; outputs can contain more rows than in 0.6.1. Include
those dimensions when grouping or pivoting, or choose a population with
dim_filters. sex is null when Dim1 represents a different dimension.
Profiles add indicator_dim_filters and per-indicator selection_status.
Ambiguous or incomplete latest-year populations return null headline values
with an explanation. Consumers should inspect this status before using a value.
Comparisons report unsupported group codes and missing requested countries.
For multi-chunk queries, source.params is empty and source.requests contains
the exact requests and continuation metadata. Unsupported identifiers and aliases
raise errors; failed dimension lookups preserve their upstream errors.
Tables show defaults; capped limits are clamped to at least 1 and at most the listed maximum. Raising a limit beyond that maximum does not fetch more data.
Tool signatures below show the canonical parameter names, omitting deprecated
aliases. Unknown arguments are rejected, so getting the names right matters. In particular: country is singular, countries is the list form, year filters are year_start / year_end (not year_from / year_to).
find_country_code also accepts the deprecated country_name alias. Pass
either country or country_name, not both.
get_indicator_data similarly accepts deprecated region_code in place of
country. Use country for countries, WHO regions and income-group codes.
Tool | Signature | Purpose |
|
| Paginated list of all GHO indicators; |
|
| Case-insensitive substring search on indicator names; |
|
| Curated map of comparative-health-systems topics → indicator codes |
|
| All GHO dimensions (COUNTRY, REGION, SEX, AGEGROUP, etc.) |
|
| Allowed values for a dimension |
|
| Resolve country name → ISO3 code |
|
| World Bank income-group spatial codes |
|
| Decilion's curated groupings (LAC, LAC_TERRITORIES, OECD, LDC, SSA, MENA, etc.); see Regional analysis below |
|
| Return the ISO3 list for one curated group |
Tool | Signature | Purpose |
|
| Full metadata record for citation |
|
| What disaggregations (sex, age, residence) an indicator uses; |
Tool | Signature | Purpose |
|
| Single indicator with optional spatial/temporal/sex/dim filters; |
|
| One indicator × N spatial units × year range, tidy rows or CSV; |
|
| Parallel-fetched headline indicators for one country |
|
| Expert escape-hatch; pass-through OData query for advanced disaggregations (wealth quintile, residence, education, custom Dim2 values); |
Resource gho://topics/{topic_id}: readable view of a curated topic and its indicator codes
Prompt compare_health_systems(countries, topic): guided template for cross-country comparative analysis
latest_only=True retains the latest year for each country and full dimension
combination. Age bands, residence areas and other subgroups remain separate;
sex is filled only when Dim1 represents sex. Discover dimensions first and
use dim_filters to compare a specific population. Indicators without a sex
dimension, such as physician density, must be queried without sex="both".
Dimension discovery samples data and reports its own truncation flags.
For an explicit custom profile population, pass per-indicator filters:
country_profile("Colombia", indicator_codes=["SDGPM25"],
indicator_dim_filters={"SDGPM25": {"Dim1": "RESIDENCEAREATYPE_TOTL"}})country_profile(year=...) selects the latest observation at or before that
year, not necessarily in that year. Inspect each returned reference year.
Profiles select within the latest available year after applying filters. They
prefer known WHO aggregate codes, otherwise report a unique labeled population.
If several populations remain, no headline value is chosen. The profile query
fetches up to 50 rows per indicator. When a capped page does not include an older
year, the latest-year population set may be incomplete and no value is selected.
Each profile indicator includes the exact query, truncation flags and selection
status. Apply filters or use the data tools to investigate unresolved results.
Comparisons cap rows per chunk of up to 10 countries, not per country. An
alphabetically earlier country's observations can consume the entire allowance.
Check missing_requested_codes, truncated and possibly_truncated; split into
smaller country lists or narrow filters to establish coverage. A missing result
is not proof that WHO has no data. source.requests records each exact HTTP
query and its continuation link. For several chunks, filter is a readable
summary and source.params is empty, rather than containing an invented query.
Curated groups use exact ISO3 membership. unsupported_group_codes and a warning
report members absent from GHO dimensions. A group with no supported members
raises an error even when explicit countries are also supplied.
Both gho-mcp and ghed-mcp expose the same curated country groupings beyond what WHO and the World Bank publish as built-in dimensions. Pass country_group="LAC" (or any of the codes below) on the data tools and the server resolves to the right ISO3 list without you having to enumerate codes by hand.
These are the definitions bundled with this release, last verified in the source on 2026-05-06. The World Bank region lists use FY2026 definitions; they are not a live classification service. Member counts describe the curated lists, not the number of economies with observations in either WHO database.
Code | Definition | Members |
| 33 sovereign Latin American & Caribbean states (PAHO/Decilion convention) | 33 |
| World Bank's 42-economy LAC region: sovereign states plus territories (Aruba, Cayman Islands, Curaçao, Puerto Rico, etc.) | 42 |
| World Bank East Asia & Pacific (FY2026) | 38 |
| World Bank Europe & Central Asia | 58 |
| World Bank "Middle East, North Africa, Afghanistan and Pakistan" (FY2026) | 23 |
| MENA without Israel and Malta | 21 |
| World Bank North America (Bermuda, Canada, USA) | 3 |
| World Bank South Asia (FY2026; without AFG and PAK, now in MENA) | 6 |
| World Bank Sub-Saharan Africa | 48 |
| UN Least Developed Countries | 44 |
| OECD member countries | 38 |
Aliases include natural-language ("Latin America and Caribbean", "Sub-Saharan Africa", "Least Developed Countries") and official codes (LCN, SSF, etc.). Two read-only tools, list_curated_country_groups and resolve_country_group_membership, let an assistant inspect or expand the lists at runtime.
country_group= on the data toolscountry_group= merges (deduplicated) with any explicit countries= list. GHED additionally combines region / income filters using AND semantics. The following examples identify which server supports each call:
compare_countries(indicator_code="oops_che", country_group="LAC",
latest_only=True) # GHED
compare_countries(indicator_code="WHOSIS_000001", country_group="OECD",
year_start=2010, year_end=2023) # GHO
list_curated_country_groups() # both
resolve_country_group_membership("LAC") # both; returns 33 ISO3 codes
# ghed-mcp also exposes:
build_research_panel(indicator_codes=["che_gdp", "gghed_che"],
country_group="OECD", year_start=2000, year_end=2024)
summarize_country_group(indicator_code="ext_che", country_group="LDC",
latest_only=True)
list_countries(country_group="LAC", income="High") # LAC HICsCurated members are validated as exact ISO3 codes, without fuzzy name matching. GHO reports unsupported members through unsupported_group_codes and warnings. An entirely unsupported group raises an error. Each source has different geographic and indicator coverage, so inspect the resolved and missing-country lists before comparing regional results. User-supplied countries= are resolved separately; unsupported three-letter identifiers and aliases whose target is absent from GHO dimensions raise an error. Exact country names take precedence over partial name matching.
The lists are static Python data bundled with each package. Membership changes require a new package release and an upgrade; reinstalling the same version does not refresh them. WHO region/income values come from the respective data source and should not be assumed to represent historical classifications for every year.
The LAST_VERIFIED constant in country_groups.py records the bundled review
date. Consult the authoritative sources for subsequent changes:
World Bank country and lending groups: https://datahelpdesk.worldbank.org/knowledgebase/articles/906519
UN Least Developed Countries: https://policy.desa.un.org/least-developed-countries
OECD members: https://www.oecd.org/en/about/members-partners.html
Re-check before time-sensitive group comparisons and at least annually. See the UN graduation updates for scheduled changes; the package does not automatically remove graduating LDCs.
The same country_groups.py definitions live in both ghed-mcp and gho-mcp (canonical source: ghed-mcp). Their intended group membership matches, but supported countries and available observations can differ by source.
Each block below shows a natural-language prompt and a sketch of the underlying MCP tool calls. These calls illustrate arguments for your assistant; they are not standalone Python scripts. Actual values and coverage depend on the WHO source.
Country profile
"Give me a Colombia health systems profile."
The assistant calls country_profile(country="Colombia") and returns life expectancy, HALE, IMR, U5MR, MMR, UHC index, DTP3 coverage, skilled birth attendance, doctor and nurse density, premature NCD mortality, and TB incidence for each indicator's latest available year, with both-sex, all-age and total-residence populations preferred when explicitly coded. Each selected value includes its actual population dimensions. Ambiguous or incomplete latest-year populations return selection_status="ambiguous" or "incomplete" and a null value, so a subgroup is never silently treated as a national total.
Comparative LAC analysis
"Compare maternal mortality across the Andean countries since 2010."
The assistant calls:
compare_countries(
indicator_code="MDG_0000000026",
countries=["Colombia", "Ecuador", "Peru", "Bolivia", "Venezuela"],
year_start=2010,
latest_only=False,
format="csv",
)and gets a CSV ready to drop into any spreadsheet, statistical package, or charting tool.
Income-group gradient
"What's life expectancy by World Bank income group in 2021?"
The assistant calls compare_countries("WHOSIS_000001", countries=["WB_HI","WB_UMI","WB_LMI","WB_LI"], year_start=2021, year_end=2021, sex="both") and compares the returned estimates, units and reference years. Calculate any
gap from the retrieved values; no fixed difference is assumed.
compare_countries(..., format="csv") returns a CSV string under the csv key. Two common downstream paths:
To pandas, for time-series analysis or modelling (optional: install
pandas and matplotlib in your analysis environment):
import io, pandas as pd
# csv_text is the value of result["csv"] from compare_countries
df = pd.read_csv(io.StringIO(csv_text))
df["year"] = df["year"].astype(int)
# First select one indicator and population with the tool's sex/dim_filters.
# Stop if multiple populations or duplicate observations would be combined.
population = ["spatial_dim_type", "time_dim_type", "dim1_type", "dim1",
"dim2_type", "dim2", "dim3_type", "dim3"]
if len(df[population].drop_duplicates()) > 1:
raise ValueError("Select one comparable population before pivoting.")
if df.duplicated(["country_code", "year"]).any():
raise ValueError("Resolve duplicate country-year observations before pivoting.")
df = df.pivot(index="year", columns="country_code", values="value")
df.plot(title="Selected indicator and population by country")To any external tool (Excel, Google Sheets, R, Stata, Tableau, charting platforms, etc.):
with open("data.csv", "w", encoding="utf-8", newline="") as f:
f.write(csv_text)The columns country_code, country_name, year, sex, value, value_display, low, high, indicator_name, spatial_dim_type, time_dim_type, dim1_type, dim1, dim2_type, dim2, dim3_type, dim3 preserve population identity in both rows and CSV and are tidy-format-friendly and map cleanly into most analysis or visualization workflows. For wide-format / per-country columns, pivot first (pandas snippet above).
The friendly tools cover spatial, temporal and sex filters, plus equality filters on Dim1/Dim2/Dim3 and their types through dim_filters. Use get_indicator_data_raw for custom OData expressions or selected output fields:
get_indicator_data_raw(
indicator_code="MDG_0000000026",
filter="SpatialDim eq 'BRA' and TimeDim ge 2010",
select="SpatialDim,TimeDim,Dim1Type,Dim1,Dim2Type,Dim2,Dim3Type,Dim3,NumericValue",
top=20,
)Inspect what disaggregations an indicator supports with describe_indicator_dimensions(indicator_code) first; it samples observations and lists the Dim1/Dim2/Dim3 types and values seen in the sample.
topics_indexhealth_outcomes: life expectancy, HALE, IMR, U5MR, MMR, adult mortality
service_coverage: UHC index, DTP3, measles, ANC, skilled birth attendance
health_workforce: doctors, nurses & midwives, dentists, pharmacists per 10k
health_financing: health spending as % GDP, OOP share, per-capita CHE
ncd_burden: premature NCD mortality, hypertension, obesity, smoking
infectious_diseases: TB, HIV, malaria, hepatitis, water access
child_health: stunting, wasting, exclusive breastfeeding, immunization
risk_factors: tobacco, alcohol, obesity, physical inactivity
mental_health: suicide, mental health workforce
environment_climate: PM2.5, WASH (water/sanitation/hygiene)
medicines_access: essential medicines availability
quality_safety: antimicrobial resistance, hospital safety proxies
equity_sdg: SDG-aligned indicators for equity framing
The 2026-09-14 regression suite contains 77 tests. GitHub Actions runs it on Python 3.11, 3.12, 3.13 and 3.14 against the minimum and latest compatible MCP SDK, then builds both distributions and checks wheel imports outside the checkout.
python -m pip install -e ".[dev]"
python -m pytestTests mock the WHO API; no network access required for the standard suite. A weekly GitHub Actions workflow validates that the curated indicator codes still resolve against the live API and opens an issue if anything rots.
Release procedure: RELEASING.md.
The GHO OData feed is read-only and unauthenticated. Aggregate values (regional, income-group, global) are computed by WHO; this server does not recompute them.
Detailed health expenditure data lives in the separate GHED database; a few GHED indicators are mirrored in GHO but not the full set.
Some indicators are sparse for recent years. describe_indicator_dimensions
inspects a sample of populations, not complete country/year availability. Query
the required countries and years and inspect missing-country and truncation flags.
Availability depends on the WHO OData service. Changes to endpoints, indicator codes or response schemas may require a server update.
The WHO Global Health Observatory (GHO) is the World Health Organization's central platform for global health statistics. It is the authoritative source of internationally comparable indicators on:
Sustainable Development Goals health monitoring (SDG 3 and related targets)
Universal Health Coverage: service coverage index, financial protection, essential medicines availability
Major disease burden: HIV, tuberculosis, malaria, hepatitis, NCDs, mental health
Health system inputs: workforce density, immunization coverage, health expenditure
Risk factors: tobacco, alcohol, obesity, air pollution, WASH
Equity dimensions: disaggregations by sex, age, residence, wealth quintile, and education where source data permits
The GHO underpins WHO's annual World Health Statistics report, regional health reviews, and country-level briefings used by ministries of health, multilateral institutions, and global health researchers worldwide. The data is free and openly published through the OData API this server wraps, and through the official portal with its own visualizations, dashboards, and downloads.
This MCP server is plumbing. The data, the indicator definitions, the methodological work, and the country-level data validation are all WHO's. If you use values retrieved through this server, please:
Cite WHO as the source. The source block on every data response includes the exact endpoint, parameters, and retrieval timestamp to make this straightforward.
Visit the GHO portal for indicator metadata, methodology notes, and the official visualizations. The MCP exposes the data: the portal provides the canonical context.
Read the World Health Statistics annual report for WHO's curated narrative analysis of what the data shows.
The GHO is a public good. The most valuable contribution any user can make is to support and reference WHO's underlying data work.
Decilion provides global health consulting across Latin America and the Caribbean, including applied AI for global health.
This server is one of Decilion's open-source contributions to the global health data community. It pairs with ghed-mcp for detailed health-expenditure analysis. If you use it in research, a brief acknowledgment is appreciated but not required.
MIT. See LICENSE.
One indicator × N spatial units × year range, returned as tidy rows or CSV.
Workhorse for comparative analysis. Country names, ISO3 codes, region codes, and income-group codes all auto-resolve. Row labels resolve human titles for regions and income groups, not just countries.
For large country sets (e.g. country_group="LAC" with 33 sovereign
states), the request is automatically chunked into multiple parallel
HTTP calls of up to 10 spatial units each, then merged. This avoids the
HTTP 400 the GHO API returns when an $filter carries too many
SpatialDim eq '...' or ... clauses. The number of underlying requests
is returned as chunk_count and chunks run in parallel via asyncio.
Args:
indicator_code: e.g. "WHOSIS_000001".
countries: List of ISO3 codes, country names, region codes
(AFR/AMR/SEAR/EUR/EMR/WPR/GLOBAL), or income-group codes
(WB_HI/WB_UMI/WB_LMI/WB_LI).
country_group: Curated grouping code (e.g. "LAC", "OECD", "LDC",
"SSA"). Resolves to ISO3 members and merges with countries
if both are passed. See list_curated_country_groups for
available groups.
year_start: Inclusive lower bound on year.
year_end: Inclusive upper bound on year.
sex: "BTSX"/"both", "MLE"/"male", "FMLE"/"female", or raw SEX_* codes.
dim_filters: Extra dimension filters as {field: value}, e.g.
{"Dim2": "WEALTHQUINTILE_QUINTILE5"}. Use
describe_indicator_dimensions first to discover available types
and values. Cannot include "Dim1" if sex is also passed.
latest_only: If true, keep only the most recent year per spatial unit
and full dimension combination, preserving every population.
top: Per-request row cap, default 1000, max 5000. Applied to each
chunk of ≤10 spatial units, so the merged total may reach
top × chunk_count. This is not a per-country allowance: an
earlier country can consume a chunk and omit later countries.
Check missing_requested_codes and truncation flags.
format: "rows" (default) returns a list of dicts under the "rows" key;
"csv" returns a CSV string under the "csv" key.
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | ||
| top | No | ||
| format | No | rows | |
| year_end | No | ||
| countries | No | ||
| year_start | No | ||
| dim_filters | No | ||
| latest_only | No | ||
| country_group | No | ||
| indicator_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: automatic chunking into parallel HTTP calls, the chunk_count return value, top being applied per chunk rather than per country, truncation and missing_requested_codes flags, and exact format behavior. It also warns about the HTTP 400 limitation and clarifies latest_only semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative; every section adds operational value. The core one-line summary is front-loaded, followed by chunking caveats and then a clean Args block with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with 0% schema coverage and no annotations, the description covers parameter meanings, prerequisites, edge cases, and output formats. Since an output schema exists, not listing return fields is acceptable; 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?
Although schema description coverage is 0%, the Args section documents all 10 parameters with concrete examples, accepted value families, cross-parameter constraints (e.g., Dim1 cannot be used with sex), and per-chunk semantics for top. This fully compensates for the bare 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 opening line 'One indicator × N spatial units × year range, returned as tidy rows or CSV' precisely defines the tool's resource and output, and 'Workhorse for comparative analysis' states its role. The multi-spatial-unit scope and auto-resolution of country/region/income codes distinguish it from single-country sibling tools.
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 clear usage context: it is the workhorse for comparative analysis, recommends calling describe_indicator_dimensions before using dim_filters, and points to list_curated_country_groups for available groups. It also explains when chunking kicks in for large country sets, but it does not explicitly name alternative tools for single-country or raw data needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Latest values for a curated set of headline indicators in one country.
Fetches all indicators in parallel. Within the latest year, prefers known both-sex, all-age and total-residence codes; every chosen population is labeled. Ambiguous or incomplete populations return no headline value.
Args: country: ISO3 code, country name, region code, or income-group code. year: Optional reference year. If None, returns the most recent available value per indicator. If set, returns the latest value at or before that year. indicator_codes: Optional override of the headline indicator set. Defaults to a curated comparative-health-systems list. indicator_dim_filters: Per-indicator dimension filters, e.g. {"SDGPM25": {"Dim1": "RESIDENCEAREATYPE_TOTL"}}. Keys use the same whitelist as get_indicator_data. Filters apply before latest year selection; unmatched indicator keys raise an error.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| country | Yes | ||
| indicator_codes | No | ||
| indicator_dim_filters | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full burden and does so thoroughly: it discloses parallel fetching, the preference for both-sex/all-age/total-residence codes, labeling of populations, the no-value behavior for ambiguous populations, the year-selection semantics, and the error behavior for unmatched filter keys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in one clear sentence and the Args section is organized. It is on the longer side, but nearly every clause carries semantic weight — defaults, ordering, error behavior — so little is waste.
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 a rich output schema, the description appropriately omits return-format details while covering defaults, parameter semantics, error conditions, and selection behavior. No critical gap remains for an agent to call this 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 0%, and the description fully compensates: it defines valid country inputs (ISO3, name, region, income-group), explains year semantics including the None default, describes the indicator_codes override with its default curated list, and gives a concrete example for indicator_dim_filters plus ordering and error rules.
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 first sentence states a specific verb ('returns latest values'), a specific resource ('headline indicators'), and a scope ('in one country'). This distinguishes it from siblings like compare_countries and get_indicator_data without needing to open their 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?
The description implies when to use it — a country-level snapshot of a curated indicator set — and references get_indicator_data's whitelist for filter keys, which helps route an agent. However, it never explicitly states when NOT to use it or names an alternative for cases like raw data pulls or cross-country comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe which disaggregations (Dim1, Dim2, Dim3) an indicator uses, by sampling.
Args: indicator_code: e.g. "WHOSIS_000001". sample_size: Rows to sample, default 200, capped at 1000.
| Name | Required | Description | Default |
|---|---|---|---|
| sample_size | No | ||
| indicator_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that the tool works 'by sampling' and that sample_size is 'capped at 1000', which is useful behavioral context beyond the raw schema. However, it does not disclose potential inaccuracy from sampling, permission requirements, or side effects, which is a meaningful gap for a data-sampling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sections: a single-purpose sentence followed by terse parameter explanations. Every word earns its place—no fluff, examples are concrete, and the core action is front-loaded. This is excellent structure for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to explain return values. It covers the main action and parameters adequately. However, it could add context about what 'uses' means (e.g., presence of the disaggregation in the indicator's data) and note that sampling may miss rare disaggregations. These are minor gaps but prevent a higher score.
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 0%, so the description must compensate. It does this effectively: for indicator_code it provides a concrete example ('WHOSIS_000001'), and for sample_size it explains the meaning ('Rows to sample'), the default (200), and adds the cap (1000) not present in the schema. This adds significant value over the raw input schema, though it could elaborate on the format of indicator_code or the concept of disaggregations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Describe which disaggregations (Dim1, Dim2, Dim3) an indicator uses, by sampling.' This differentiates from siblings like list_dimensions (lists all dimensions) and get_dimension_values (retrieves values for a dimension) by focusing on which disaggregations an indicator uses. However, it doesn't explicitly name these alternatives, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus the sibling tools, nor any when-not conditions. The purpose statement implies usage (when you need to know which disaggregations an indicator uses), but there are no exclusions or alternative tool references. This leaves the agent to infer the selection logic from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find ISO3 country codes by name fragment (uses the COUNTRY dimension).
Args:
country: Full or partial country name, e.g. "Colombia" or "Korea".
Canonical parameter — matches the country field used by
get_indicator_data and country_profile.
country_name: Deprecated alias for country, kept for backward
compatibility. Pass either country or country_name, not both.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ||
| country_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must carry behavioral context. Discloses use of COUNTRY dimension and deprecation of country_name, but does not mention return format (ISO3 codes), auth needs, or side effects. Adequate but minimal.
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?
Description is two concise sentences plus a well-structured Args section. No wasted words, though the Args section could be integrated into the main description for better flow.
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?
Tool is simple with 2 optional string params and an output schema. Description explains parameters but omits what is returned (ISO3 codes). Given the output schema exists, the agent might infer, but explicit mention would improve completeness.
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 0%, but description adds meaningful semantics: country is canonical and matches other tools' field, country_name is deprecated alias. This compensates for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it finds ISO3 country codes by name fragment, using the COUNTRY dimension. The verb 'Find' and specific resource 'ISO3 country codes' make purpose precise. Distinguishes from siblings like country_profile (profile data) and get_indicator_data (data queries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides parameter usage details: country is canonical, country_name is deprecated alias, and to pass only one. However, it does not explicitly guide when to use this tool versus siblings like resolve_country_group_membership or country_profile, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the allowed values for a dimension.
Args: dimension_code: e.g. "COUNTRY", "REGION", "SEX", "AGEGROUP", "WORLDBANKINCOMEGROUP".
| Name | Required | Description | Default |
|---|---|---|---|
| dimension_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the basic function without mentioning error handling, response format, or any side effects. The presence of an output schema is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with a clear verb-object structure. The list of examples is placed after the main sentence, which is reasonable. However, it could be slightly more structured (e.g., separate param description).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description does not need to detail return values. However, it lacks information about error cases (e.g., invalid dimension_code) and does not clarify whether the output is a list or another type. For a simple tool, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description provides concrete examples for the sole parameter 'dimension_code' (e.g., 'COUNTRY', 'REGION'). This adds meaning beyond the schema's generic 'string' type, guiding the agent on valid inputs.
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 starts with 'Get the allowed values for a dimension,' which uses a specific verb and resource. It clearly distinguishes itself from sibling tools like 'list_dimensions' (which lists all dimensions) by indicating it retrieves values for a given dimension.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not contrast with 'describe_indicator_dimensions' or explain which dimensions are valid. The examples give a hint but no explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch observations for one indicator with optional filters.
Args:
indicator_code: e.g. "WHOSIS_000001" (life expectancy at birth).
country: ISO3 code, country name, region code (AFR/AMR/SEAR/EUR/EMR/WPR),
"GLOBAL", or income-group code (WB_HI/WB_UMI/WB_LMI/WB_LI).
region_code: Deprecated alias for country. Use country instead.
Cannot be combined with country — pass only one.
year_start: Inclusive lower bound on TimeDim (year).
year_end: Inclusive upper bound on TimeDim (year).
sex: Accepts "BTSX"/"both", "MLE"/"male", "FMLE"/"female"
or the raw "SEX_BTSX"/"SEX_MLE"/"SEX_FMLE" codes.
dim_filters: Extra dimension filters as {field: value}, e.g.
{"Dim1": "AGEGROUP_YEARS15-49"} or
{"Dim2": "RESIDENCEAREATYPE_RUR"}. Each pair becomes an
OData equality filter. Use describe_indicator_dimensions
first to see the available Dim1/Dim2 types and values for
an indicator. Cannot include "Dim1" if sex is also passed.
top: Max rows returned, default 100, capped at 1000.
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | ||
| top | No | ||
| country | No | ||
| year_end | No | ||
| year_start | No | ||
| dim_filters | No | ||
| region_code | No | ||
| indicator_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the 'top' parameter cap at 1000, default 100, and constraints like dim_filters vs sex conflict. However, it omits details like rate limits, data freshness, or pagination behavior, making it adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-organized docstring with clear bullet points and sections. It is somewhat long but each part adds value. Minor redundancy could be trimmed, but overall it is appropriately sized 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?
Given the complexity (8 parameters, no schema descriptions), the description covers all parameters, constraints, and cross-references (e.g., describe_indicator_dimensions). With an output schema present, return values are not needed. The description is complete for a data-fetching tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It does this excellently for all 8 parameters, providing valid values, examples, units, and constraints (e.g., region_code deprecated, dim_filters interaction). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch observations for one indicator with optional filters,' providing a specific verb and resource. However, it does not differentiate from sibling tools like get_indicator_data_raw, so purpose clarity is not perfect.
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?
There is no explicit guidance on when to use this tool versus siblings. While parameters are explained, the description lacks context like 'when to use get_indicator_data vs get_indicator_data_raw' or 'use describe_indicator_dimensions first,' which limits usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expert tool: pass-through OData query for advanced GHO use cases.
Use only when get_indicator_data and compare_countries can't express your query — for example, filtering by wealth quintile, education level, residence area, indicator-specific Dim2 values, or any unusual disaggregation we don't model with friendly parameters. The filter is passed verbatim, so you must format the OData syntax yourself.
Args:
indicator_code: e.g. "WHOSIS_000001".
filter: Raw OData $filter expression, e.g.
"SpatialDim eq 'COL' and Dim1 eq 'AGEGROUP_YEARS15-49'".
Single quotes inside string literals must be doubled ('').
top: Max rows returned, default 100, capped at 5000.
orderby: Raw OData $orderby, e.g. "TimeDim desc,SpatialDim".
Defaults to "TimeDim desc".
select: Raw OData $select listing fields to keep, e.g.
"SpatialDim,TimeDim,NumericValue".
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| filter | No | ||
| select | No | ||
| orderby | No | ||
| indicator_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses that the filter is passed verbatim and requires proper OData syntax, but does not mention rate limits or potential side effects. However, given the expert nature, this is largely sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary sentence, usage guidance, and a clear parameter list. Every sentence adds value, and there is no extraneous 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?
Given the complexity (5 parameters, output schema present), the description covers usage context, parameter details, and sibling relationships comprehensively. No gaps are apparent.
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 0%, so the description must add meaning. It thoroughly describes each parameter: indicator_code with example, filter with escaping syntax, top with default and cap, orderby with example and default, and select with example, providing significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a pass-through OData query for advanced GHO use cases, using specific verbs and resources, and explicitly distinguishes from sibling tools get_indicator_data and compare_countries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use only when get_indicator_data and compare_countries can't express your query' and provides examples of when to use it, giving clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full metadata record for an indicator (for citation/context).
Args: indicator_code: e.g. "WHOSIS_000001".
| Name | Required | Description | Default |
|---|---|---|---|
| indicator_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It states the output is a 'full metadata record' but does not detail what fields or structure to expect. The existence of an output schema helps, but the description could add more about the metadata contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately stating the purpose and then describing the parameter. Every word is useful with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (though not detailed here), the description does not need to explain return values. It provides enough context for a simple metadata retrieval tool, though a bit more detail on what 'full metadata' includes would improve completeness.
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 0%, so the description compensates well by providing an example value for indicator_code ('e.g. "WHOSIS_000001"'). This adds meaning beyond the schema's type definition, clarifying the expected format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Return the full metadata record for an indicator' with a specific purpose 'for citation/context'. The verb and resource are explicit, and it distinguishes from siblings like get_indicator_data (which returns data) and describe_indicator_dimensions.
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 'for citation/context' gives clear context for when to use this tool. While it does not explicitly state when not to use it or compare with alternatives, the purpose is sufficiently clear given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Decilion's curated country groupings (WB regions, LDCs, OECD).
Returns groups beyond GHO's built-in WHO regions (AFR/AMR/etc.) and
World Bank income-group codes — World Bank geographic regions, the UN
Least Developed Countries list, and OECD membership. Use the returned
members lists with the countries parameter on compare_countries,
or pass the group code to resolve_country_group_membership.
These groupings mirror those in ghed-mcp so a regional analysis behaves consistently across the GHO and GHED servers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool returns curated groups, notes consistency with ghed-mcp, and implies read-only behavior. No side effects or destructive actions mentioned.
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?
Very concise, two well-structured paragraphs. First sentence states main purpose, second details groups, and remaining sentences explain usage and consistency. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and presence of output schema, the description is complete. It explains what is returned and how to use the output effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline is 4 per guidelines. The description adds no parameter info beyond 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 clearly lists the specific country groupings (WB regions, LDCs, OECD) and distinguishes them from built-in WHO regions and World Bank income-group codes. Verb 'list' with specific resource makes purpose 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?
The description explains when to use this tool (for groupings beyond built-in ones) and how to use the results with compare_countries and resolve_country_group_membership. It provides clear context but does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all GHO dimensions (e.g. COUNTRY, REGION, SEX, AGEGROUP, WORLDBANKINCOMEGROUP).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description discloses scope ('all GHO dimensions') and examples, but omits details like ordering, pagination, or response format. Basic but adequate for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no extraneous content, front-loaded with the core action.
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 zero parameters and an output schema, the description provides examples but could be more complete, e.g., explaining that these are categories for filtering data or linking to related 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?
No parameters; description adds value by providing concrete examples of dimensions, clarifying the tool's output beyond an empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List all GHO dimensions' with examples, clearly indicating the resource and verb. However, it does not differentiate from sibling tools like describe_indicator_dimensions.
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 from the purpose, but no explicit guidance on when to use this tool versus alternatives. No when-not or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List World Bank income-group spatial codes usable in compare_countries.
Returns codes like WB_HI, WB_UMI, WB_LMI, WB_LI alongside their titles.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It reveals that the tool returns codes and titles, which is essential. However, it does not mention whether the operation is read-only, if any authentication is needed, or the static nature of the data. The transparency is adequate but not deep.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the primary purpose, and the second provides an example of returned values. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, static data) and has an output schema, so the description need not detail return structure. It sufficiently covers the purpose and return content. The context of use in compare_countries is provided, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so baseline is 4. The description adds value by stating what information is returned (codes and titles), which is not in the empty schema. No further parameter details are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing World Bank income-group spatial codes. It uses a specific verb ('List'), identifies the resource ('income-group spatial codes'), and notes the usage context ('usable in compare_countries'). This distinguishes it from sibling tools like list_curated_country_groups.
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 when to use the tool (to get income group codes for use in compare_countries) but does not explicitly state when not to use it or mention alternatives. The context is clear, so it's a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WHO GHO indicators (paginated).
Args: skip: Number of records to skip for pagination. top: Page size, max 200.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains pagination via skip/top but omits details like result ordering, empty results behavior, or any constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose and efficient parameter explanations. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description adequately covers pagination. However, it could mention whether the list is exhaustive, sorted, or has a maximum skip value.
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?
Despite 0% schema description coverage, the description clearly defines 'skip' as records to skip and 'top' as page size with max 200, adding essential semantics beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists WHO GHO indicators with pagination, which is a specific verb-resource pair. It distinguishes from sibling tools like search_indicators by implying a comprehensive listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like search_indicators. The description does not provide context for appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a curated group code to its ISO3 member list.
Accepts canonical codes (LAC, SSA, LDC, OECD, …), official WB region codes (LCN, SSF, …), and common spellings ("Latin America and Caribbean", "Sub-Saharan Africa", "Least Developed Countries").
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It discloses that the tool accepts various input formats and resolves to an ISO3 member list, implying a safe read operation. However, it does not mention error handling (e.g., if group not found) or output format, which is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence states the core action; the second lists input variants. No redundant words, and the structure is clear 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?
Given the tool's simplicity (one parameter, output schema exists), the description is mostly complete. It covers the main function and acceptable inputs. It could briefly note that the output is a list of ISO3 codes, but the output schema presumably handles that. Minor gap: no mention of validation or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required 'group' parameter with no description (0% coverage). The description compensates fully by listing acceptable formats: canonical codes (LAC, SSA, LDC, OECD), official WB region codes (LCN, SSF), and common spellings. This adds significant semantic meaning for an AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Resolve a curated group code to its ISO3 member list.' It uses a specific verb and resource, and distinguishes itself from sibling tools like list_curated_country_groups (which lists groups) and compare_countries (which compares countries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests usage by listing accepted input types (canonical codes, official WB region codes, common spellings), but does not explicitly state when to use this tool versus alternatives or provide exclusions. No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GHO indicators by case-insensitive substring of IndicatorName.
Args: query: Free-text fragment, e.g. "life expectancy" or "tuberculosis". top: Max results, default 50, capped at 200.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses case-insensitive substring matching and the top parameter cap of 200. It does not mention error handling or empty results, but overall provides key behavioral traits.
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 plus parameter list. Purpose is front-loaded, each line is essential, no redundancy. Extremely concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with an output schema, the description covers all necessary details: purpose, parameters with constraints, and search behavior. No gaps identified given the context signals.
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 0%, so description must add meaning. It explains both parameters: query as free-text with examples, top as max results with default and cap, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches GHO indicators by case-insensitive substring of IndicatorName, using specific verbs and resource. It distinguishes from sibling tools like list_indicators by specifying a search function rather than listing all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus sibling tools. Examples are provided, but no comparison to alternatives like list_indicators or get_indicator_metadata is made, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Curated index of comparative-health-systems topics → indicator codes.
Covers health outcomes, service coverage, workforce, financing, NCDs, infectious diseases, child health, risk factors, mental health, environment/climate, medicines access, quality & safety, and equity/SDG framing. Pass any returned code to get_indicator_metadata or compare_countries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention any side effects, readonly behavior, or caching. For a zero-parameter tool, it is adequate but lacks detail on output structure or update frequency, though an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences covering purpose, scope, and usage guidance. No redundant phrases, and the structure is front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description provides sufficient context: it explains what the tool returns (topic-code mapping), lists covered areas, and suggests downstream tools. No additional information is necessary for correct 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?
There are no parameters, so schema coverage is trivially 100%. The description adds no parameter information because none exist. With zero parameters, a baseline of 4 is appropriate; the description does not need to add 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 clearly states it is a curated index that maps topics to indicator codes, listing a broad range of health system topics. This distinguishes it from siblings like get_indicator_metadata or compare_countries, which operate on individual codes rather than providing a topic-to-code mapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the user to pass returned codes to get_indicator_metadata or compare_countries, providing clear next steps. While it doesn't explicitly state when not to use this tool, the context implies it is the starting point for topic exploration, and no alternatives are mentioned, which is acceptable given its unique role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.0country_profile1 field changedInput schema / properties / indicator_dim_filtersAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Indicator Dim Filters"
+}v0.6.1compare_countriescountry_profiledescribe_indicator_dimensionsfind_country_codeget_dimension_valuesget_indicator_dataget_indicator_data_rawget_indicator_metadatalist_curated_country_groupslist_dimensionslist_income_groupslist_indicatorsresolve_country_group_membershipsearch_indicatorstopics_indexScored across 15 tools
compare_countries and get_indicator_data overlap heavily—both fetch observations for one indicator with country/region/income filters, year ranges, sex, and dimension filters—differing mainly in multi-country support. get_indicator_data_raw is clearly distinct as raw OData, and discovery tools are mostly distinct, but the two friendly data-fetch tools create real selection ambiguity.
Most tools follow a clear verb_noun pattern (list_dimensions, get_indicator_metadata, search_indicators, resolve_country_group_membership). A few nouns like topics_index and country_profile, plus compare_countries, deviate slightly, but there is no mixed casing or unpredictable verb style.
15 tools is within the ideal range and covers discovery, metadata, retrieval, and raw access. The count is slightly inflated by the get_indicator_data vs compare_countries overlap, so not every tool feels strictly necessary, but the overall scope is manageable.
For a read-only health data API, the surface is complete: indicator discovery, dimension introspection, country/group resolution, metadata, friendly and raw data access, and a multi-indicator country profile are all present. No obvious dead ends exist; even advanced queries have an escape hatch via raw OData.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Hosted MCP server for live public-data APIs and Skills for AI agents.
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
