OKstays

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

Annotations already carry read-only/idempotent/no-sign-in semantics, yet the description still adds real value by enumerating what comes back: Comfort Score breakdown, price, strengths/complaints, differing signals, and a verdict. It doesn't cover ordering, ties, or latency, but the output shape disclosure is the useful part 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?

Front-loaded trigger sentence followed by a dense but well-ordered enumeration of returns. Slightly packed—the parenthetical about hotel_name is easy to miss—but no sentence is 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 output schema, the description assumes responsibility for describing return content and does so, while annotations handle the safety profile and the required id source is explained. An agent has everything needed to call it and interpret the result.

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 the schema already documents all four parameters including ranges and date format. The description only adds the provenance of hotel_ids (from search_hotels) and a note that a hotel name can locate a named hotel; that is useful but minimal, 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) and resource (2-4 specific hotels) and immediately differentiates from siblings by naming search_hotels as the id source, implicitly separating it from single-hotel get_hotel and find_similar_hotels. An agent can select 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?

"Use this when the user is choosing between 2-4 specific hotels" gives a clear trigger, and it explains where the ids come from. It stops short of stating the inverse case (a single hotel → get_hotel, or open-ended browsing → search_hotels), so the routing is good but not exhaustive.

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 'read-only, no sign-in' is largely redundant. What earns credit is the undisclosed domain behavior: results exclude any hotel with repeated complaints about cleanliness, beds, showers, bugs or safety, and each result carries the price difference versus the anchor. Return shape in detail (no output schema) and behavior when dates are omitted are not covered.

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 dense sentence pair, front-loaded with the usage trigger and example, then the result contract. No filler and nothing buried at the end that an agent needs early.

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 7-parameter, no-output-schema tool it covers the essentials: what comes back, how it is ranked, and what is filtered out. Gaps remain around whether prices/stay-open links work without checkin/checkout and what the response object looks like, which matters given there is no output schema.

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 all seven parameters are already documented, which sets the baseline at 3. The description adds domain meaning for cheaper_only ('like this one but cheaper') and implies hotel_id defines the destination scope, but gives no extra syntax or format guidance beyond the schema.

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 and pins the scope: alternatives to a given hotel, in the same destination, ranked by 'closest comfort profile'. The anchor-by-hotel_id framing plus the complaint-exclusion filter makes it clearly distinct from search_hotels (query-based) and compare_hotels (comparison), so an agent can route 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 condition ('when the user likes a hotel but wants alternatives') with a concrete user utterance example and the cheaper_only variant. It stops short of naming when NOT to use it or pointing to compare_hotels/search_hotels as alternatives, so it is clear context rather than full routing 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally; the description still adds the auth context ('no sign-in') and, because there is no output schema, spends most of its text disclosing exactly what the response contains. It does not address failure modes (unknown city, missing guide) or any cost/latency characteristics.

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 routing guidance is front-loaded and the closing sentence cleanly closes the scope with the sibling handoff. The middle is one very long enumerated clause listing return contents; it is justified by the absent output schema but is heavy to parse in a single pass.

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 compensates by specifying the return payload item by item, and with full schema coverage on four simple parameters nothing else is needed. An agent has enough to decide when to call it and what it will get back.

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 explains adults, checkin/checkout and the location slug including the area-to-destination behaviour. The description adds nothing about parameter semantics beyond what is structured, 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 names a specific resource (destination/city overview) and enumerates its payload precisely: hotel count, average Comfort Score, median price, neighbourhoods with top hotels, travel styles, city tax, seasonality, and area guide. It explicitly distinguishes itself from search_hotels, so an agent can route without opening either 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?

It states the deciding condition up front ('when the user is still choosing a destination or an area to stay in') and names the alternative with a concrete example: 'A request for hotels (e.g. quiet hotels in Bangkok) is search_hotels' job.' Both when-to-use and when-not-to-use are explicit.

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?

The annotations already establish read-only, idempotent, non-destructive behavior, but the description adds useful context by describing the returned fields and noting that no sign-in is required. Since there is no output schema, the return-shape summary is especially valuable, though it does not cover error cases or 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?

The description is short and front-loaded, starting with the primary use case before listing return contents and the search_hotels tag shortcut. Every sentence contributes useful selection or interpretation context.

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 zero-parameter, read-only lookup with rich annotations and no output schema, the description provides enough context to call the tool correctly. It explains when to use it, what it returns, and how the returned values relate to search_hotels.

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 there is no parameter semantics burden beyond establishing that the call is a parameterless lookup. The baseline for zero-parameter tools 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 and resource: looking up comfort signals and travel styles accepted by search_hotels. It also distinguishes the tool from search_hotels by framing it as the lookup path when the user's wish does not map clearly to a filter.

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 an explicit usage condition: use this when the user's wish doesn't map clearly to a filter or travel style. It also names the alternative path by noting that plain names work directly in search_hotels tags, which helps an agent choose between lookup and search.

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, and destructiveHint=false; the description adds the practical consequences ('Read-only, no sign-in') plus a concrete cost tradeoff for detail='full' (about four times longer) and a full inventory of returned content. It stops short of describing pagination or failure behavior for an unknown hotel_id.

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 trigger is front-loaded and the return-value sentence earns its length by listing what the agent will actually see. The middle sentence is a dense run-on that would read better split, but no sentence is 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?

