citiesPublished city readings ranked by price (EUR). Optionally filter by country code or by a substring of the city name.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Case-insensitive substring of the city name | |
| country | No | ISO 3166-1 alpha-2 country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does state the core behavior: it returns published city readings sorted by EUR price and supports optional filters. It stops short of mentioning read-only status, pagination or result limits, or the exact response shape, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the resource, the ranking basis, the currency, and the available filters with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional, fully documented parameters, the description provides enough context to know when to call it and what it returns: a price-ranked list of city readings. It omits minor details such as pagination or exact output fields, but these are not blockers for a low-complexity lookup 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%, so the schema already documents both parameters. The description only paraphrases the filters ('country code', 'substring of the city name') and adds no additional format, combination, or default behavior beyond what the schema provides.
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 resource ('published city readings') and a distinct behavior (ranked by price in EUR), with optional filters. It is clear but does not explicitly distinguish itself from sibling tools such as compare or country_index.
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 conveys that this tool is for city-level readings sorted by price and explains how to narrow results by country or city-name substring. It does not, however, provide any when-to-use/when-not-to-use guidance relative to the listed sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct geographic level or analytical view, but compare and country_index can both return country-level price rankings, so an agent may need to read the descriptions carefully to choose correctly. Overall, the boundaries are clear enough for most queries.
Names are consistently lowercase snake_case and mostly noun phrases describing the returned view, but compare stands out as a standalone verb. The pattern is still readable and predictable.
Five tools is well-scoped for a focused data retrieval server. Each tool provides a distinct view—overview, countries, cities, subdivisions, and comparisons—without unnecessary redundancy.
The set covers the full read-only surface of The Omelette Index: global statistics, country rankings and details, city readings with filters, subdivisions by country, and country comparisons. There are no obvious dead ends for typical lookup workflows.