Search UNESCO World Heritage sites, intangible heritage, biosphere reserves, and Global Geoparks.
Scored across 9 tools
Each tool targets a distinct UNESCO program: World Heritage sites, Biosphere Reserves, Global Geoparks, and Intangible Cultural Heritage. The get/search pairs are clearly separated by resource type, and unesco_list_reference serves as a vocabulary helper with no overlap.
All tool names follow a consistent unesco_verb_noun pattern: unesco_get_*, unesco_search_*, unesco_list_reference. The resource names are predictable and match their program domain.
9 tools perfectly cover four distinct UNESCO datasets, each with a dedicated get and search function, plus a reference tool. This is a well-scoped set with no redundant tools.
The surface provides full read/search access across four major UNESCO heritage programs. However, it lacks any write operations (e.g., creating or updating records), though these may not be applicable for a public data server. No obvious gaps in retrieval capabilities.
Fetch one biosphere reserve's full record by mab_id: its introduction, ecological and socio-economic characteristics, core, buffer, and transition areas (terrestrial and marine, in hectares) with resident population by zone, designation, extension, renaming, and periodic-review years, coordinates, and its UNESCO page.
| Name | Required | Description | Default |
|---|---|---|---|
| mab_id | Yes | The reserve's mab_id, from unesco_search_biosphere_reserves. Case and accents are ignored. |
| Name | Required | Description |
|---|---|---|
| url | No | The reserve's UNESCO page URL. |
| name | No | English name. |
| sids | No | True when the reserve is in a Small Island Developing State. |
| error | No | Present when the call failed. Absent on success. |
| mab_id | No | Biosphere reserve id (mab_id). |
| country | No | Country name as UNESCO records it. |
| regions | No | UNESCO regions the reserve belongs to. |
| sources | No | Datasets this response was built from. |
| website | No | The reserve's own website, when recorded. |
| latitude | No | Representative point latitude. |
| longitude | No | Representative point longitude. |
| population | No | Resident population by zone, as recorded; 0 can mean none or unreported, and zone sums do not always match the total. |
| country_code | No | ISO 3166-1 alpha-2 code of the reserve country. |
| introduction | No | UNESCO's introduction to the reserve. |
| area_hectares | No | Areas in hectares (unit inferred; undocumented upstream), as recorded — the server computes no totals, and zone sums do not always match the totals. |
| transboundary | No | True for a transboundary reserve; each participating country has its own mab_id. |
| renaming_years | No | Years the reserve was renamed; empty when none. |
| extension_years | No | Years the reserve was extended; empty when none. |
| designation_year | No | Year of designation. |
| regional_network | No | MAB regional network, when the reserve belongs to one. |
| periodic_review_years | No | Years of periodic review; empty when none recorded. |
| ecological_characteristics | No | Ecological characteristics, when recorded. |
| socio_economic_characteristics | No | Socio-economic characteristics, when recorded. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered; the description adds meaningful behavioral context by enumerating the record's content scope (zones in hectares, population by zone, designation/extension/renaming/review years, coordinates, UNESCO page).
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?
One front-loaded sentence that leads with the verb and resource; the long enumeration of returned fields is dense but relevant, with little wasted wording.
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 single-parameter read tool with full schema coverage, annotations, and an output schema, the definition is essentially complete; the field enumeration is arguably redundant with the output schema but not harmful.
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 parameter's description already covers source, case/accent insensitivity, and length bounds. The description adds only 'by mab_id', so the baseline of 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 ('Fetch') and resource ('one biosphere reserve's full record') scoped by 'mab_id', which cleanly separates it from unesco_search_biosphere_reserves and the other unesco_get_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies single-record retrieval and the schema notes the mab_id comes from unesco_search_biosphere_reserves, but the description itself gives no explicit when-to-use vs. when-to-search guidance or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one UNESCO Global Geopark's full record by ugg_id: its countries, designation year, transnational status, area and resident population as recorded, coordinates, UNESCO's introduction and description, its account of how the geopark sustains local communities, its own website, and its UNESCO page.
| Name | Required | Description | Default |
|---|---|---|---|
| ugg_id | Yes | The geopark's ugg_id, such as EUFR10, from unesco_search_geoparks. Case and surrounding whitespace are ignored. |
| Name | Required | Description |
|---|---|---|
| url | No | The geopark's UNESCO page URL. |
| name | No | English name. |
| error | No | Present when the call failed. Absent on success. |
| ugg_id | No | UNESCO Global Geopark id (ugg_id). |
| sources | No | Datasets this response was built from. |
| website | No | The geopark's own website, when recorded. |
| latitude | No | Latitude of the geopark's point. |
| countries | No | Country display names aligned with country_codes. |
| longitude | No | Longitude of the geopark's point. |
| population | No | Resident population, as recorded; absent when UNESCO records none, and 0 can mean unreported. |
| description | No | UNESCO's description of the geopark. |
| introduction | No | UNESCO's introduction to the geopark. |
| area_hectares | No | Area in hectares, as recorded. |
| country_codes | No | ISO 3166-1 alpha-2 codes of the geopark's countries; a transnational geopark lists each. |
| transnational | No | True when the geopark spans more than one country. |
| designation_year | No | Designation year; geoparks UNESCO recognized before the Global Geopark label existed are dated 2015, the year it was created. |
| sustaining_local_communities | No | UNESCO's account of how the geopark sustains its local communities. |
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 that this is a single-record retrieval of a 'full record', but the enumerated return fields largely restate the output schema rather than disclosing new behavioral traits such as failure modes for unknown ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence leads with the action and key parameter before listing the payload contents. It is slightly list-heavy, but every clause maps to a distinct part of the record and nothing is repeated.
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 lookup tool with an output schema, annotations covering safety, and fully documented parameters, the description supplies enough context to call it correctly. The only shortfall is the absence of guidance on invalid or unknown id behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 100% schema description coverage, the schema already explains ugg_id, its pattern, and case/whitespace normalization. The description only reiterates 'by ugg_id' and adds no format or lookup semantics beyond it, 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 opens with a specific verb and resource ('Fetch one UNESCO Global Geopark's full record by ugg_id') and enumerates the returned fields, making it trivially distinguishable from siblings like unesco_get_site and unesco_get_biosphere_reserve. An agent can select it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the get-by-id shape, and the id's provenance (unesco_search_geoparks) is documented in the schema rather than the description. There is no explicit when-to-use/when-not guidance or contrast against the other get_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one Intangible Cultural Heritage element's full record by ich_ref: its description, the list it is inscribed on, the countries that share it, its inscription year, UNESCO concept terms, the World Heritage sites UNESCO links to it, its UNESCO page, and the main image with its caption and copyright credit.
| Name | Required | Description | Default |
|---|---|---|---|
| ich_ref | Yes | The element's ich_ref, from unesco_search_intangible_heritage. A number, a digit string, or the element's ich.unesco.org/en/{RL|USL|Art18}/{ref} page URL. |
| Name | Required | Description |
|---|---|---|
| url | No | The element's UNESCO page URL. |
| list | No | The list the element is inscribed on: Representative List, Urgent Safeguarding List, or Register of Good Safeguarding Practices. |
| name | No | English name. |
| error | No | Present when the call failed. Absent on success. |
| image | No | Main image with its caption and credit, when UNESCO lists one. |
| ich_ref | No | Intangible heritage element reference (ich_ref). |
| name_fr | No | French name. |
| sources | No | Datasets this response was built from. |
| concepts | No | Primary UNESCO concept terms; empty for the few elements without any. |
| countries | No | Country display names aligned with country_codes. |
| description | No | UNESCO's description of the element. |
| country_codes | No | ISO 3166-1 alpha-2 codes of the countries sharing the element, as UNESCO lists them. |
| multinational | No | True when more than one country shares the element. |
| inscribed_year | No | Inscription year. Elements dated 2008 were incorporated into the Representative List that year after an earlier proclamation. |
| concepts_secondary | No | Secondary UNESCO concept terms. |
| world_heritage_sites | No | World Heritage sites UNESCO links to the element; empty when none are linked. |
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 only the scope of the returned record. It says nothing about error behavior for a bad ref or whether results are live from UNESCO's site, and most of its content duplicates what the output schema carries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that opens with the action and identifier before listing record contents. It is efficient, though the long field enumeration reads more like a return-value manifest than selection guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so enumerating description, lists, countries, year, concepts, linked sites, page and image is largely redundant; the description compensates for no usage routing or error expectations. Adequate for a simple one-param getter, but not adding much beyond structured fields.
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 schema itself documents ich_ref's pattern, format flexibility (bare number, digit string, or full ich.unesco.org URL) and upstream source. The description's 'by ich_ref' adds no meaning beyond that, 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 (fetch), resource (one Intangible Cultural Heritage element's full record) and the exact key (ich_ref). 'One ... full record' clearly separates it from the sibling search/list tools that return multiple partial items.
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: the schema notes the ref comes from unesco_search_intangible_heritage, so the search-then-fetch flow is inferable, but the description itself never states when to use this over unesco_search_intangible_heritage or what to do with an invalid/unfindable ref.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one World Heritage site's full record by id_no: its description, statement of Outstanding Universal Value, each inscription criterion with its meaning (criterion (vi) marked as inferred), States Parties, coordinates, area, inscription and later years, Danger-list year, component parts, names in six languages, and the main image with its copyright credit. Intangible heritage UNESCO links to the site is listed by unesco_search_intangible_heritage with world_heritage_site.
| Name | Required | Description | Default |
|---|---|---|---|
| id_no | Yes | The site's World Heritage id_no, from unesco_search_sites. A number, a digit string, or the site's whc.unesco.org/en/list/{id} page URL. | |
| max_components | No | Maximum component parts to list (0–1000, default 20). 0 omits the list but keeps components_total; the largest site has 758 components. |
| Name | Required | Description |
|---|---|---|
| cap | No | The max_components that was applied. |
| url | No | The site's UNESCO page URL. |
| name | No | English name. |
| error | No | Present when the call failed. Absent on success. |
| id_no | No | World Heritage id_no. |
| image | No | Main image with its credit, when UNESCO lists one. |
| names | No | Names in the other UNESCO languages, each present when UNESCO records it. |
| shown | No | Components listed. |
| notice | No | How to list more components, or why some are missing. |
| region | No | UNESCO region. |
| states | No | States Parties as UNESCO names them. |
| sources | No | Datasets this response was built from. |
| category | No | Cultural, Natural, or Mixed. |
| criteria | No | Inscription criteria in numeral order. |
| latitude | No | Representative point latitude, when recorded. |
| in_danger | No | True when the site is on the List of World Heritage in Danger. |
| longitude | No | Representative point longitude, when recorded. |
| truncated | No | True when the component list was capped at max_components. |
| components | No | Component parts in UNESCO order, up to max_components. |
| description | No | UNESCO's short description, when recorded. |
| area_hectares | No | Area in hectares, when recorded. |
| country_codes | No | ISO 3166-1 alpha-2 codes aligned with states; empty for the one site without a code. |
| justification | No | The statement of Outstanding Universal Value, when recorded. |
| transboundary | No | True when the site spans more than one State Party. |
| inscribed_year | No | Year of inscription. |
| secondary_years | No | Later years UNESCO's secondary dates list for the site after inscription; empty when none. |
| components_total | No | UNESCO's component count for the site. |
| danger_listed_year | No | Year of the site's current Danger-list entry, when in danger. |
| components_unparsed | No | Entries of UNESCO's component list that could not be read and are omitted; 0 normally. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to cover safety or idempotency. It adds real behavioral context: the record's completeness (description, OUV, criteria, States Parties, coordinates, area, dates, Danger-list year, component parts, multilingual names, main image + copyright), a data-quality caveat ('criterion (vi) marked as inferred'), and a pointer that intangible heritage is deliberately excluded. It doesn't mention failure modes for invalid/missing id_no, which keeps it from 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense but front-loaded sentence covering purpose, identifier, and payload fields, followed by a second sentence handling the intangible-heritage boundary. Nothing is padded, though the long enumerated field list is heavy for a description and the final sentence could be trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, output-schema-backed lookup, an agent needs to know what the record contains and what it excludes—both are covered. The 'inferred' criterion caveat is a nice touch. Only the invalid-id_no behavior and any rate/access constraints remain unspecified, minor given the rich output schema and safe annotations.
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 schema descriptions already explain that id_no accepts a number, digit string, or whc.unesco.org URL, plus max_components' 0–1000 range, default 20, and the '758 components' worst case. The description refers to 'id_no' and 'component parts' but adds no format or constraint detail the schema lacks, 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+resource ('Fetch one World Heritage site's full record by id_no') and immediately specifies the scope ('full record'). The adjacent sentence distinguishes it from unesco_search_sites and the intangible-heritage sibling, so an agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by id_no' constraint and the explicit pointer to unesco_search_sites for obtaining the id effectively state when to use this tool. It also names the sibling that handles the intangible-heritage linkage ('listed by unesco_search_intangible_heritage'), routing the agent away from expecting this tool to return that data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vocabulary the other unesco_ tools accept and the coverage of the underlying datasets: the ten inscription criteria with their meanings and site counts, the countries in each dataset with their ISO alpha-2 and alpha-3 codes and record counts, the five UNESCO regions, the three intangible heritage lists, the MAB regional networks, and each dataset's record count, license, and data date. Set filter to narrow a topic to matching entries, for example a country name to find its code.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | What to list. criteria: the ten inscription criteria (i)–(x) with meanings and site counts, the values of the criteria input of unesco_search_sites. countries: every country with its ISO alpha-2 and alpha-3 codes and counts per dataset, the values of every country input. regions: the five UNESCO regions with codes, the values of the region inputs. intangible_lists: the three intangible heritage lists with acronyms, the values of the list input of unesco_search_intangible_heritage. biosphere_networks: the MAB regional networks with acronyms, the values of the regional_network input of unesco_search_biosphere_reserves. datasets: each dataset with its record count, data date, license, attribution, and coverage notes. | |
| filter | No | Keep only entries whose name or code (a criterion's meaning, a dataset's title) contains every word of this text, each word matching at the start of a word. Case, accents, and punctuation are ignored, so the filter must contain at least one letter or digit and at most 16 distinct words. For example, a country name finds its ISO code. For countries, a two- or three-letter ISO code (or UK) keeps exactly that country, as the country inputs read it, and common former or everyday names such as Turkey, Swaziland, or Holland match too. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| topic | No | The topic listed. |
| notice | No | Guidance when the filter matched no entry. |
| regions | No | Region rows (topic regions). |
| sources | No | Datasets this response was built from. |
| criteria | No | Criteria rows (topic criteria). |
| datasets | No | Dataset rows (topic datasets). |
| countries | No | Country rows sorted by name (topic countries). |
| intangible_lists | No | Intangible heritage list rows (topic intangible_lists). |
| biosphere_networks | No | MAB regional network rows (topic biosphere_networks). |
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 the shape of the listing (what each topic contains) but since an output schema exists this is partly redundant, and it says nothing about size, pagination or truncation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded and the filter guidance comes second. The first sentence is a long enumeration, but every element (criteria, countries, regions, lists, networks, datasets) maps to a real topic value, so the density earns its place rather than being 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?
With an output schema, 100% schema description coverage, and read-only/idempotent annotations, the description supplies everything else an agent needs: the mapping between topic values and datasets, and how filter interacts with the lists.
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 schema's own enum and filter descriptions are extremely detailed, so the baseline is 3. The description reinforces the filter's purpose with a concrete example (country name to find its code) but adds no semantics 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?
The description opens with a specific verb+resource: it lists the reference vocabulary that the unesco_ search/get tools accept. It enumerates exactly what is returned per topic (criteria, countries, regions, lists, networks, datasets), clearly distinguishing this lookup tool from the sibling search/get 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?
It implies the use case well by framing the tool as the source of values the other unesco_ tools accept, so an agent knows to call it to resolve valid inputs. It also explains how filter narrows a topic (e.g. a country name to find its code). It does not explicitly state when not to use it, but no sibling overlaps its lookup role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the World Network of Biosphere Reserves (UNESCO Man and the Biosphere Programme) by keyword, country, region, MAB regional network, designation year range, transboundary or Small Island Developing States status, or distance from a point. Every keyword must appear at the start of a word in the reserve's name, introduction, or ecological or socio-economic description; there is no biome or ecosystem field, so an ecosystem search is a keyword search such as mangrove or alpine. A country is an ISO 3166-1 alpha-2 or alpha-3 code. A transboundary reserve appears once per participating country, each with its own mab_id. Results page with next_cursor and carry facet counts over the whole match.
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Only reserves within radius_km of this point. Every reserve has coordinates. | |
| sids | No | true: only reserves in Small Island Developing States. false: only reserves elsewhere. | |
| sort | No | Result order. Default: relevance when query is set, else distance when near is set, else name. relevance needs query; distance needs near. area_largest orders by total recorded area. | |
| limit | No | Maximum results per page (1–50, default 20). | |
| query | No | Keywords; every word must match the start of a word in the reserve's name, introduction, or ecological or socio-economic description. Case, accents, and punctuation are ignored, so the query must contain at least one letter or digit and at most 16 distinct words; no phrases, operators, or fuzzy matching. For an ecosystem, use a habitat word such as mangrove, wetland, or alpine. | |
| cursor | No | Opaque continuation cursor from the previous call's next_cursor. Pass it with the same filters and sort to fetch the next page. | |
| region | No | UNESCO region: Africa, Arab States, Asia and the Pacific, Europe and North America, or Latin America and the Caribbean (codes AFR, ARB, APA, EUR, LAC accepted). Matches any of a reserve's regions. | |
| country | No | ISO 3166-1 alpha-2 or alpha-3 code, any case (FR, FRA). Matches the reserve's country; a transboundary reserve has one row per participating country. For a country name, look up its code with unesco_list_reference (topic countries). | |
| designated_to | No | Latest designation year, inclusive. | |
| transboundary | No | true: only transboundary reserves (one row per participating country). false: only single-country reserves. | |
| designated_from | No | Earliest designation year, inclusive. | |
| regional_network | No | MAB regional network, by full name or acronym (AfriMAB, ArabMAB, EABRN, EuroMAB, IberoMAB, SACAM, SeaBRnet), any case. A few reserves belong to no network. | |
| include_description | No | Set false to leave each row's introduction out of the response (default true); unesco_get_biosphere_reserve returns it. Which reserves match, their order, and matched_in are unchanged. |
| Name | Required | Description |
|---|---|---|
| cap | No | The page size (limit) that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results on this page. |
| facets | No | Facet counts over the whole match, not just this page. |
| notice | No | Guidance on the result: why nothing matched, caveats, or how to continue paging. |
| sources | No | Datasets this response was built from. |
| reserves | No | Matching reserves on this page. |
| truncated | No | True when more results remain beyond this page. |
| totalCount | No | Total matches across all pages. |
| next_cursor | No | Pass as cursor, with the same filters and sort, to fetch the next page. Present when more results remain. |
| applied_filters | No | The filters and sort as the server applied them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and openWorld, so safety is covered; the description then adds genuinely non-obvious behavior: prefix-word keyword matching, no biome/ecosystem field, transboundary reserves duplicated one row per participating country each with its own mab_id, cursor pagination via next_cursor, and facet counts spanning the whole match rather than the page.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the resource and the facet list, then layers in matching rules and paging behavior with no filler. It is dense and long-ish, but each sentence carries information an agent needs to build a correct query.
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 13-parameter tool with a nested near object, enums, and an output schema, the description supplies everything the structured fields do not: matching semantics, duplication behavior, pagination and facet scope, and the sibling calls for country-code lookup and full descriptions. Nothing required to call 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%, so the baseline is 3, but the description adds meaning the schema does not: the word-prefix matching rule for query, the accepted country code forms in context, the caveat that a few reserves belong to no regional network, and the cross-field relationship between transboundary and row duplication. It largely restates the near/sort/paging semantics that 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 (Search) and a precisely scoped resource (World Network of Biosphere Reserves / UNESCO MAB) and immediately enumerates the facets it searches on. It also names the sibling unesco_get_biosphere_reserve, so an agent can separate search from retrieval without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context on how and when to use it: keyword, country code, region, network, year range, transboundary, SIDS, or proximity, plus the ecosystem-search workaround ('an ecosystem search is a keyword search such as mangrove or alpine'). It also routes two sub-tasks to siblings (unesco_list_reference for country codes, unesco_get_biosphere_reserve for the full description), but it never contrasts itself with unesco_search_sites/geoparks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search UNESCO Global Geoparks by keyword, country, designation year range, transnational status, or distance from a point. Every keyword must appear at the start of a word in the geopark's name, introduction, description, or account of how it sustains local communities, and name matches rank first. A country is an ISO 3166-1 alpha-2 or alpha-3 code and matches every geopark it takes part in, transnational geoparks included. Geoparks UNESCO recognized before the Global Geopark label existed are dated 2015, the year it was created. Results page with next_cursor and carry facet counts over the whole match.
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Only geoparks within radius_km of this point. Every geopark has one point, which the distance measures. | |
| sort | No | Result order. Default: relevance when query is set, else distance when near is set, else name. relevance needs query; distance needs near. area_largest orders by recorded area. | |
| limit | No | Maximum results per page (1–50, default 20). | |
| query | No | Keywords; every word must match the start of a word in the geopark's name, introduction, description, or account of sustaining local communities. Case, accents, and punctuation are ignored, so the query must contain at least one letter or digit and at most 16 distinct words; no phrases, operators, or fuzzy matching. For a landform, use a word such as volcanic, karst, or fossil. | |
| cursor | No | Opaque continuation cursor from the previous call's next_cursor. Pass it with the same filters and sort to fetch the next page. | |
| country | No | ISO 3166-1 alpha-2 or alpha-3 code, any case (FR, FRA). Matches every geopark the country takes part in, transnational geoparks included. For a country name, look up its code with unesco_list_reference (topic countries). | |
| designated_to | No | Latest designation year, inclusive. | |
| transnational | No | true: only geoparks spanning more than one country. false: only single-country geoparks. | |
| designated_from | No | Earliest designation year, inclusive. | |
| include_description | No | Set false to leave each row's introduction out of the response (default true); unesco_get_geopark returns it. Which geoparks match, their order, and matched_in are unchanged. |
| Name | Required | Description |
|---|---|---|
| cap | No | The page size (limit) that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results on this page. |
| facets | No | Facet counts over the whole match, not just this page. |
| notice | No | Guidance on the result: why nothing matched, caveats, or how to continue paging. |
| sources | No | Datasets this response was built from. |
| geoparks | No | Matching geoparks on this page. |
| truncated | No | True when more results remain beyond this page. |
| totalCount | No | Total matches across all pages. |
| next_cursor | No | Pass as cursor, with the same filters and sort, to fetch the next page. Present when more results remain. |
| applied_filters | No | The filters and sort as the server applied them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/openWorld/idempotent, so the description carries the real burden and delivers: word-start matching rule, name matches rank first, country-code matching that includes transnational geoparks, the non-obvious 2015 designation-year normalization for pre-label geoparks, cursor pagination, and whole-match facet counts. These are genuinely useful quirks an agent could not infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence and the five sentences are dense with substance. There is minor overlap with the schema's own parameter descriptions, keeping it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter search tool with an output schema present, the description covers matching semantics, the country-code edge case, the designation-year quirk, and pagination, leaving nothing an agent needs in order to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already documented (including enums, defaults, and the cursor contract), so the baseline is 3. The description re-states the query and country semantics that the schema already contains, adding little beyond it.
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 (Search) and resource (UNESCO Global Geoparks) and enumerates all filter facets. It is clearly distinguishable from the sibling retrieval tools (unesco_get_geopark) and other search_* tools by resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for the filters and routes the agent to siblings in two places: unesco_list_reference to resolve a country name to a code, and unesco_get_geopark to fetch the full introduction. It stops short of an explicit when-to-use-this-vs-other-search-tools statement, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search UNESCO's Intangible Cultural Heritage lists — the Representative List, the Urgent Safeguarding List, and the Register of Good Safeguarding Practices — by keyword, country, list, inscription year range, multinational status, or linked World Heritage site. Every keyword must appear at the start of a word in an element's English or French name, its UNESCO concept terms, or its description, and name matches rank first. A country is an ISO 3166-1 alpha-2 or alpha-3 code and matches every element it shares, multinational elements included. world_heritage_site takes a site's id_no and lists the elements UNESCO links to it. Rows omit the description; read it with unesco_get_intangible_heritage_element. Results page with next_cursor and carry facet counts over the whole match.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Intangible heritage list: Representative List, Urgent Safeguarding List, or Register of Good Safeguarding Practices (acronyms RL, USL, Art18 accepted). | |
| sort | No | Result order. Default: relevance when query is set, else name. relevance needs query. | |
| limit | No | Maximum results per page (1–50, default 20). | |
| query | No | Keywords; every word must match the start of a word in an element's English or French name, its UNESCO concept terms, or its description. Case, accents, and punctuation are ignored, so the query must contain at least one letter or digit and at most 16 distinct words; no phrases, operators, or fuzzy matching. | |
| cursor | No | Opaque continuation cursor from the previous call's next_cursor. Pass it with the same filters and sort to fetch the next page. | |
| country | No | ISO 3166-1 alpha-2 or alpha-3 code, any case (FR, FRA). Matches every element the country shares, multinational elements included. For a country name, look up its code with unesco_list_reference (topic countries). | |
| inscribed_to | No | Latest inscription year, inclusive. | |
| multinational | No | true: only elements shared by more than one country. false: only single-country elements. | |
| inscribed_from | No | Earliest inscription year, inclusive. | |
| world_heritage_site | No | A World Heritage site's id_no (from unesco_search_sites or unesco_get_site); lists the elements UNESCO links to that site. A number, a digit string, or the site's whc.unesco.org/en/list/{id} page URL. |
| Name | Required | Description |
|---|---|---|
| cap | No | The page size (limit) that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results on this page. |
| facets | No | Facet counts over the whole match, not just this page. |
| notice | No | Guidance on the result: why nothing matched, caveats, or how to continue paging. |
| sources | No | Datasets this response was built from. |
| elements | No | Matching elements on this page. |
| truncated | No | True when more results remain beyond this page. |
| totalCount | No | Total matches across all pages. |
| next_cursor | No | Pass as cursor, with the same filters and sort, to fetch the next page. Present when more results remain. |
| applied_filters | No | The filters and sort as the server applied them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, open-world), so the description's job is to add behavioral detail — and it does: it states that every keyword must match word-starts, that name matches rank first, that rows omit the description field, that results page with next_cursor, and that facet counts cover the whole match. This is above the annotation baseline, though it doesn't disclose rate limits or max result size beyond what schema shows.
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?
Five sentences, front-loaded with scope, then matching semantics, then parameter clarifications. Every sentence carries substantive information; minor redundancy between 'a World Heritage site's id_no' and later explanation, but generally tight for a 10-parameter tool.
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 search with output schema present, the description covers scope, matching behavior, pagination, facet behavior, deferred fields, and cross-tool routing. An agent has enough to formulate and page through queries correctly without opening the schema, and return-value explanation is correctly delegated to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description meaningfully elaborates: query matching semantics (prefix match across name/concept terms/description), ISO alpha-2/alpha-3 for country with multinational inclusion, id_no semantics for world_heritage_site, and the requirement to pass cursor with the same filters. It adds value beyond the schema descriptions without duplicating them wholesale.
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 opens with a specific verb+resource ('Search UNESCO's Intangible Cultural Heritage lists') and enumerates the three constituent lists by name, immediately distinguishing it from sibling searches (unesco_search_sites, unesco_search_geoparks, unesco_search_biosphere_reserves). It also distinguishes itself from the element-fetch sibling by pointing to unesco_get_intangible_heritage_element for descriptions.
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 clearly implies context of use (keyword/country/list/year/multinational/world_heritage_site filtering) and explicitly routes to unesco_get_intangible_heritage_element for full descriptions and to unesco_list_reference for country code lookup. It lacks an explicit 'when not to use' or 'use search_sites instead' exclusion statement, keeping it at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the UNESCO World Heritage List by keyword, country, category (Cultural, Natural, Mixed), region, inscription criteria (i)–(x), inscription year range, Danger-list status, transboundary status, or distance from a point. Every keyword must appear at the start of a word in a site's name (any of six languages), description, or statement of Outstanding Universal Value, and name matches rank first. A country is an ISO 3166-1 alpha-2 or alpha-3 code and matches every site it shares, transboundary sites included. Set in_danger to true for the List of World Heritage in Danger; the data records the year of each site's current Danger-list entry but no threat factors. Criterion (vi) is inferred from each site's statement of Outstanding Universal Value and marked as inferred. Results page with next_cursor and carry facet counts over the whole match.
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Only sites within radius_km of this point: a site matches when its representative point or any of its components lies within the radius, and a site with neither never matches. distance_km and the distance sort use the nearest of those points. | |
| sort | No | Result order. Default: relevance when query is set, else distance when near is set, else name. relevance needs query; distance needs near. Absent areas and Danger years sort last. | |
| limit | No | Maximum results per page (1–50, default 20). | |
| query | No | Keywords; every word must match the start of a word in a site's name (any of six languages), description, or statement of Outstanding Universal Value. Case, accents, and punctuation are ignored, so the query must contain at least one letter or digit and at most 16 distinct words; no phrases, operators, or fuzzy matching. | |
| cursor | No | Opaque continuation cursor from the previous call's next_cursor. Pass it with the same filters and sort to fetch the next page. | |
| region | No | UNESCO region: Africa, Arab States, Asia and the Pacific, Europe and North America, or Latin America and the Caribbean (codes AFR, ARB, APA, EUR, LAC accepted). | |
| country | No | ISO 3166-1 alpha-2 or alpha-3 code, any case (FR, FRA). Matches every site the country takes part in, transboundary sites included. For a country name, look up its code with unesco_list_reference (topic countries). | |
| category | No | Site category: Cultural, Natural, or Mixed. | |
| criteria | No | Inscription criteria a site must all carry. (i) A masterpiece of human creative genius. (ii) An important interchange of human values over time or within a cultural area, in architecture, technology, monumental arts, town planning, or landscape design. (iii) A unique or exceptional testimony to a cultural tradition or a civilization, living or vanished. (iv) An outstanding example of a type of building, architectural or technological ensemble, or landscape illustrating significant stages in human history. (v) An outstanding example of traditional human settlement, land use, or sea use representative of a culture or of human interaction with the environment, especially where vulnerable to irreversible change. (vi) Direct association with events, living traditions, ideas, beliefs, or artistic and literary works of outstanding universal significance. (vii) Superlative natural phenomena, or areas of exceptional natural beauty and aesthetic importance. (viii) An outstanding example of a major stage of Earth's history, including the record of life, significant ongoing geological processes, or significant landforms. (ix) An outstanding example of significant ongoing ecological and biological processes in the evolution of ecosystems and communities of plants and animals. (x) The most important natural habitats for in-situ conservation of biological diversity, including those holding threatened species of outstanding universal value. Criterion (vi) is inferred from the statement of Outstanding Universal Value, since UNESCO's criteria fields omit it. | |
| in_danger | No | true: only sites on the List of World Heritage in Danger. false: only sites not on it. Omit for both. | |
| inscribed_to | No | Latest inscription year, inclusive. | |
| transboundary | No | true: only sites shared by more than one State Party. false: only single-State sites. | |
| inscribed_from | No | Earliest inscription year, inclusive. | |
| include_description | No | Set false to leave each row's description out of the response (default true); unesco_get_site returns it. Which sites match, their order, and matched_in are unchanged. |
| Name | Required | Description |
|---|---|---|
| cap | No | The page size (limit) that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results on this page. |
| sites | No | Matching sites on this page. |
| facets | No | Facet counts over the whole match, not just this page. |
| notice | No | Guidance on the result: why nothing matched, caveats, or how to continue paging. |
| sources | No | Datasets this response was built from. |
| truncated | No | True when more results remain beyond this page. |
| totalCount | No | Total matches across all pages. |
| next_cursor | No | Pass as cursor, with the same filters and sort, to fetch the next page. Present when more results remain. |
| applied_filters | No | The filters and sort as the server applied them. |
| descriptions_omitted | No | Present when include_description is false: no row carries its description, which unesco_get_site returns. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far beyond the readOnly/openWorld/idempotent annotations, it discloses keyword matching rules (word-start match across name/description/OUV, name matches rank first), that country codes match transboundary sites too, that Danger-list records only the entry year and no threat factors, and that criterion (vi) is inferred and flagged.
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 facet inventory and paginated-result behavior, and every sentence carries information. It is a dense single block rather than a structured list, which slightly hurts scannability for 14 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering the safety profile, the description fills the remaining gaps: matching semantics, ranking, the inferred criterion (vi), the Danger-year limitation, and cursor-based paging with whole-match facet counts.
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 each parameter thoroughly. The description reinforces cross-cutting semantics (country code matching, criterion (vi) inference) but adds little parameter-level detail beyond what the schema provides, matching the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (Search) and resource (UNESCO World Heritage List) and enumerates the exact facets that can be filtered, so an agent can immediately distinguish it from the sibling search tools for biosphere reserves, geoparks, and intangible heritage.
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 facet list and the mention that name matches rank first make the tool's role clear, and the schema points to unesco_get_site and unesco_list_reference for adjacent needs. However, the description itself never states explicit when-to-use/when-not conditions versus those siblings.
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.
unesco_get_biosphere_reserveunesco_get_geoparkunesco_get_intangible_heritage_elementunesco_get_siteunesco_list_referenceunesco_search_biosphere_reservesunesco_search_geoparksunesco_search_intangible_heritageunesco_search_sitesRead-only MCP for heritage travel: search 500+ UNESCO destinations by region and intent.
Read-only OpenHeritage search for genealogy and cultural heritage records.
Search GBIF species taxonomy, occurrence records, datasets, and publishers.
Search GBIF species taxonomy, occurrence records, datasets, and publishers.
Add one secure layer between your agents and this server.
