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?

Goes well beyond the readOnly/idempotent annotations: it discloses the 24-month window, the 1,000 cap, sort order, the upstream providers, the privacy limit (reviewer names are not included), and the failure mode (available=false means no reviews from this source). It also instructs on faithful quoting and not over-representing a small bad-review share.

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 dense paragraph that front-loads scope and sources before the output/handling guidance. Nearly every clause carries information, though the sentence grows long with several nested clauses that could be split for faster scanning.

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 and does so: it explains what is returned (count of 1-2 star reviews plus their texts, or recent reviews of any score), the ordering, the empty-result signal, and the fallback field. Nothing an agent needs to call and interpret this tool 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 real meaning: only_bad=true restricts to 1-2 star reviews (explicitly defined as a score of 4 or less out of 10), while only_bad=false also returns the most recent reviews of any score. That expands the schema's one-line gloss on the flag.

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 (guest reviews for one hotel) and pins down scope precisely: last 24 months, up to 1,000, newest first. It also names its data sources (Staylist via LiteAPI – Nuitée booking guests and Tripadvisor), which separates it cleanly from siblings like get_hotel or search_hotels.

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 context for use ('so the traveler can see what went wrong for other guests before booking') and points to an alternative path when this source is empty (nearby_with_reviews lists close hotels whose reviews can be read instead). It does not state explicit exclusions versus siblings such as get_hotel, so it falls just short of 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.