Déstaire

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

Goes well beyond the annotations by disclosing the payment mechanism (MPP payment, Stripe Shared Payment Token from the user's wallet such as Link), that a pay link is returned, that delivery is tied to the email account, and that the purchase is final and non-refundable. That irreversibility and payment-flow context is exactly what annotations like destructiveHint=false cannot convey.

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 tight sentences, front-loaded with what the tool does and the payment model, followed by the prerequisite and the finality warning. No filler or repetition.

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 enumerated, yet the description still previews the pay link. Combined with payment method, delivery target, prerequisite, and non-refundability, everything an agent needs to call this safely is present.

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 both parameters are already documented, and the description largely restates the email parameter's purpose ('the guide goes to that account') while adding the actionable requirement to confirm it with the user. The slug parameter gets no additional semantic detail. 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?

States a specific verb and resource ('Buy a city guide for the user') and immediately qualifies the transaction model ('paid inside this conversation'), which separates it from the read-only get_guide/list_guides siblings. An agent knows exactly what this tool does 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?

Gives a clear prerequisite ('Confirm the user's email first') and frames this as a paid purchase, which implicitly contrasts with the free read siblings. It never explicitly names get_guide as the alternative for reading, so the when-not-to-use routing is 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds that the response body varies by detail level, including place lists at 'full', but it doesn't disclose anything about error behavior for unknown slugs or payload 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?

It is a single short sentence, so it is not verbose, but the 'One article:' fragment front-loads a noun rather than the action, and the trailing phrase 'with every list of places' is grammatically loose and slightly ambiguous.

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 an output schema present and annotations covering safety, the definition's scope is mostly adequate. It still leaves the agent without guidance on tool selection (this tool vs. the list/search siblings) or failure modes, which is a meaningful gap for a lookup 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 description coverage is 100% and both parameters (slug pattern/meaning, detail enum with default) are documented there. The description's nod to detail='full' merely restates the enum, adding no new semantics such as expected text length or cost.

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 single-article retrieval and its returned content ('opening paragraphs' vs 'whole text with every list of places'), which separates it from sibling list_articles. The verb is only implied ('Get' comes from the name/title), and the telegraphic 'One article:' opener is less crisp than a full sentence.

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 never states when to pick this tool over list_articles, get_guide, or search_stays, nor what prerequisites (a valid slug) exist. The only usage-adjacent content is the detail tradeoff, which is already carried by the schema.

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 cover readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely useful behavioral context beyond them: the default response is truncated to the first 10 stays with a total count, and detail=full returns everything. That truncation/context-saving behavior is not expressed 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?

It is a single short sentence with no filler, which is good, but the structure is choppy: the clause 'the first 10 and the total, or all of them with detail "full"' is syntactically loose and slightly ambiguous about what is truncated (the stays vs. the destination).

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 explained, and annotations cover the safety profile, so the remaining burden is light. However, for a tool whose default response is silently truncated, the description could do more on error/not-found and ambiguous-slug behavior, and usage guidance is thin.

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 slug, detail, and country are already documented in the schema, making 3 the baseline. The description gestures at the detail enum's effect but does not add syntax, format, or fallback meaning beyond what the schema string already says.

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 (retrieve one destination plus its stays) and uses 'One destination' to distinguish from the sibling list_destinations. It does not name the sibling explicitly, but an agent can tell single-fetch from list semantics 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?

Usage is only implied: 'One destination' signals single-record lookup versus list_destinations, and the detail explanation hints at when a lighter response is wanted. There is no explicit when-to-use/when-not guidance or alternative 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered structurally. The description adds the nature of the payload (a public shop page containing price and photos), which is mild added context, but says nothing about auth, caching, or error behavior.

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, and the payload contents are front-loaded. The second sentence is slightly oblique in phrasing but earns its place by separating read from purchase.

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?

Output schema exists so return values need not be restated, and annotations cover the safety semantics; the single required parameter is documented in-schema. The description is complete enough for an agent to call this correctly, with only routing to buy_guide left implicit.

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?

One parameter with 100% schema description coverage; the schema already explains that slug is the last part of the guide's URL and constrains its format. The description adds no syntax or lookup guidance beyond that, 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?

It names the resource and scopes it explicitly as the public shop page of a single city guide, listing the data it exposes (standfirst, contents, price, photo URLs). It distinguishes itself implicitly from buy_guide by noting the guide is sold on its page, though it does not name that sibling 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 clause 'The guide itself is sold on its page' implies the purchase action belongs elsewhere (buy_guide), but no alternative is named and no condition is stated. Usage is inferable rather than spelled out.

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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the shape of the payload ('as its page shows it' plus the field inventory), but says nothing about missing-slug behavior, error cases, or rate 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?

A single front-loaded sentence with no filler. The field enumeration is mildly wasteful since an output schema already defines the return shape, but it costs little and reads cleanly.

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 an output schema present the description need not explain return values, and annotations cover the read-only/idempotent nature, so the core needs of a one-param lookup are met. The only meaningful gap is not telling the agent where a slug comes from (i.e., routing to search_stays).

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 'slug' parameter is fully documented in the schema, including its pattern and that it is the last part of the stay's URL. The description adds no parameter meaning beyond that, 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 verb and resource ('get_stay' returns one stay) and previews the returned surface — description, address, location, website, rate, amenities, collections, photos. It is clear on its own, but never names or contrasts with the obvious sibling search_stays, so an agent must infer that this is the single-record fetch versus the filtered list.

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?

No when-to-use guidance and no exclusions. It does not say that a slug is required or that slugs come from search_stays/list_stays, nor when an agent should prefer this over search_stays for detail retrieval. Usage is only implied by the field list.

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, closed-world behavior, so the safety profile is covered. The description adds one genuinely new behavioral fact — results are sorted newest first — plus the returned field set, but says nothing about pagination, default page size behavior, or total counts.

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 front-loaded sentence covering scope, ordering, and output fields with essentially no waste. It is slightly telegraphic — the sentence is a fragment with no verb, which reads more like a caption than a tool description.

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, an output schema covering return values, and 100% schema coverage on both parameters, the description only needs to supply ordering and routing context. Ordering is present, but there is no guidance on when to prefer this over sibling list/search tools, so it is adequate rather than 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?

Schema description coverage is 100% and both parameters (limit, category) are documented in the schema, so the baseline is 3. The description's 'category' mention refers to a returned field, not the filter, and it adds no filter syntax, matching rules, or limit semantics 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 names the resource (travel writing/articles), its ordering (newest first), and the fields delivered, so an agent knows exactly what comes back. The verb is only implied by the tool name and there is no explicit differentiation from siblings like list_guides or get_article, which keeps it 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?

There is no when-to-use statement, no mention of the alternative retrieval tools (get_article, search_stays-style search), and no indication of when browsing this list beats fetching a single article. The 'newest first' ordering hints at a browse-feed use case but leaves the agent to infer it.

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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description usefully adds that results are aggregated with stay counts, but says nothing about ordering, pagination, or completeness of the result set beyond that.

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 dense sentences that lead with what is returned and close with the actionable link to search_stays. Slightly convoluted opening clause ('The countries and destinations that have stays') but no wasted 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 an output schema present, the description does not need to enumerate return fields, and the sole parameter is fully documented in the schema. What remains is conveyed: what is listed, that counts are included, and how the output feeds search_stays.

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 there (name or ISO code). The description never mentions the country filter, so it adds no meaning beyond the schema; 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 the resources precisely: countries/destinations that have stays plus the collections (Coast, City, Mountain), each with a stay count. This separates it from the singular get_destination and from search_stays, though the listing verb itself is only implied by the name rather than stated.

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 closing line 'Their names and slugs are the filters of search_stays' tells the agent exactly why and when to call this: to discover valid filter values before searching. No explicit exclusions are given, but the workflow context is clear.

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 the safety profile is fully covered. The description adds the useful detail that results are limited to guides currently on sale, but nothing about volume, ordering, or freshness beyond that.

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 front-loaded sentence that lists the returned fields with no filler. It is appropriately sized, though the clause structure is slightly list-like rather than prose.

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 an output schema present the description need not document return shape, yet it still summarizes the fields, and the 'on sale' scope fills the main interpretive gap. Complete enough for a zero-argument list tool, missing only sibling routing.

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 zero parameters, so the description carries no parameter burden and the empty schema is self-consistent. Baseline 4 applies for a no-argument tool.

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 precisely (city guides that are on sale) and enumerates the return fields (city, standfirst, price, buy URL), so an agent knows exactly what comes back. It does not explicitly differentiate from get_guide or buy_guide, keeping it 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 phrase 'on sale' scopes the listing to purchasable guides, which implies when this tool applies. However, there is no explicit when-to-use guidance or comparison against siblings like get_guide (single guide) or buy_guide (purchase action).

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 the safety profile is fully covered. The description's added behavior ('Best matches first') largely restates the schema's sort default of 'relevance', and the listed return fields are already exposed by the output schema, so it adds limited new behavioral context.

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 tight sentences, front-loaded with the core action, then filters, then result shape. No filler and nothing repeated unnecessarily.

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 an output schema present, the return-value sentence is a bonus rather than a necessity, and all eight parameters plus the safety annotations are well covered. The one gap is routing guidance relative to get_stay/list_destinations, which an agent would have to infer.

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 eight parameters are documented in the schema, including the 'from' rate semantics and amenity matching. The description adds only the grouping phrase 'a nightly budget in euros' for max_rate, which is minor beyond what the schema already says. Baseline 3 applies when the schema does the heavy lifting.

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 specific verb and resource ('Find hotels and private stays') and specifies the search modality ('by plain words'), which cleanly separates it from get_stay (single fetch) and the list_* siblings. An agent can identify this as the keyword-search entry point 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?

Usage is implied by 'with optional filters for country, destination, collection, amenities, and a nightly budget', which tells the agent this is the filtered discovery tool. However, no sibling is named and there is no when-not guidance (e.g., use get_stay when you already have an ID, use list_destinations to discover filter values).

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