Invokely official statistics

Rank places

rank_places

Read-onlyIdempotent

Rank every place of one level inside an area by an indicator: all countries of the world, EU countries, US states, the counties or cities of a state, US cities, the regions of a country, the municipalities of a Spanish province. Use it for "which state has the highest unemployment", "top 10 countries by GDP per capita", "poorest counties in Texas", "EU countries with the lowest inflation". level is the level of the ranked places (country, region, province, municipality); within is the area they belong to. US states are regions of "United States"; US counties are provinces of a state; US cities are municipalities of "United States" or of a state; EU NUTS 2 regions are regions of "EU" or of a country. Example: {"indicator": "unemployment_rate", "level": "region", "within": "United States", "limit": 5}. Countries of the world: {"indicator": "population", "level": "country"}. Returns {indicator, level, within, period, comparable, order, total, values: [{rank, place, value, status?}], source, notes?}. Every value comes from one source and one period. order "asc" lists the lowest first. Cite source.citation. For rates across municipalities pass min_population (for example 5000) so very small places, where a few people move the rate, do not top the list. transform ranks a calculated figure: per_capita, per_1000 or per_100k for totals (population from one series for every place), yoy or yoy_diff for change from a year earlier. Example: {"indicator": "gdp_usd", "level": "region", "within": "United States", "transform": "per_capita"}. Each value lists its inputs; places without an input are left out and counted in notes.

Input Schema

Name	Required	Description
`level`	Yes	Level of the places ranked.
`limit`	No	Optional. Rows to return, 10 by default.
`order`	No	Optional. desc (highest first, default) or asc.
`period`	No	Optional. "2024" (year), "2024-Q3" (quarter), "2024-S1" (half year) or "2024-09" (month). Omit for the latest value.
`within`	No	Optional area that contains the ranked places, for example "United States", "EU", "Germany", "Texas", "Cataluña". Omit to rank all countries.
`country`	No	Optional ISO 3166-1 alpha-2 code to disambiguate the place, for example "ES" or "US".
`indicator`	Yes	Indicator id from search_indicators, for example "population", "registered_unemployment_rate", "unemployment_rate", "cpi_annual_change", "net_income_per_person".
`transform`	No	Optional. per_capita, per_1000, per_100k (totals only) or yoy, yoy_diff. See get_value.
`citation_style`	No	Optional. Adds source.citations with the citation in this style (APA 7, MLA 9, Chicago author-date, Harvard, BibTeX or RIS), or in all six with "all". The publisher is the author. Leave it out to keep the response short.
`min_population`	No	Optional. Leave out places with fewer residents.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 12, 2026

addedInput schema / properties / citation_style

Added value: +{
+  "description": "Optional. Adds source.citations with the citation in this style (APA 7, MLA 9, Chicago author-date, Harvard, BibTeX or RIS), or in all six with \"all\". The publisher is the author. Leave it out to keep the response short.",
+  "enum": [
+    "apa",
+    "mla",
+    "chicago",
+    "harvard",
+    "bibtex",
+    "ris",
+    "all"
+  ],
+  "type": "string"
+}

addedInput schema / properties / transform

Added value: +{
+  "description": "Optional. per_capita, per_1000, per_100k (totals only) or yoy, yoy_diff. See get_value.",
+  "enum": [
+    "per_capita",
+    "per_1000",
+    "per_100k",
+    "yoy",
+    "yoy_diff"
+  ],
+  "type": "string"
+}

First observedOct 11, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial behavior: return shape, the guarantee that every value comes from one source and one period, order semantics, the min_population caveat about small places, and the rule that places lacking inputs are dropped and counted in notes.

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

Conciseness4/5

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

Front-loaded with purpose and use cases, then progressively deeper detail; information density is high and few sentences are wasted. It is long, but the length is justified by 10 parameters and the level/within grammar that needs explaining.

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

Completeness5/5

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

Despite having no output schema, the description documents the response envelope, the source/period guarantee, and the notes field. Combined with 100% schema coverage, an agent has everything needed to call and interpret the tool correctly.

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

Parameters4/5

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

Schema coverage is 100% (baseline 3), but the description adds real semantic value the schema lacks: the interaction between level and within (US states are regions of 'United States', US cities are municipalities of a state), the rationale for min_population, and worked examples for transform and limit.

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

Purpose5/5

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

The description states a specific verb (rank) plus resource (places) and precisely scopes it: 'every place of one level inside an area by an indicator'. It enumerates the exact level/area combinations, making it clearly distinguishable from siblings like get_value or compare.

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

Usage Guidelines4/5

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

It gives concrete triggering questions ('which state has the highest unemployment', 'top 10 countries by GDP per capita') and explains the level/within grammar needed to select the right scope. It never names an alternative sibling tool or states when-not-to-use, so it stops short of full routing guidance.

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

All Invokely official statistics tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?