The Omelette Index

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that results are side-by-side and ranked in EUR, which is useful context. However, it does not specify sort direction, response structure, data source, or error 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?

One sentence with no filler, front-loading the core comparison purpose and then stating the ranking rule. Every element 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?

There is no output schema and no annotations, so the description must explain return behavior. It covers side-by-side presentation and EUR pricing but leaves sort direction and response structure ambiguous. For a simple single-parameter tool this is near adequate but not fully complete.

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 for the only parameter is 100%, already documenting ISO 3166-1 alpha-2 country codes with min/max constraints. The description adds conceptual context about readings but does not contribute parameter-level meaning 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 concrete outcome: 'Side-by-side omelette index readings for two or more countries, ranked by price in EUR.' It clearly distinguishes this multi-country comparison tool from single-country siblings like 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 phrase 'for two or more countries' implies the tool is for comparing multiple countries, but there is no explicit statement of when not to use it or which sibling tool to use instead for a single country. Usage guidance is inferable rather than stated.

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?

There are no annotations, so the description carries the burden. It usefully discloses that prices are in EUR, use a trimmed median, only published countries appear, and the behavior changes with the optional argument. However, 'full reading' is vague about what fields, ordering, or format the response contains, and no error behavior is mentioned.

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 filler: the first states the resource and scope, the second explains the no-arg and with-arg behaviors. It is front-loaded and every clause 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?

For a simple one-optional-parameter lookup the description covers the main call patterns, but without an output schema it leaves 'full reading' unspecified and does not clarify response shape, sorting direction, or invalid-input behavior. It also lacks any comparison to sibling tools, which would help agents select this over cities or compare.

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 schema already fully documents the single country parameter with ISO alpha-2 constraints and examples. The description adds the contextual meaning that providing the country selects that country's full reading, which is helpful but does not go beyond the schema's documented purpose.

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 identifies the tool as the omelette price index by country and differentiates the two call modes: no-argument returns a ranked list of all published countries, while a country argument returns that country's full reading. It does not explicitly contrast itself with sibling tools such as cities or compare, so it stops short of full differentiation.

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 direct conditional usage guidance: invoke with no arguments for the full country ranking and with a country code for a single country's reading. It does not mention when not to use this tool or point to alternatives like compare or index_overview.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool returns descriptive statistics and lists the specific outputs, making the read-only, aggregate nature clear. It does not address formatting or edge cases, but for a zero-parameter overview tool this is reasonably transparent.

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, compact sentence that front-loads the tool's purpose ('Descriptive statistics for The Omelette Index') and then lists the concrete values returned. Every phrase adds useful information, and there is no redundancy or 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 low complexity, empty input schema, and no output schema, the description provides enough detail for an agent to understand what will be returned. It conveys the dataset scope, the included statistics, and even the currency unit (EUR). The only minor gap is the lack of detail about the response format, but this is not critical for a no-input overview 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?

The tool has zero parameters, so the baseline is 4. The input schema is empty and complete, and the description adds no parameter-specific detail because none is needed. The description focuses on what the overview returns rather than inputs, which is appropriate here.

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 identifies this as a dataset-level overview tool with a specific resource ('The Omelette Index') and enumerates the exact statistics it provides, such as counts of places, published countries/subdivisions/cities, global price centre, and dearest/cheapest countries. This scope distinguishes it from the sibling tools, which target specific geographical or comparison views.

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 this tool is for obtaining a high-level dataset summary, but it does not explicitly state when to use it instead of siblings like cities, compare, country_index, or subdivisions. There are no direct alternative references or exclusion criteria, so usage guidance is only implicit.

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?

With no annotations, the description must carry the behavioral disclosure burden. It does disclose key behavior: returned readings are ranked by price and each subdivision is compared to its country via vsCountryPct. However, it does not explain the sort direction, data freshness, pagination, or any access constraints, leaving important behavior undeclared.

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 compact sentence with no filler, front-loading the core idea of subdivision readings before adding ranking and comparison details. Minor awkwardness from the passive 'Published' phrasing keeps it from a perfect score.

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 one-parameter read-only list tool with a fully documented schema, the description covers the key output semantics: country scope, price ranking, and the vsCountryPct comparison. It does not describe the exact response envelope, but no output schema exists and the tool's complexity is low, so the definition is reasonably complete.

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 schema already documents the single country parameter with its ISO 3166-1 alpha-2 format and length constraints, so schema coverage is 100%. The description only reinforces that this is one country and does not add new parameter-level detail, matching the baseline for high schema 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 identifies the resource as state/province readings within a single country, which makes the tool's scope clear and distinguishes it from sibling tools like cities. However, it lacks a direct verb such as 'lists' or 'returns', and it does not explicitly name sibling alternatives, so it stops short of a 5.

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 the tool is for retrieving subdivision-level readings for one country, but it gives no explicit when-to-use guidance or exclusions relative to cities, compare, or country_index. An agent must infer the appropriate use case from the name and this single descriptive sentence.

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