Stay Otter

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

Well beyond what readOnlyHint/openWorldHint already convey: it discloses quota tiers (1/day free, 30 for Pro), a 5–60 second latency expectation, source coverage limits (no Airbnb), and that values are read live at call time ('each read now'). It does not say what an error or partial response looks like when a source blocks the read, which is the notable remaining gap.

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 content is dense and largely front-loaded, but it is delivered as two long run-on sentences with a confusing metaphor in the opening clause and stacked clauses mid-sentence. Latency and quota — arguably the most decision-relevant facts — are buried at the tail.

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 6-param, no-output-schema, open-world read tool whose annotations only cover safety and openness, the description supplies the returned data set, quota, latency, source coverage and freshness. What remains unaddressed is the adults parameter and any behavior on failed/unsupported reads, which stops it short of fully self-contained.

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 50% schema coverage the description must carry the undocumented half, and it partially does: 'with dates' explains checkIn/checkOut semantics (prices only appear then), 'a hotel's name and city' explains city, and 'a spot they name' reinforces the spot param. However, the adults parameter is never mentioned in either the schema or the description, and 'with dates' gives no format or pairing constraint, so the compensation is incomplete.

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 core action is specific: read a single property the traveler found and return location, street character, nearby bars/cafés/restaurants within a ten-minute walk, distance to a named spot, and lowest total/cancellable prices. This is distinguishable from the sibling aggregators (search_stays, city_picks, get_stay) because it enriches one user-supplied listing rather than searching. The opening clause 'Reads one place the traveler found themselves into the receipts a pick carries' is metaphorically garbled and delays the actual meaning.

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 explicit input eligibility (Booking.com, Vrbo, Expedia page or hotel name + city) and a hard exclusion ('Airbnb pages cannot be read'), plus a stated prerequisite ('Needs a key: one check a day free, Pro up to thirty'). It does not name a sibling as the alternative for cases this tool cannot serve (e.g. an Airbnb link), leaving the agent to infer that search_stays or get_stay should be used instead.

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 grant readOnlyHint=true, but the description adds meaningful behavior: results are instant and free, cached from a rota refresh, and pinned to fixed trip parameters (~six weeks out, two adults/five nights, or a six-adult weekend in named cities). That the agent cannot control dates or party size is critical context absent from the schema. Points withheld because the trip-shape rules are buried in a single dense sentence and the city enumeration functions as data rather than 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?

The city roster is stated twice in near-identical form plus a third superset list, burning most of the token budget on redundant enumeration. The whole definition is one run-on sentence with no line breaks or structure, and the most decision-relevant facts (fixed dates, fixed party size) are buried mid-sentence rather than front-loaded.

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 two-parameter, read-only lookup with no output schema, the description covers the essential facts an agent needs: coverage, fixed trip parameters, the stayType fork, and the fallback tool. It doesn't hint at the response shape at all, but with no output schema that is a minor gap for a simple retrieval 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 50%, and the `city` parameter has no schema description at all — the description compensates by enumerating the covered cities, which effectively serves as the allowed value set. `stayType` is explained beyond the schema's one-liner: `hotel` yields a two-adult/three-night room trip only in a listed subset, while whole homes are the default with five nights and two adults. Deduction for inconsistency — the hotel-capable city list is duplicated and several cities appear in both lists.

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 precomputed, cached search result ('the latest finished standard search') for a covered city, which is a specific resource. It does not lead with a clean verb+resource phrase, forcing the agent to parse a run-on sentence, but the coverage constraint and the routing sentence at the end make it distinguishable from search_stays.

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?

'For other places or specific dates use search_stays' explicitly names the alternative and the two conditions that select it. Implicitly, use this tool when the city is covered and the exact dates don't matter, but the description never states that positive condition directly — the agent must invert the exclusion.

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 and openWorldHint, and the description adds real context: results come from Viator, ranking prioritizes trip intent over the city's default best, and a fallback is mentioned 'when the row is thin.' The fallback phrase is too vague to be actionable, but the sourcing and ranking behavior are genuine additions 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?