There is no output schema, so the description carries the return-shape burden itself and does so by naming each payload component. Combined with explicit guidance on focus and detail, an agent has everything needed to call this correctly for a single-hotel lookup.

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 all six parameters are already documented and the baseline is 3. The description adds modest value beyond that: routing focus to 'what the user asked about' and quantifying detail='full' as roughly four times longer, but it adds nothing for adults, checkin, or checkout beyond the schema.

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 opens with a precise trigger ('when the user asks about one hotel') and enumerates exactly what comes back: Comfort Score breakdown, must-haves, strengths/complaints with reasons, price, city tax, link. It implicitly separates itself from search_hotels and compare_hotels by scoping to a single hotel's detail view.

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 trigger is explicit ('when the user asks about one hotel: why it scores as it does, or whether it's quiet, clean or good for sleep or work') and it tells the agent how to set focus and when to escalate to detail='full'. It doesn't name the alternatives (search_hotels for discovery, compare_hotels for multi-hotel comparison) or state when not to use it, so a small inference remains.

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's 'Read-only, no sign-in' largely restates it but adds the useful auth detail of no sign-in required. It also discloses the return payload contents, which the annotations do not.

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 tightly packed sentences with the trigger condition front-loaded, followed by the return shape and the filter behavior. No filler or restatement of the title.

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 zero-required-parameter, single-filter list tool with full annotation coverage and no output schema, the description supplies everything needed: when to call it, what it returns, and how the optional parameter changes scope.

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 the baseline is 3, but the description adds genuine value beyond the schema's 'Country name to filter by' by stating that passing country restricts output to one country — clarifying the unfiltered default. It doesn't add format nuances (e.g., exact-match vs partial name), keeping it from a 5.

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 ('which destinations OKstays covers', 'Returns every destination we score') plus the returned fields (country, slug, hotel count), so the agent knows exactly what comes back. It does not explicitly contrast itself with the nearest sibling, get_city_overview, which prevents 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?

Gives clear triggering conditions: 'when the user asks which destinations OKstays covers' and 'before planning a trip through a country', which implicitly routes the agent here ahead of plan_trip. It also explains the filter/no-filter choice, but names no explicit exclusion or alternative tool for detail-level city data.

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?

Despite annotations already covering read-only/idempotent safety, the description adds substantial behavior beyond them: results ordered by travel sequence, best match chosen by Comfort Score or the travel style's score, alternatives, stay dates, indicative totals, and the deep-link behavior where each hotel link carries the stop's dates so its Book Now button books those nights. 'No sign-in' is also extra context not in the 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?

Five short sentences, each doing distinct work: trigger, return shape, link behavior, prerequisite, sibling pointer, and safety. The important scope and return information is front-loaded 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 9 parameters, no output schema, and rich annotations, the description fills the key gaps: what is returned per stop, how dates chain, how ranking works, and the confirmation prerequisite. Nothing essential for correct invocation 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%, so the baseline is 3, but the description adds meaning beyond it: persona drives which score ranks hotels, and start_date is chained so each stop begins when the previous ends. It also reinforces ordering of stops and the need to settle nights with the user, though it does not explain per-parameter defaults or limits beyond the schema.

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 and resource ('plan a multi-stop trip', 'returns hotels for each stay in travel order') and its multi-stop scope implicitly separates it from single-city siblings like search_hotels. An agent can identify the tool's job 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?

It gives explicit triggering context ('when the user plans a trip with several stops'), a prerequisite ('agree the stops and nights with the user first'), and routes coverage questions to list_cities. It lacks an explicit when-not / alternative for a single-destination search (search_hotels), so it falls short of the 5 bar.

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, and the description adds genuinely new behavior: 10 results per page, ranking order with tie-breaking on review count, a caveat that thin-review hotels are pulled toward the destination average, and the important rule that hotel_name causes other filters to be ignored. 'Read-only, no sign-in' merely restates the annotations, and pagination cap of 5 pages is only in the 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?

The trigger is correctly front-loaded, but the second sentence is a single sprawling construction with nested parentheticals containing Comfort Score weighting percentages (60/30/15/15/10) that are expensive to parse and only marginally useful for tool selection. That detail does help interpret ranked output given there is no output schema, so it earns partial rather than zero credit.

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 17-parameter search tool with no output schema, the description still covers result contents (strengths, complaints, indicative price, okstays.com link), page size and ordering, and the name-lookup override. Missing only pagination ceiling and explicit guidance on which sibling to call for follow-up detail, both of which the schema or siblings partly supply.

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 17 parameters are already documented, and the description mostly re-lists them (travel style, 8+ signals, price, minimum score, neighbourhood, distance, property_type). It does add one cross-parameter insight — that the long-stays persona defaults to property_type 'any' — but that is also repeated in the schema.

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+resource ('search hotels in a destination') plus the two distinct entry modes (destination browse vs. lookup by hotel_name), which lets an agent separate it from get_hotel, compare_hotels and find_similar_hotels without opening a schema. The scope exclusion ('Places to stay only, not flights or car hire') further sharpens what it does.

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 opening clause gives a concrete trigger with a worked example ('quiet hotels in Bangkok under $150') and covers the by-name variant. It does not state when to prefer siblings like get_city_overview or plan_trip, and the only exclusion is the flights/car-hire line, so routing is clear but not fully comparative.

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