Guestit

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds non-obvious context: results retain missing or unavailable listings rather than erroring, and prices include fees but do not hold inventory or create a booking. That is genuine behavioral value beyond 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?

Three short sentences, zero filler, with the core purpose and the cardinality limit front-loaded before the caveats about missing listings and pricing.

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?

An output schema exists so return values need not be described, and the key caveats (unavailable listings retained, prices not bookable) are covered. The main remaining gap is not routing the agent from search_stays into this tool by name.

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 only 40%, and the description compensates only partially: it reinforces the 2-4 slug bound and the shared date/guest constraint, but says nothing about the locale enum or the 730-day check-in/night limits that the schema documents for the dates.

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) over a specific resource (Guestit listings) and bounds the scope with 'two to four distinct' listings for shared dates and guest count. This visibly separates it from search_stays and stay_details, though it never names those siblings explicitly.

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 'two to four distinct listings' constraint implies the caller must already hold listing slugs (i.e. use this after a search), but that sequencing is left to inference. No explicit when-to-use/when-not-to-use statement or named alternative is provided.

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 closed-world, so safety needs no restating. The description adds real behavioral detail beyond them: result cardinality is capped at one, only destinations with Guestit stays are returned, and the empty-result path requires asking the user about a nearby larger place. It stops short of saying whether a fuzzy/partial match is attempted, which is the one behavior an agent would still wonder about.

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 short sentences, zero filler, and the ordering is correct: what it does, then how to call it, then what comes back, then what to do when it fails. Each sentence carries a distinct instruction.

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?

An output schema exists, so return structure needn't be explained, and the description still volunteers the useful cardinality fact (at most one). Combined with the fallback guidance this is nearly complete; the only gap is the unmentioned `locale` parameter and what a non-matching vs. ambiguous result looks like.

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 0%, so the description carries the full burden. It does clarify the meaning of `query` (a bare place name like 'Åre' or 'Stockholm', not a hotel or a country), but `locale` with its en/sv enum is never mentioned, leaving one of two parameters documented only by its schema. That partial compensation lands at the baseline.

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 ('Find the Guestit destination') and pins down scope: resolves a place name, returns at most one place, only places with Guestit stays. The phrase 'before searching stays' positions it as a prerequisite step relative to search_stays, so an agent can distinguish it from its siblings 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 clear when-to-use ('before searching stays') plus a concrete input rule ('Pass the place alone, such as Åre or Stockholm') and explicit failure handling ('ask the user about a larger place nearby'). No sibling tool is named as an alternative and there is no explicit when-not-to-use, so it falls 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?

The annotations already establish that this is a read-only, idempotent, non-destructive search, but the description adds substantial behavioral context beyond them. It discloses that prices are estimates with no inventory hold, that live-check failures can reduce page size below the limit, that nightly-rate filters use indexed average rates rather than final totals, and that pagination counts reflect the search index rather than current public rows. These are meaningful operational caveats an agent needs before interpreting results.

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 front-loaded with the core action and then layers only operationally important caveats: workflow, estimates, live-check omission, rate semantics, pagination, and booking handoff. Every sentence carries distinct information, and none is a restatement of the tool name or schema. It is dense but appropriately sized for a search tool with multiple behavioral caveats.

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?

Given the output schema, the description does not need to explain return fields, and it already covers the workflow, sibling tools, booking handoff, estimate semantics, live-check omissions, rate-filter behavior, and pagination discrepancies. Together with the annotations and output schema, it gives an agent enough context to invoke the tool correctly and interpret its results. No critical behavioral gap remains.

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 only 33%, so the description must compensate for several undocumented parameters. It adds useful meaning for location_id provenance, date/guest price estimation, nightly-rate filter semantics, pagination behavior, and filter resending, but it does not explain page, limit, sort, locale, with_pets, min_bedrooms, or num_guests directly. The added context is helpful but does not fully cover the 12-parameter surface.

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: 'Search public Guestit accommodation using a location_id from resolve_destination.' It also distinguishes this tool from siblings by routing location resolution to resolve_destination and detailed inspection to stay_details or compare_stays. An agent can tell what this tool is for 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?

The description gives explicit workflow guidance: obtain location_id from resolve_destination, resend the full filter set when refining, and read house rules and cancellation policy with stay_details or compare_stays before recommending. It also says booking happens on the returned Guestit website link, which clearly positions this as a discovery tool rather than a booking tool. Alternatives and sequencing are named rather than left 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 closed-world, so the safety profile is covered. The description adds genuinely new behavior: fees are already included in the total, no inventory is reserved, no payment is taken, and website_url arrives with dates and guests pre-filled — all decision-relevant for an agent that might otherwise assume a booking side effect.

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 short sentences, front-loaded with what is read, then inputs, then pricing semantics, then the no-commitment disclaimer, then the handoff. Nothing is repeated and every sentence carries information an agent needs.

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?

An output schema exists, so return values need no explanation, and the description covers the read-only nature, the estimate inputs, and the next step. The only shortfall is the undocumented locale parameter and slug expectations, a minor gap for a five-parameter tool.

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 only 40%, so the description must carry weight, and it does clarify that both dates plus guest count are jointly required to produce an estimate. Still, it says nothing about locale (en/sv), the listing_slug format, or why the two dates are coupled — the date-limit constraints live only in the schema property descriptions.

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 uses a specific verb ('Read') with concrete resources: a public Guestit listing, house rules, cancellation policy, and a dated price estimate. It is clearly a single-listing detail lookup rather than a search, though it never names search_stays, compare_stays, or resolve_destination to draw the boundary explicitly.

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 a usage condition for pricing ('Supply both dates and the guest count for an estimate') and a follow-on action ('Open website_url to continue on Guestit'), which implies the tool's role in a booking flow. However, it never says when to prefer it over search_stays or compare_stays, so the agent must infer the routing from the sibling names alone.

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