OKstays

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing what the comparison returns (a structured verdict plus strengths/caveats), which helps the agent decide whether to spend a call on it. It stops short of noting cost or latency, so not 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?

One sentence, front-loaded with the action and cardinality, then the payoff contents. No filler; every clause tells the agent something it would otherwise have to guess.

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 carries the full burden of describing return values and does so concretely, listing each output section. Combined with annotations covering safety and a 100%-covered single parameter, nothing needed to invoke this correctly is missing.

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 parameter is fully documented, including the '2-4 hotel ids from search_hotels' provenance. The description's '2-4 hotels' restates the schema's minItems/maxItems without adding format or ID-source detail, so 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?

States a specific verb ('Compare') plus resource ('hotels'), the cardinality (2-4), and enumerates exactly what the comparison produces (Comfort Score breakdown, price, strengths, caveats, differing filters, verdict). An agent can distinguish this from get_hotel (single hotel) or search_hotels (discovery) without opening any 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?

The 2-4 constraint implies the use case (side-by-side evaluation of a shortlist), but the description never states when to prefer this over get_hotel or find_similar_hotels, nor any prerequisites. Usage is inferable but not spelled out, and no alternatives are named.

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 establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds the key behavioral detail that results are constrained to the same city and ranked by similarity across comfort filters. It still does not explain tie-breaking or ranking specifics, but it adds meaningful context 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 short sentences with no filler: the first defines the result set, the second clarifies a useful parameter mode. The content is front-loaded and appropriately sized.

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 annotations covering safety and the schema covering all parameters, the description supplies the main missing conceptual context: same-city scope and comfort-profile similarity. It could mention that a list is returned and how many by default, but the schema's limit description covers that.

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 all four parameters are documented in the schema; the description only reinforces cheaper_only and the meaning of hotel_id. It does not add new semantics for limit or max_price beyond the schema, so the 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 (hotels) and the specific selection logic (same city, comfort profile closest to a given hotel), which distinguishes it from broad search_hotels and single-hotel get_hotel. It does not explicitly name sibling alternatives, so it falls 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?

It gives one concrete usage phrase for cheaper_only ('like this one but cheaper'), which is helpful, but it does not state when to choose this over search_hotels or compare_hotels, nor when not to use it. Usage is implied by the required hotel_id rather than fully guided.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that by spelling out what the snapshot contains (aggregated counts, median price, best/worst attributes), which matters since there is no output schema. It stops short of disclosing data freshness, caching, or coverage limits.

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 payload and followed by the routing rule. Every clause earns its place, and the counter-example is compact rather than redundant.

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 single-parameter, read-only lookup with no output schema, the description supplies exactly the missing piece: what the response will contain. Combined with the rich annotations and the routing guidance, an agent has everything needed to select and call it 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 description coverage is 100% for the single 'location' parameter (city name or slug), so the schema carries the parameter semantics. The description adds no syntax, slug-format, or disambiguation detail beyond what the schema states; 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?

Opens with a specific noun-phrase resource ('Snapshot of a destination') and enumerates the concrete payload: hotel counts, average Comfort Score, median price, strengths/weaknesses, best neighbourhoods, suitable travel styles. It also names the sibling it is not, so an agent can distinguish it from search_hotels and list_cities without opening a 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 an explicit trigger ('when the user is choosing a destination or an area') and an explicit alternative with a concrete counter-example ('quiet hotels in Bangkok' -> call search_hotels directly). Both the when and the when-not are stated, leaving nothing to inference.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value by enumerating the returned content (ids, names, descriptions, categories, personas), which matters because there is no output 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?

A single compact sentence front-loads what is returned and appends the secondary persona data. Every clause earns its place with no 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?

With no params, no output schema, and annotations covering the safety profile, the description adequately discloses the return content an agent needs. It could note that this is a static reference list needing no arguments, but it is essentially 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 tool takes no parameters (empty object schema), so there is no parameter semantics to document; the baseline for zero-parameter tools 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?

