Staylist World

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description still adds real value beyond that: it cannot book or charge, checkout happens on the third party site, dated offers are price-sorted, URLs must be preserved unchanged, and a commission may apply without affecting scores or ordering. It stops short of covering rate limits, auth, or freshness of links.

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 with the return content, then constraints and disclosures, with no filler sentences. Slightly long at four sentences, but each one carries distinct information an agent needs (URL handling, sorting, no booking, commission).

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 exists, so the description carries the return-value burden and does so well: it enumerates the link types returned (property links to Trip.com/Klook, dated offer links sorted by total price, Staylist page). Combined with the annotations covering safety, 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 60%, and the description only indirectly maps parameters to behavior via 'Dated offer links, when present,' hinting that checkin/checkout select dated offers. It adds nothing about adults or children_ages semantics, so it neither compensates for the uncovered parameters nor goes meaningfully 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 ('Return the approved booking links for a hotel') and clarifies the exact scope by equating it with what is shown publicly on staylist.world plus the Staylist hotel page. This distinguishes it cleanly from get_hotel (hotel details), search_hotels, and list_destinations without the agent 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?

Usage is implied rather than stated: the agent can infer you call this when a traveler wants to book, and the description draws a useful boundary ('this tool cannot book or charge anyone'). However, it never names an alternative sibling or explains when to prefer get_booking_link over get_hotel, and no prerequisite sequence (e.g. after search_hotels) is 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?

With annotations covering the read-only/idempotent safety profile, the description adds real semantic context beyond them: refundable=null means unknown, prices are not guaranteed, the AI overview exists only "where one exists," and hotel policies reveal whether guests from all countries are accepted. It doesn't cover auth or rate limits, so it stops 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?

Purpose is front-loaded and almost every clause earns its place because no output schema exists, so the return-field inventory is genuinely useful. It is nonetheless one long run-on sentence with stacked parentheticals that could be more scannable.

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 tool with no output schema, the description does the heavy lifting: it lists returned fields, explains the photos omission, the AI-overview conditionality, null semantics, and price caveats. Only pagination/response-shape mechanics are unaddressed, a minor 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 60%, and the description compensates by explaining that dates/guests drive live-provider booking offers and that dates and occupancy must be carried over from the search, giving operational meaning to checkin/checkout/adults/children_ages. hotel_id is left to the schema, which already documents it.

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 verb and resource ("Hotel details") and enumerates the concrete fields returned, so an agent knows exactly what this retrieves. It implicitly distinguishes itself from search_hotels by referencing "from the search," but never names siblings explicitly, keeping it at 4 rather than 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?

Guidance is implied rather than stated: "Preserve dates and occupancy from the search" tells the agent to reuse search parameters, and "No photos: people see those on the booking page" redirects one need. However, it never states when to call this versus get_booking_link or search_hotels, leaving routing 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 readOnly/idempotent/non-destructive, and the description adds substantially more: a 1,000 cap, newest-first ordering, the 24-month window, the bad-review threshold (score of 4 or less out of 10), absence of reviewer names, and the meaning of available=false. It also discloses the output contract (staylist_page, booking_links) and the counting semantics the agent must preserve.

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 with purpose and scope, then behavior, then output contract - every clause carries information. The downside is that it is one dense run-on paragraph mixing retrieval facts, output shape, and editorial instructions (quote faithfully, report the denominator), which makes it harder to scan than a structured form would be.

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-value burden and does so: review counts, bad-review texts, staylist_page, booking_links, and nearby_with_reviews when available=false. Combined with the annotations, 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 both parameters are already documented; the description still adds meaning by defining 'bad' numerically (1–2 star / score of 4 or less out of 10) and clarifying that only_bad=false returns the most recent reviews of any score. The hotel_id linkage to search_hotels is only in the schema, not the description.

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?

Specific verb+resource ('Guest reviews for one hotel') with explicit scope: last 24 months, up to 1,000, newest first, sourced via LiteAPI. It also names its companions (get_booking_link, search_hotels for the id), so the agent can place it among siblings without opening 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?

Usage is clearly framed ('so the traveler can see what went wrong... before booking'), the default of only_bad=true is stated with the with-only_bad=false alternative spelled out, and the available=false path routes to nearby_with_reviews. It lacks an explicit statement of when NOT to call this versus a sibling (e.g., when no hotel_id is known yet), so it stops short of a 5.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior not in annotations: it consumes no provider search quota and reflects the live provider, which matters for call budgeting.

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 short sentences, no filler, and the key constraint (the list does not restrict searches) is placed early. Slightly fragmentary opening but appropriately sized for a trivial tool.

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 no-parameter, no-output-schema listing tool with strong annotations, the description covers what it returns, that it is optional, and its quota behavior. Only the return shape/size is unspecified, which is a minor gap given no output schema exists.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No param claims are made that could mislead.

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 conveys that this returns a set of popular destinations with country codes, but 'Popular starting points' is loose phrasing that never states the action (listing/browsing) plainly. It is distinguishable from sibling search/get tools by resource, though no sibling is named.

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 clarifies that the list is optional and does not restrict which destinations can be searched, which is real routing guidance for an agent deciding whether it must call this first. It never states a positive condition for when to call it, so usage is only implied.

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 mark this read-only/idempotent/non-destructive, but the description adds substantial behavior beyond them: result cap (up to 20), that empty fields mean unknown rather than bad, that shortlist_url is a shareable comparison page, that catalogue vs non-catalogue cities use different backends, and that sample_estimate is a previously observed price rather than a quote. It also states the privacy constraint 'Never send names, email addresses or payment details'.

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 usage rule is front-loaded, and most sentences carry distinct, non-redundant information (return shape, backend differences, sample_estimate caveat, privacy rule). It is dense and long, however, and runs several topics together without clear segmentation, which slightly reduces scannability.

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 an 11-parameter open-world search with no output schema, the description explains the key returned fields (area, station, amenities, price, score, sample_estimate, shortlist_url) and the two backend behaviors, which is strong. It stops short of covering a few filters (min_rating, max_price_per_night, country_code, stars), leaving those to inference.

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 only 18% schema coverage, the description carries much of the semantic burden: it clarifies that query words match amenities, that dates must be supplied together or not at all, the occupancy limits (1-8 adults, up to 6 children, one room), and the limit cap of 20. It does not explain min_rating, stars, max_price_per_night or country_code semantics, so it compensates partially rather than fully.

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 gives a specific verb+resource ('Find hotels by city, name or preferences') and clearly frames the tool as recommendations/comparison. It distinguishes itself from siblings by routing the traveler's link to get_booking_link and implying get_hotel handles a single hotel. An agent can identify the tool's role 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 explicitly states when to use it ('when the user wants hotel recommendations or wants hotels compared') and names the alternative for a different need ('Use get_booking_link for the traveler's link'). It also gives the precondition 'Supply both dates or neither', but offers no explicit when-not guidance, keeping it short of a 5.

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