worldbank-mcp-server

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

Annotations already declare the tool as read-only and idempotent. The description adds behavioral context by specifying the accepted code formats (ISO2, ISO3, aggregates) and the list of metadata fields returned, which are not specified in annotations. This informs the agent about acceptable inputs and expected output content.

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 no filler. The first sentence states the action and outputs, the second clarifies input formats. Information is front-loaded and every word contributes.

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 single-parameter lookup tool with annotations covering safety and a full output schema, the description is complete. It specifies accepted inputs, lists the fields returned, and is consistent with the read-only nature. Nothing an agent needs 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?

The input schema description already fully documents the parameter, including accepted code types and a pointer to browse valid codes. The description repeats these code types without adding new information, providing no additional semantic 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 verb 'fetches' and the resource 'full metadata for a specific country or aggregate entity', listing the types of data returned (region, income level, capital, coordinates, lending type). This distinguishes it from sibling tools that handle time-series data or search operations.

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

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

The description implies usage for fetching country metadata but does not explicitly contrast with alternatives like worldbank_get_data or worldbank_search_indicators. It mentions accepted code formats, but does not directly state when to use this tool versus others. The schema suggests using worldbank_list_countries to browse codes, but that is not in the description.

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

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

Annotations already cover read-only, open-world, and idempotent hints. The description goes beyond by disclosing that observations may contain null values for sparse country-year cells, and explains pagination behavior for 'all' queries. It also details the mutual exclusivity of date_range and mrv. These behavioral insights are valuable and do not contradict annotations.

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

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

The description is compact, about four sentences, with the primary purpose stated first. It front-loads the core action, then delivers essential caveats (nulls, exclusivity, pagination) in a logical sequence. 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 the rich schema, output schema presence, and annotation coverage, the description sufficiently covers all necessary information for an agent to call the tool correctly. It addresses the main use case, edge cases with nulls, parameter exclusivity, and pagination, leaving no obvious gaps.

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 provides 100% coverage with detailed descriptions for every parameter, including accepted formats, mutual exclusivity, and pagination semantics. The description adds minimal extra parameter meaning beyond reinforcing the null-value behavior and the note about pagination for 'all', but does not provide significant new per-parameter insight 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's function: 'Queries World Bank indicator values for one or more countries across a time range.' It identifies itself as the primary data-access tool and explicitly points to worldbank_search_indicators for finding indicator IDs, distinguishing it from the search sibling. The wording is specific and 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?

It provides explicit guidance on when to use this tool (primary data access) and names the alternative (worldbank_search_indicators) for finding IDs. It also explains the mutual exclusivity of date_range and mrv, and advises pagination for 'all' country queries. While it doesn't enumerate exclusions between other siblings, the context is sufficient for appropriate selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral detail about what data is returned (the full metadata list) and does not contradict the annotations. It provides enough transparency for a read-only metadata lookup.

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 with no redundancy. The first sentence states the purpose and outputs, the second gives routing guidance. Every word earns its place, and the key action is 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?

For a single-parameter read-only lookup with an output schema, the description covers purpose, usage, routing, and return contents. It even guides the agent to the search tool for ID discovery. Nothing essential is missing 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?

Schema description coverage is 100%, and the schema already explains the indicator_id format with examples and directs to worldbank_search_indicators for invalid IDs. The description reinforces this but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate given the high coverage.

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 explicitly states the verb 'Fetches' and the resource 'complete metadata for a single World Bank indicator by its ID', then enumerates the exact fields returned (name, description, source dataset, source organization, unit, thematic topics). It clearly differentiates from sibling tools like worldbank_search_indicators by focusing on a single known ID.

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 explicit usage guidance: 'Use worldbank_search_indicators to discover indicator IDs if you only know the concept.' This tells the agent when to use this tool (when an ID is already known) and when to use the alternative, leaving no ambiguity about tool selection.

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

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