States a specific resource (comfort filters: ids, names, descriptions, categories) plus travel styles/personas, and ties it to search_hotels, so an agent knows what it retrieves and why. It is clear but doesn't explicitly differentiate itself from the other sibling list tools, so it lands just 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 reference to search_hotels implies this is a discovery/reference call used before filtering hotels, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage 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?

Annotations already declare this a safe, idempotent, non-destructive read, so the description needn't restate that. It does earn credit by disclosing the payload's shape — that filter scores ship with explanations and that caveats are included — which is meaningful return-side context absent from the annotations and from any output 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?

One sentence, front-loaded with the resource and scoped by 'one hotel', then a compact enumeration of the returned fields. No filler and nothing buried.

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?

Absent an output schema, the description carries the burden of describing the response and largely succeeds by naming the Comfort Score breakdown, filter explanations, caveats, price and links. Error behavior for an invalid or stale hotel_id is the only notable 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?

With a single parameter at 100% schema description coverage, the schema fully documents hotel_id and its origin in search_hotels. The description adds no syntax, format or constraint detail beyond the schema, 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?

States a specific resource ('one hotel') and enumerates exactly what is retrieved: Comfort Score breakdown, per-filter scores with explanations, caveats, price and links. The singular scope implicitly separates it from list-oriented siblings like search_hotels and compare_hotels, though no sibling is named outright.

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 'one hotel' framing implies this is the lookup-to-detail step, and the schema's 'from search_hotels' hint reinforces the workflow. However, the description never explicitly says when to prefer this over compare_hotels or find_similar_hotels, nor what to do with an unknown id.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered structurally. The description adds that results include hotel counts, which is real return-content information given there is no output schema, but it stops short of describing ordering or result size.

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 short sentences with the payload description front-loaded and the optional filter second. Nothing is wasted, though the terseness contributes to the missing sibling differentiation.

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-optional-param read tool with rich annotations, the essentials are present, and the mention of hotel counts compensates for the absent output schema. What is missing is how this enumerates destinations versus get_city_overview, which an agent needs to route 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 description coverage is 100% and the single 'country' parameter is documented with an example in the schema. The description only restates that the filter is optional, adding no syntax or matching semantics beyond the schema, 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 phrase 'Destinations covered, with hotel counts' conveys the resource and what comes back, but it is a noun phrase with no verb and never states it returns cities. It does not distinguish itself from the sibling get_city_overview, which plausibly covers similar territory.

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?

'Optionally only those in one country' implies the filtering use case, but there is no statement of when to choose this over get_city_overview or search_hotels, and no explicit when-not 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the five-must-have filter gate, the 40% weighting of comfort filters in the score, and the cap of 10 results. It stops short of describing pagination or behavior when zero hotels qualify.

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 sentences, front-loaded with the ranking and gating behavior, then the optional modifiers, then the return shape. Dense but each sentence carries information; the parenthetical weighting detail is slightly cluttered but 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?

With no output schema, the description correctly describes the return shape ('up to 10 hotels with strengths, caveats, price and links') and the filtering semantics. Coverage is strong for a 10-param tool; only edge cases (zero results, pagination) are unaddressed.

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 all 10 parameters including examples, enums and the nearest-requires-near_lat/near_lng rule. The description adds conceptual context (what the Comfort Score is) but no per-parameter detail beyond the schema, so baseline 3 is 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 verb (rank) and resource (hotels in a city) plus the ranking model (OKstays Comfort Score) and the gating rule (only hotels passing all five must-haves). This is clearly distinguishable from siblings like compare_hotels, find_similar_hotels and get_hotel without opening their schemas.

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 explains the optional modifiers ('Optionally rank for a travel style (persona) and/or require specific strengths'), which implies when to pass persona/tags, but never states when to prefer this tool over compare_hotels or get_hotel. Usage is implied rather than routed.

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