worldbank-mcp-server

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already cover safety and idempotency. Description adds valuable behavioral context: accepted code formats (ISO2, ISO3, aggregate codes). No contradictions. Could mention error handling for invalid codes, but acceptable given annotations.

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

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

Two sentences: first defines purpose and output, second lists accepted codes and references sibling. No fluff, front-loaded key info.

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 1 parameter, 100% schema coverage, existing output schema, and rich annotations, the description fully covers the tool's purpose and input requirements. No missing information for typical usage.

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 covers 100% of the single parameter with details on accepted code types. The description mostly repeats this (ISO2, ISO3, aggregate codes) and adds guidance to use worldbank_list_countries. Baseline 3; minor added value 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?

Description clearly states it fetches full metadata for a specific country or aggregate entity, listing specific fields (region, income level, capital, coordinates, lending type). Differentiates from siblings like worldbank_get_data (data queries) and worldbank_list_countries (listing) by explicitly referencing worldbank_list_countries for browsing codes.

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?

Description states when to use: to fetch metadata for a country/aggregate. It hints at alternatives by mentioning worldbank_list_countries for browsing valid codes. Could be more explicit about not using it for data or indicators, but context signals and sibling names provide sufficient guidance.

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

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

Annotations already cover readOnly, idempotent, and openWorld traits. The description adds meaningful behavioral context: nulls for sparse data, mutual exclusivity of date_range/mrv, and the note that the API returns several hundred entries per indicator, which helps the agent set expectations beyond the annotation hints.

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?

Four tightly-written sentences front-load the core purpose and then add essential behavioral notes. No fluff, no repetition, highly efficient.

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 rich schema, output schema, and annotations, the description covers the key edge cases (null values, pagination, date_range/mrv conflict) and is complete for its complexity. The output schema handles return-value documentation, so no need to describe that in text.

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 a baseline of 3 applies. The description adds practical parameter guidance—pagination for 'all' countries, per_page hints, and mutual exclusivity—complementing the already detailed 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 the tool 'Queries World Bank indicator values for one or more countries across a time range.' The verb 'queries' and the resource 'indicator values' are specific, and calling it 'the primary data-access tool' distinguishes it from sibling tools like worldbank_get_country or worldbank_search_indicators.

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 names worldbank_search_indicators as the way to find indicator_id values, and provides key usage constraints (date_range vs mrv exclusivity, pagination for 'all' countries). It doesn't fully contrast with other data-related siblings like worldbank_get_indicator, so it's not 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. The description adds value by enumerating the metadata fields returned (name, description, source, etc.). It does 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?

Two sentences, front-loaded with the core purpose, and no unnecessary words. 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?

Given the single parameter, rich annotations, and existence of an output schema, the description is fully adequate. It explains what the tool does, what it returns, and how to find valid inputs.

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 a clear description for the single parameter. The tool description echoes the guidance to use search, adding no new semantic information 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 action ('fetches complete metadata'), the resource ('single World Bank indicator'), and the specific data fields returned. It also distinguishes from the sibling tool worldbank_search_indicators by advising when to use that alternative.

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 explicit guidance: use worldbank_search_indicators to discover indicator IDs if only the concept is known. This tells the agent when to use this tool and when to switch to a sibling.

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, and the description adds valuable behavioral context: it discloses that gap-filled rows (interpolation, extrapolation, CMD estimation) have null inequality fields, calls this a 'documented gap in the source data, not an error', and explains the behavior of fill_gaps and welfare_type (e.g., thirty-five economies returning two rows per year). No contradictions with annotations.

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

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

The description is long but highly structured and information-dense. Every sentence adds unique value: main function, outputs, sibling differentiation, dataset limitations, estimation-type behavior, and null-data explanation. It is front-loaded with the core purpose and does not waste words on 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?

Given the tool's complexity (8 parameters, output schema, multiple estimation types), the description is remarkably complete. It covers when to use, what is returned, data coverage (individual economies only), gap-filling behavior, null handling, and parameter constraints (e.g., welfare_type splits). The presence of an output schema reduces the need to detail return shapes, but the description still explains key output characteristics.

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

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

Schema description coverage is 100%, so baseline is 3. The description itself does not repeat or add parameter-level semantics beyond the schema, but it provides useful context in the narrative (e.g., PPP dollars, poverty line not affecting inequality fields). The schema already carries full parameter descriptions, so the description adds no significant extra meaning.

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 specifies the tool as querying poverty and inequality estimates from the World Bank PIP, lists concrete outputs (headcount ratio, gap, severity, Gini, decile shares), and explicitly distinguishes it from the sibling worldbank_get_data by stating it is a separate dataset. The verb 'Queries' and resource 'World Bank Poverty and Inequality Platform' are specific and match the tool's name, making the 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 clearly states when to use this tool vs alternatives: it says PIP is a separate dataset from the WDI series worldbank_get_data reads, and notes that regional/income-group aggregates are not accepted. It also positions it as 'the tool for inequality and distribution questions'. This provides explicit context and exclusions, exceeding simple implied usage.

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?

No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint). Adds valuable context about default behavior (excluding aggregates) and parameter effects (include_aggregates). Annotations already cover safety; description enhances transparency.

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

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