Annotations already declare readOnly, openWorld, and idempotent, so the description builds on that. It discloses crucial behavioral traits: estimationType distinctions (survey vs interpolation/extrapolation/CMD), null gini/mld/polarization/decileShares for gap-filled rows, fill_gaps fallback behavior, welfare_type non-comparability and double-row cases for 35 economies, reporting_level splits for 10 economies, and the poverty_line echoing as povertyLine. This goes far beyond the annotation hints and prevents misinterpretation of null values.

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 single dense paragraph, long but front-loaded with the core purpose and then systematically covering dataset distinction, behavioral notes, and field semantics. Every sentence earns its place; it is redundant only in a minor way (e.g., 'Every row reports how it was produced' is repeated by the estimationType explanation). The density is justified by the tool's complexity, though some agents may benefit from bullet points.

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 an 8-parameter tool with a rich output schema, this description covers the essentials: dataset provenance, field semantics, estimation-type behavior, null handling, coverage period, and parameter-specific quirks. It leaves nothing that an agent needs to know for correct selection and invocation. The presence of an output schema means return structure is not its responsibility. It is complete for both routing and use.

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 100% schema coverage, the description adds substantial meaning. It explains the countries parameter's rejection of aggregate codes with examples (WLD, SSF, HIC), the fill_gaps toggle's consequence on row presence, welfare_type's comparability caveat and multi-row behavior, reporting_level's specific split counts, and poverty_line's independence from inequality fields. These details are not in the schema and materially improve correct usage.

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: 'Queries poverty and inequality estimates from the World Bank Poverty and Inequality Platform (PIP) for one or more countries.' It then enumerates the exact metrics returned (headcount ratio, poverty gap, severity, mean/median welfare, population) and explicitly separates itself from the WDI dataset via worldbank_get_data, making the tool uniquely identifiable among 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 explicitly contrasts with worldbank_get_data ('PIP is a separate dataset from the WDI series worldbank_get_data reads') and frames itself as 'the tool for inequality and distribution questions.' It also gives a clear exclusion: regional and income-group aggregate codes are not accepted, guiding agents to query individual economies instead. This is proactive routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds value by disclosing the default filtering behavior (excludes aggregates) and the optional inclusion of aggregate entities, which is not fully captured by annotations. It also specifies the metadata fields returned, giving the agent a clearer picture of the output. No contradiction 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 two concise sentences: the first establishes the tool's purpose and content, and the second explains the default and the flag to change it. There is no redundancy, and the most important information (what it lists and the default) is front-loaded. Every sentence earns its place.

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

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

With a full input schema and an output schema present, the description does not need to detail return formats. It adequately covers the core behavior (listing, filtering, aggregate control) and aligns with the annotations. An agent can correctly invoke the tool for a listing task without missing essential information, given the schema and annotations cover the rest.

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 all five parameters are documented in the schema with meaning. The description restates the filters and include_aggregates, but adds no new semantic nuance beyond what the schema already provides (e.g., it does not explain interaction effects or pagination behavior). Given the schema's thoroughness, the description adds minimal extra value, aligning with the baseline of 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?

The description states a specific verb ('Lists') and a clear resource ('countries and regional aggregates'), and enumerates the metadata included (ISO codes, region, income level, capital, coordinates). It distinguishes itself from siblings like worldbank_get_country by focusing on listing, while also clarifying the default exclusion of aggregates. This is unambiguous and directly informative.

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 clear context on when to use the tool (to list countries) and explains the default behavior (individual countries only) and how to opt into aggregates (include_aggregates=true). However, it does not explicitly mention alternative tools or state when not to use it, such as when a specific country is needed. Thus it meets the 'clear context, no exclusions' bar but stops short of explicit alternative routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds value by noting the tool returns source IDs and names and supports pagination, which are behavioral details beyond the annotations. No contradiction exists, and the added context is helpful for the agent to know what to expect.

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 with no fluff. The primary purpose is front-loaded ('Lists the 70+ World Bank data sources'), followed by the return content and the pagination note. Every phrase earns its place, making it highly scannable for an agent.

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, existing output schema (indicated by context), and comprehensive annotations covering safety, the description covers all necessary context. It states the resource, the output fields, the downstream usage, and pagination. No critical information is missing for an agent to correctly select and invoke this 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 100%: both 'page' and 'per_page' have descriptive comments (pagination number and results per page, with defaults and max). The description only repeats 'supports pagination' which adds no meaning beyond the schema. Per the baseline, when the schema is sufficiently descriptive, the description does not need to add parameter details.

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 identifies the exact resource (World Bank data sources) and the verb 'lists', names specific examples (WDI, IDS, Doing Business), and states the output is source IDs and names. Critically, it differentiates its purpose by explicitly targeting use as source_id in worldbank_search_indicators, distinguishing it from sibling list tools like worldbank_list_countries and worldbank_list_topics.

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 states when to use the tool: 'for use as source_id in worldbank_search_indicators', which tells the agent this is a preparatory step before searching indicators. However, it does not explicitly mention when not to use it or contrast with alternatives, so it lacks a full exclusionary statement. The intended usage is clear but not exhaustively defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds minor useful context such as the exact count (21) and the fact that descriptions are included, but discloses no additional behavioral traits (e.g., pagination, sorting). Since the annotations carry the safety profile, this is acceptable but not exceptional.

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, front-loaded with the main action ('Lists all 21...') immediately. The second sentence adds a use case without redundancy. Every word earns its place; no fluff or repetition.

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 operation with no parameters, an existing output schema (so return format is not needed), and annotations covering safety, the description is complete. It states what the tool returns (topics with descriptions), the count, and the practical use case. Nothing an agent needs 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?