Two compact sentences with the resource and provenance front-loaded. Some phrasing is convoluted ('what the trip is for first, the city's best otherwise,' 'a second place to look when the row is thin'), which slightly blunts otherwise efficient text.

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 2-parameter read-only tool with annotations and no output schema, the description covers input provenance and ranking logic but says nothing about what the response contains or how many results come back. The vague 'second place to look' reference leaves an agent unsure what it is being pointed at.

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 50% and searchId has no description at all in the schema, so the description's guidance to source it from search_stays or city_picks compensates meaningfully. It also clarifies that intent overrides the search's own context, adding semantics beyond the schema's brief 'Override' note.

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 resource and source: 'Top-rated things to do on Viator for a search's spot and dates.' It is clearly a discovery/listing tool, distinguishable from get_stay and search_stays by naming the thing it returns, though it never uses a direct verb like 'get' or '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?

'Pass a searchId from search_stays or city_picks' gives the explicit prerequisite and names the two sibling tools that produce the input. It states the intent-override rule but offers no when-not-to-use case or routing versus other content tools.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses cost ("Free"), latency ("usually instant, a few seconds the first time"), a data-quality caveat ("+" when the map read was capped in a dense center), and an explicit scope boundary ("no crime figures, no safety rating"). It even points to the underlying method URL. That is meaningful behavioral context an agent cannot get from structured fields.

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 in the opening clause, and later sentences carry distinct payloads (map cross-reference, latency, method link). The core sentence is long and heavily parenthesized, which costs some readability, but no sentence is pure 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 must carry the return shape, and it does: it enumerates every returned fact and flags the capped-count notation. Combined with the cost, latency, and method disclosures, 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%, and the schema descriptions already explain that searchId comes from search_stays or get_stay and sourceId comes from the card. The description reinforces the "finished search" and "pick" framing but adds no format, constraint, or edge-case detail beyond the schema. Baseline 3 is correct.

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 and enumerates its contents precisely: counts of bars, pubs, cafés, restaurants and groceries within a ten-minute walk, plus the nearest stop and night-walking facts. That level of specificity makes the tool's scope unmistakable. It stops short of a 5 because it never names a sibling (e.g. get_stay, search_stays) to contrast against, so the agent must infer the boundary from context alone.

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?

"from a finished search" and "the pick's sourceId" imply the prerequisite state and inputs, which is useful implied guidance. However, there is no explicit statement of when to reach for this tool versus get_stay or city_picks, and no exclusion conditions. The agent can infer usage but is not told 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 and the description is consistent with that (nothing suggests mutation). It adds cost/latency context ('Free and instant') and explains what the card contains (venues by kind, groceries, nearest stop, map facts), which is genuine value beyond the annotation.

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 and the key usage trigger are front-loaded, but the tail half is promotional filler — the ground-method URL and the no-account vote page — that doesn't help an agent invoke this tool correctly and dilutes the signal.

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 burden of describing returns; it gestures at contents ('finished picks with receipts', 'running status', block facts) but never characterizes the shape or what 'receipts' actually are. Adequate to call, but an agent still can't anticipate the response structure.

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?

searchId is well covered by the schema description and the description reinforces its provenance ('the searchId from search_stays, or the id in a stayotter.com/stay/s_… link'). However, travellerCountry appears in neither the schema description nor the prose, leaving half of the 50%-coverage parameter set undocumented.

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 the resource ('the card for a search by searchId') and its two return modes ('finished picks with receipts, or its running status'), which lets an agent distinguish it from search_stays. The verb is implied by a noun phrase rather than stated outright, keeping it just 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?

It names the exact sibling and the condition that selects it: 'Use it to finish a search_stays call that returned running,' plus the secondary case of reading a shared stay link. No inference is required to know when to reach for this tool over search_stays.

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 past the readOnly/openWorld annotations: discloses latency ('picks within about a minute', hard stop at two and a half minutes), the async contract ('returns status running with a searchId'), dedup/limit behavior (up to three picks), and output artifacts (receipts, tracked openUrl links). Quota and auth requirements are stated explicitly: three free trips per connection, then a key; free account five a month, Pro unlimited.

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 sentences, front-loaded with what it searches and returns, then timing, then pricing. Dense but every sentence carries distinct information. The rate-limit sentence with two nested account tiers is slightly bulky but not wasteful.

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 19-parameter, no-output-schema search tool, the description covers the essentials an agent needs: sources searched, result count and composition, async fallback, and cost/auth gating. Remaining gaps are mostly parameter-level nuances already handled by the schema, though the 'verified against the map' claim and the alert-oriented flexDays intent could use more explanation.

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 79%, so the schema already carries most parameter meaning. The description adds only loose references to 'the dates and party' and implies waitSeconds drives the running-status cutoff; it does not explain stayType vs. hotelBrands interplay, budget tiers, or the two price caps. 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 concrete verb+resource with named sources: 'Live search of Booking.com, Vrbo and Expedia Group (hotel rooms)'. It also conveys the output shape (three picks: best overall, best value, closest). It doesn't explicitly differentiate from siblings like get_stay, check_listing, or city_picks, so an agent must infer the boundary from names alone.

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?

Implicitly frames this as the discovery step ('Live search... verified against the map') and explains the waitSeconds/running-status fallback, which is useful. But it never says when to prefer this over get_stay, check_listing, or city_picks, nor any exclusions (e.g., do not use for a known listing).

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 annotations: it discloses a recurring daily re-run, email delivery to the key's account, the exact alert thresholds, the auth requirement with a connect URL, and a pricing/quota model (first alert free, more are Pro). It stays silent on the non-idempotent behavior declared in annotations — an agent isn't warned that repeat calls may create duplicate alerts.

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 sentences, front-loaded with the core action and trigger criteria; the auth and pricing clauses are compact and relevant to whether the agent should call it. Slightly dense with commercial detail that a model may not need.

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 the mutation/safety profile and no output schema, the description supplies the missing pieces an agent needs: prerequisite (finished search + key), side effect (daily email), and trigger conditions. The main remaining gap is duplicate-alert/idempotency behavior and how to stop an alert.

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 0%, so the description carries the burden for the single searchId parameter. It adds some meaning by stating the search must be a *finished* search, but doesn't clarify the s_ prefixed ID format or what happens if the ID refers to an unfinished search.

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 ('Starts the otter's daily re-run of a finished search') plus the exact trigger conditions for the alert (5% or $50 drop, cheapest pick disappears). Strong on what it does, but it never names the closely related siblings (watch_booking, watch_similar_homes, watch_booking) that an agent would have to choose between.

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 implies the precondition that the search must already be 'finished' and that a key is required, which guides invocation. But it gives no explicit when-to-use/when-not guidance and does not contrast itself with watch_booking or watch_similar_homes, which are the obvious alternatives for watching prices.

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?

Extremely rich beyond annotations: states it needs a key, is free/unlimited, emails the account, reads rates every morning, uses 5%/or $50 thresholds, reminder cadence 7/3/1 days, what it retains vs. discards, whole-home edge case, and that it never books or cancels. This is consistent with readOnlyHint=false (it creates a watch) and destructiveHint=false.

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 long narrative wall with many tangential details (thresholds, reminder cadence, whole-home calendars, public track record) that crowd out the core action. The opening is reasonably front-loaded, but overall it is over-verbose and hard to scan.

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 complex, no-output-schema tool it covers the lifecycle well: what happens on the first read, on a drop, on a closing watch, and the whole-home edge case. The main gap is that notification/return behavior is described narratively rather than structurally, but an agent has enough to call it correctly.

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% for both parameters, so the schema already documents confirmation text and paidUsd. The description reinforces that confirmation is the pasted email text but adds no format/syntax beyond the schema. 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?

The opening states a specific verb+resource: watch a stay already booked with free cancellation, and explains it emails when a cheaper rate appears. It is clearly distinguishable from set_alert and watch_similar_homes by scope (an existing booking vs. a generic alert / nearby homes), 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?

It gives a clear triggering condition: 'For a stay already booked with free cancellation: pass the confirmation email's text.' That tells the agent exactly when this applies. It does not explicitly exclude set_alert or clarify the boundary against watch_similar_homes even though it describes that behavior inline.

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 annotations: discloses the trigger thresholds (5% or $50 under), the alert channel (email), the expiry (free-cancellation deadline), that the initial live search takes 30-90 seconds, that it isn't counted as a trip, that it requires the same key the booking was watched with, and that it costs nothing. It also rules out a misleading expectation by stating a find is never the same home cheaper.

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 precondition and effect, and every clause carries information (threshold, timing, ordering, cost). It is a dense single block with heavy parenthetical nesting, which slightly hurts scanability but wastes no sentences.

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 one-parameter tool with no output schema, the description supplies everything an agent needs: the triggering condition, what the user will observe (email), how long the first call blocks, cost, and the follow-up action ordering.

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 already 100%, so the baseline is 3. The description adds real value by noting the tool 'needs the key the booking was watched with', clarifying that bookedId must come from the same credential context as the original watch — a constraint not captured 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 and resource ('watches other verified whole homes nearby for the same dates and party') plus the outcome (emails the account on a qualifying price drop). It is unambiguously distinct from watch_booking and set_alert, which are the nearest siblings.

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 precondition chain: the home must already be booked via watch_booking and the first morning's read must have found the nights taken. It also states the required workflow ordering — book the new home first, cancel the original second — so the agent knows not to advise cancellation upfront.

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