Three sentences, front-loaded with purpose, and each sentence adds essential information without fluff. Efficiently covers key filtering options and default behavior.

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

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

Covers the main use cases with filtering and default behavior. Pagination is implicitly covered by parameters. Since an output schema exists, the description does not need to detail return fields. Minor gap: no mention of rate limits or further pagination details, but overall sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the effect of 'include_aggregates' and listing valid codes for region and income_level, which is helpful beyond the schema's 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 explicitly states 'Lists countries and regional aggregates with metadata' and lists specific fields (ISO codes, region, income level, capital, coordinates). It distinguishes from sibling tools by mentioning filterable parameters and default behavior.

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?

Clearly explains how to filter by region and income level, and includes the important default exclusion of aggregates with the option to include them. Does not explicitly state when not to use this tool, but sibling tools have distinct purposes.

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 adds value by stating that it lists over 70 sources, returns IDs and names, and supports pagination, complementing the annotations without contradicting them.

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

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

Three sentences: first introduces the core action and examples, second explains output and purpose, third notes pagination. Every sentence adds necessary information, no 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?

The description is complete for this simple tool: it explains what is listed, the output's purpose, and pagination. With the output schema provided and strong annotations, no further context is needed.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'Supports pagination' but does not add meaning beyond the schema's parameter descriptions. Thus, it meets the baseline but does not exceed 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?

The description clearly states the verb 'Lists' and the resource 'World Bank data sources', provides concrete examples (e.g., World Development Indicators), and explains the returned fields (IDs and names) and their usage in the sibling tool worldbank_search_indicators, effectively distinguishing it from 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 indicates that the tool is used to obtain source IDs for subsequent use in worldbank_search_indicators, providing clear workflow context. However, it does not explicitly mention when not to use it or compare with other sibling tools, so it falls short of a perfect score.

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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds value by specifying the exact count (21) and that topics come with descriptions, going beyond annotations.

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

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

Two concise sentences, front-loaded with the main action, 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 no parameters and output schema exists, description is complete, explaining the tool's purpose and how it feeds into a sibling 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?

No parameters; schema coverage is 100%. Description does not need to add parameter details. Baseline for 0 params is 4.

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 clearly states 'Lists all 21 World Bank thematic topics', providing specific verb and resource, and distinguishes from siblings by mentioning use in finding topic_id for worldbank_search_indicators.

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

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

Explicitly says 'Use to browse the indicator space or find a topic_id for worldbank_search_indicators', giving clear context and referencing a sibling tool as an alternative.

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 indicate read-only, open-world, idempotent behavior. The description goes beyond by detailing match semantics (every term must match, punctuation ignored), ranking order (exact ID/name > phrase > ID/name > description), and deduplication across sources. These are valuable behavioral traits not visible 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?

Every sentence adds unique value: scope, return purpose, prerequisite, search behavior, ranking, deduplication, and helper-tool references. Information-dense but well-organized, front-loaded with the primary 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?

With an output schema present, return-value explanation is unnecessary. The description covers all operational aspects: queries, filters, matching semantics, ordering, deduplication, and parameter prerequisites. A complete picture for successful 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 descriptions cover 100% of parameters, so baseline is 3. The description adds critical semantic context: the 'at least one' requirement, matching rules, and how topic_id/source_id interact with query. This enhances parameter understanding beyond the schema's individual field definitions.

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?

Clear verb+resource+scope: 'Searches the 29,500+ World Bank indicator catalog by keyword, topic, or source.' Distinct from siblings like worldbank_get_data (fetching data) and worldbank_list_topics (listing topics). States purpose precisely.

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

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

Explicitly states the mandatory constraint ('At least one of query, topic_id, or source_id must be provided') and names alternatives for acquiring filter IDs ('Use worldbank_list_topics... worldbank_list_sources...'). Also mentions chaining into worldbank_get_data, clarifying when this tool fits a workflow.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds substantial context beyond that: filters combine by AND, every filter is exact-match upstream, the response behavior on empty results, and the ISO2/ISO3 divergence with cross-reference to worldbank_get_country. This exceeds what annotations alone provide.

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 front-loaded with the core purpose, uses concrete examples and clear alternatives, and each sentence earns its place. Though longer than average, the tool's complexity (9 params, code quirks, AND semantics, sibling distinctions) justifies the length, and the structure is logical and scannable.

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 9 parameters, no required fields, and an output schema, the description covers purpose, usage, behavioral quirks, and parameter semantics. It leaves no critical gap, addressing edge cases like ISO2 vs ISO3, regional codes, AND combination, and empty results—making it fully comprehensive.

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 covers 100% of parameters, so the baseline is 3. The description adds cross-cutting semantics not in the schema: country codes use ISO2 (not ISO3), multi-country operations use regional codes, and the region values differ from WDI aggregate codes. This enriches parameter understanding without repeating schema content.

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 the World Bank lending portfolio' by specific filters (free text, country, region, status, board approval date) and lists return fields. It explicitly distinguishes from the statistics catalogue and names sibling tools for that purpose, making the 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?

Provides explicit when-to-use examples ('use it for...'), contrasts with worldbank_search_indicators and worldbank_get_data for statistics, and gives practical guidance on omitting status (returns mostly historical operations) and empty search results. This is rich, actionable usage guidance.

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