The tool has zero parameters and schema coverage is 100% (the schema has an empty properties object). Per the rubric, a 0-parameter tool gets a baseline of 4. The description adds nothing about parameters because there are none, which is correct. No further param info is 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 action ('Lists') and the resource ('World Bank thematic topics') with a specific scope ('all 21'). It also gives examples of the content ('Economy & Growth, Health, Education, etc. with descriptions'). This distinguishes it from sibling tools like worldbank_list_countries or worldbank_search_indicators, as it is specifically about the topic list.

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 explicit guidance: 'Use to browse the indicator space or find a topic_id for worldbank_search_indicators.' This tells the agent when to invoke it. However, it does not explicitly state when not to use it or name alternative tools for other scenarios, though the reference to worldbank_search_indicators implies a downstream alternative. A fully explicit exclusion would earn a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description goes well beyond by detailing the matching algorithm (every term must match, punctuation ignored), the ranking order (exact ID/name, phrase, etc.), and deduplication behavior (each indicator ID appears once). This provides valuable behavioral context not available in annotations or schema.

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

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

The description is dense but well-organized: first sentence states purpose and return, second states the constraint, then matching behavior, then dedup, and finally references to companion tools. Every sentence contributes new information; there is no fluff or redundancy.

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

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

For a search tool with multiple filters and ranking logic, the description covers all necessary aspects: what it returns, how matching works, ranking, deduplication, the minimum filter requirement, and how to obtain valid filter values. Given an output schema exists for return format, the description is sufficiently complete for an agent 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 coverage is 100% with parameter descriptions, but the tool description adds significant meaning by explaining how the query parameter matches terms across ID, name, and description, and how topic_id/source_id act as filters with references to list tools. It also clarifies the 'at least one' constraint, which the schema doesn't enforce as required fields.

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 ('Searches') and resource ('the 29,500+ World Bank indicator catalog'), and immediately differentiates from siblings like worldbank_search_projects by specifying keyword, topic, or source filters. It also states the return value and its downstream use ('chaining into worldbank_get_data'), making the tool's 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?

It explicitly states the precondition 'At least one of query, topic_id, or source_id must be provided' and directs users to worldbank_list_topics and worldbank_list_sources for valid IDs. The mention of chaining into worldbank_get_data clearly implies this is the search step before data retrieval, and the distinction from other search tools is clear from context.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes far beyond that by explaining that filters are exact matches combined with AND, that narrow searches can legitimately return nothing, and that the response reports whether country codes matched on their own. It also details ISO2 vs. ISO3 handling, regional codes for multi-country operations, and the lifecycle stage definitions (Active, Pipeline, Closed, Dropped) — all behavioral nuances an agent needs to interpret results correctly.

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 every sentence earns its place. It is front-loaded with the core purpose, then systematically covers disambiguation, filter semantics, parameter nuance, and edge-case behavior. There is no filler or repetition, and the structure flows logically from 'what' to 'how' to 'when not to use it'.

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 9-parameter search tool with an output schema, the description is remarkably complete. It covers return fields, filter combination logic, country code conventions, regional codes, status definitions, date semantics, pagination hints, and the special behavior of include_abstract. It also anticipates likely mistakes (ISO2 vs ISO3, regional codes, empty results) and addresses them inline. Even with an output schema present, the description preempts most practical ambiguities an agent could face.

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?

Even though schema description coverage is 100%, the description adds substantial meaning not present in the schema. It clarifies that 'region' uses operational lending regions rather than WDI aggregate codes, that 'countries' accepts ISO2 or regional codes with OR semantics, that 'approved_from/to' are inclusive dates and that board approval date is the commitment date (with pipeline projects carrying a scheduled future date). It also explains the size and appropriate usage of 'include_abstract', which is exactly the kind of pragmatic parameter guidance agents need.

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

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

The description states a specific verb ('searches') and a precise resource (the World Bank lending portfolio), enumerates the filter dimensions and the returned fields, and explicitly contrasts it with the statistics catalogue. It names sibling tools (worldbank_search_indicators, worldbank_get_data) that serve different purposes, making it unmistakable which tool to pick.

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 gives explicit when-to-use guidance with concrete example queries ('what is the World Bank funding in Kenya', 'which climate adaptation projects are active') and explicitly routes users to worldbank_search_indicators/worldbank_get_data for statistics and time series. It also flags the ISO2/ISO3 departure, which is a critical operational detail for this server.

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