TieredTravel

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

With no annotations, the description carries the full burden, and it does disclose the payload contents (daily cost per tier, currency, language, best months), which is genuinely useful given there is no output schema. It says nothing about rate limits, authorization, or comparison constraints beyond the schema's max/minItems of 2.

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?

A single economical sentence with the core comparison front-loaded and the returned attributes trailing in a compact list. It is a fragment without an explicit verb, but no words are wasted.

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 comparison tool with no output schema, the description covers both the input shape (two cities) and the salient return fields, which is what an agent needs. Only the absence of routing guidance relative to destination_costs keeps it short of 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 description coverage is 100% and the schema already states 'Exactly two city names or slugs,' so the parameter is fully documented structurally. The description only echoes 'two cities' without adding format, slug-vs-name preference, or resolution guidance, so baseline 3 is appropriate.

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 names the resource (two cities) and the scope of the comparison clearly, and 'side by side' makes the comparative intent unmistakable versus an unrelated sibling like walking_route. It never names destination_costs, so the distinction from the single-destination cost tool is left implicit rather than stated.

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?

Usage is only implied: the side-by-side framing tells an agent this is the tool for a two-city comparison rather than a lookup. There is no explicit when-to-use, when-not-to-use, or routing to destination_costs for single-city queries, so the guidance is minimal but inferable.

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 carries the full burden and handles the important traits: the data source (hand-written catalogue of 100 cities), the failure mode (error, never estimates), and the per-tier editorial content. It omits less critical traits like read-only nature, latency, or result ordering, but the operationally relevant behavior is disclosed.

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 tight sentences: what is returned first, then the data source, then the failure contract. Every sentence earns its place and nothing is repeated from the schema.

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 no output schema, the description must describe returns, and it does name the four cost categories plus the editorial overview per tier. The notable gap is currency and units for the figures, which an agent would need to interpret or present the costs 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 examples ("lisbon", "Lisbon") already in the schema, so the single city parameter is fully documented by structured data. The description adds no format, casing, or slug-resolution detail beyond what the schema provides, making the baseline 3 correct.

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?

States a specific resource (a day's cost in a city) and the exact breakdown returned: accommodation, food, transport, activities across budget/mid-range/luxury tiers. That scope is functionally distinct from compare_destinations and find_destinations, so an agent can route to it without opening the schema.

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?

Gives a clear precondition and boundary: only 100 catalogued cities are supported, and a miss returns an error rather than an estimate. It does not, however, point the agent at find_destinations as the way to discover whether a city is in the catalogue, which is the obvious alternative-routing guidance missing here.

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 carries the burden and does disclose the key behavioral facts: this is a pure lookup (no mutation implied by 'List'), it only knows a fixed catalogue, and the neighbouring tools hard-fail rather than infer. It doesn't discuss permissions or result size beyond the '100' cap, but for a read-only catalogue listing that is minor.

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 scope of the tool is front-loaded and the call-first guidance follows immediately. 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?

Covers purpose, filtering, when to call, and the absence of required parameters, which is sufficient for a one-parameter read tool with no output schema. What the return value looks like (bare names vs. names with country metadata) is left unstated, a small remaining gap.

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% and the single optional parameter already documents that it accepts a country, continent or name fragment and that omission returns all entries. The description restates that same information rather than adding format or matching-rule detail, so the baseline of 3 is appropriate.

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?

States a specific verb and resource ('List which cities this server knows about') plus the filtering scope (country, continent, name fragment), so the agent knows exactly what the tool returns. It also implicitly separates itself from siblings like destination_costs and walking_route, which operate on already-known cities.

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?

Gives an explicit trigger ('Call this first when a city might not be covered') and the reason ('the other tools fail rather than guess'), which routes the agent away from the sibling tools when coverage is uncertain. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 carries the full burden and does a solid job: it discloses return contents (ordered stops, what to know, coordinates, on-foot distance, total time), a meaningful exclusion (tram/metro/ferry legs removed and flagged separately), and a coverage limitation. Auth, rate limits and error behavior are unstated, keeping it short of a 5.

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 tight sentences, front-loaded with the payload description before the exclusions and coverage caveat. The unnamed 'nine cities' line is slightly unactionable but still earns its place as an expectation-setter.

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?

No output schema and no annotations, so the description must describe the return, and it does: ordered stops, per-stop detail, distance and total time, plus the multimodal-leg exclusion. Adequate for a read-only content tool, though the shape/format of the response is only described prose-wise.

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%, so both parameters (city, hours enum 3/6/12) are already fully documented in the schema. The description adds only tangential context ('total time') and does not clarify the hours semantics beyond what the enum already conveys, so the baseline 3 applies.

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+resource: a curated stop-by-stop walking route for a city, and enumerates what each stop carries (notes, coordinates, distance, time). The purpose is unambiguous, but it never explicitly names or contrasts with the siblings (compare_destinations, destination_costs, find_destinations), so differentiation is left to inference.

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?

Usage is implied (fetch a walk for a city) and there is a partial when-not: nine cities deliberately have no route. However, it neither names those cities nor points to an alternative tool for those cases, so the guidance is incomplete.

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