HotelRefund Price Tracker

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

With readOnlyHint already covering safety, the description goes well beyond it: it enumerates the actual evaluation rules (same-site drops, ended guarantees, currency mismatch, four matching conditions) and discloses the privacy trait that 'no personal data is needed or accepted'. It also describes the output shape in detail, which matters because no output schema exists.

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 purpose before the rule list, and nothing is gratuitous. The rule enumeration is dense but each clause maps to a real decision the tool makes, so it earns its space.

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 14-parameter, nested-object tool with no output schema, the description carries the return-value burden well (verdict, deadline, payout, difference, tracking evidence). Minor gap: it does not say what verdict values look like or how deadlines are computed, which an agent might want before interpreting results.

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. The description still adds meaning by tying parameters to semantics the schema alone does not convey — e.g. tracking_id as independent timestamped evidence, currency mismatch as a rejection reason, and booked_date deciding old Expedia bookings.

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 (check) and resource (best price guarantee claim) and pins the exact rule set it applies — HotelRefund Refund Report rules. It is clearly distinguishable from siblings like get_refund_guide (guidance) and draft_refund_request (drafting), without needing to open 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?

The scope 'lower price found after booking' implies the usage context, and the tracking_id sentence hints at when to supply extra evidence. However, it never explicitly says when to use this versus get_refund_guide or draft_refund_request, nor states any exclusions or prerequisites. Adequate but leaves 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 cover only readOnly/openWorld, so the description must add the substance, and it does: it discloses the return shape (a short chat/form message plus a full letter), the PDF side-effect available at refund_report_url, the reject rule that confirmation number and guest name are not accepted and render as placeholders, and the enrichment behavior when tracking_id is supplied. These are exactly the traits an agent cannot infer from annotations or schema.

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 dense sentences, front-loaded with the action and the four kinds before the operational caveats. Every clause carries information, though the kind-specific parentheticals make the opening sentence long enough that an agent must parse carefully.

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 25-parameter, no-output-schema tool, the description covers the important gaps: it explains the four modes, the price_guarantee preconditions, the placeholder rule for identity fields, and the response contents so the missing output schema is less damaging. It is slightly thin on the minor parameters and does not spell out the full structure of the two returned texts.

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 72% schema coverage the schema already carries a lot, yet the description adds real cross-field semantics the schema does not: booked_on/paid_total/lower_total/lower_price_site are grouped as price_guarantee requirements, new_check_in may be omitted to ask which dates are possible, and tracking_id injects recorded Agoda prices into specific letter types. Remaining parameters (city, room_type, adults, cancellation_policy, breakfast) are left unexplained in 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?

Names a specific action (write the text of a request) and enumerates the four exact kinds supported, with a one-clause gloss for each (claim for the price difference, date_change, goodwill_refund for non-refundable bookings, checkin_request citing a lower price). An agent can distinguish this from siblings like get_refund_guide or check_refund_claim without 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?

Gives clear per-kind selection guidance, including the critical precondition that only goodwill_refund applies to non-refundable bookings and that price_guarantee is a claim against the booking site rather than the hotel. It never states when NOT to use this tool or points to a sibling alternative, 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the exact pricing basis (total incl. taxes and fees, 2 adults, standard rate), that room type and breakfast are reported only when Agoda supplies them, that nothing is stored, and two operational constraints — a 30-minute cache and a shared daily budget for live lookups. That last pair is exactly the kind of rate-limit context an agent needs.

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-loads the core purpose and scope in the first sentence, then layers use case, output hints and caching. Three sentences, no filler, though the opening sentence is dense and the cache/budget detail could be tightened.

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 return-value burden and does so: it names the total with taxes and fees, room type, breakfast, and agoda_url as evidence. Combined with the read-only annotations and full schema coverage, an agent has everything needed to call and interpret this 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%, so the schema already documents all five parameters, including the currency list and the 'use the currency the booking was paid in' instruction. The description adds only the agoda_hotel_id provenance (search_hotels) and the fixed 2-adult/standard-rate context, which is useful framing but largely duplicative of 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 (Read) and resource (Agoda price for one hotel and one stay) with the exact scope of the reading: whole-stay total with taxes/fees, 2 adults, standard rate. This clearly distinguishes it from get_price_history, get_hotel_price_calendar and track_hotel_price.

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?

Explicitly names the situation (after booking elsewhere to see whether Agoda is now cheaper) and the downstream consumer (check_refund_claim), plus the comparison use case. The 'one-time reading — nothing is tracked or stored' line implicitly rules out the tracking siblings, so the agent knows when this is the wrong tool.

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 readOnlyHint and openWorldHint, and the description strengthens these by disclosing background fetching, pending > 0, and the need to call again after ~3 seconds. It also explains what fields are returned, including is_tracked and track_page_url, without contradicting 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?

Every sentence earns its place: purpose, return contents, differentiation, async behavior, and defaults are all packed compactly. The description is front-loaded with the core purpose and remains readable despite carrying substantial behavioral detail.

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 read-only calendar tool with a full input schema and no output schema, the description sufficiently covers return values, pending behavior, defaults, and the distinction from related tools. 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 100%, so most parameter meaning is already provided. The description adds value by giving the default window (28 days), 1 night, and 2 adults context, and by clarifying the relationship between agoda_hotel_id and search_hotels. This goes beyond the schema without duplicating 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?

Description uses a specific verb ('Show') and resource ('what one hotel costs on Agoda for each check-in date in a window'), clearly distinguishes itself as a date cross-section rather than a time series, and references the source of agoda_hotel_id (search_hotels). It differentiates well from siblings like get_price_history and track_hotel_price.

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 explicitly frames the use case ('what if I move my dates' view), states that this is not a time series, and directs users to track_hotel_price when they want to keep watching a date. This provides clear when-to-use and when-not-to-use guidance.

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 readOnlyHint/openWorldHint annotations: it names the awaiting_first_price and no_rates states and explains what each means (sold out/not open, re-checked daily), explains what report_url/csv_url are for (price-guarantee evidence, refunds, check-in negotiation), and warns that seasonality is on a separate scale from the tracked prices.

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 core return payload is front-loaded in the first sentence, but the description runs long and dense, packing fallback states, URL purposes and seasonality caveats into an undifferentiated block. For a two-parameter read tool with a fully documented schema, some of this prose is surplus rather than load-bearing.

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 full burden of describing returns, and it does so thoroughly — shape of the price series, the booking_guidance signal and its components, generated headline/summary text, export URLs, optional seasonality, and degraded states. An agent has everything needed to call and interpret it.

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 in the schema and the baseline is 3. The description adds only marginal meaning beyond that — it says language governs booking_guidance text and track_page_url, which the schema already states, and adds no format or sourcing detail for tracking_id.

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 recorded prices for one tracking') and immediately scopes what is returned (current, first, lowest, highest, change, trend, time series). The tracked-record scope distinguishes it implicitly from siblings like get_current_price and get_hotel_price_calendar without needing to name them.

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 the description of the tracked-record scope and the awaiting_first_price / no_rates states, which tell the agent when results are meaningful. However, it never explicitly says when to choose this over get_current_price or get_hotel_price_calendar, and there are no stated exclusions or prerequisites beyond the tracking_id origin in 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?

Beyond the readOnlyHint=true annotation, the description discloses two useful behaviors: with no arguments it returns a listing of all guides with topic ids and one-line summaries, and the language parameter only changes the returned URL while the guide text stays English. This adds concrete behavioral context that an agent cannot infer from the schema or 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?

The three functional parts are front-loaded and each sentence earns its place: main action, no-arg listing behavior, and language behavior. The list of topics in the first sentence is a bit long but provides useful scoping without redundancy.

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 covers what the agent needs to know: it returns full guide text, a listing mode with topic ids and summaries, and a language-dependent URL. Combined with the readOnly annotation and detailed schema, nothing critical is missing for a two-optional-parameter read-only 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?

The input schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds value by explaining the no-arg behavior for topic (list all guides) and clarifying that language controls only the URL, not the guide text, which goes beyond the schema's individual parameter 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 opens with 'Return the full text of one HotelRefund reference guide', which is a specific verb+resource. It enumerates the covered topics and is clearly distinct from sibling tools like get_hotel_price_calendar or get_price_history, which address pricing data, not refund guidance.

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 clear usage context: it is for guides about bookings that already exist, and instructs 'Call without arguments to list every guide'. It does not explicitly say when not to use this tool or name sibling alternatives, but its context is sufficient to differentiate it from the pricing-focused siblings.

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 adds behavioral context by listing the specific operational metrics reported, including the 'remaining shared daily registration allowance for AI clients.' This goes beyond the annotation by explaining what the read-only status call exposes without suggesting any side effects.

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 two sentences with no filler. The main purpose is front-loaded, followed by a compact enumeration of returned metrics and a practical usage note. Every sentence earns its place.

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 zero-parameter status tool with no output schema, the description is complete: it states what the tool reports, the scope of coverage, and when to invoke it. Nothing essential is missing for an agent to decide to call it.

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 has zero parameters, so parameter semantics do not carry risk. The description still adds value by detailing what the status call returns, satisfying the baseline for a no-parameter 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 uses a specific verb ('Report whether the tracker is running and what it covers') and then enumerates the concrete data returned: hotels, cities, tracked stays, price checks, and registration allowance. This clearly distinguishes it from the sibling tools, which are about prices, deals, hotels, or tracking actions rather than service status.

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 explicitly states when it is useful: 'before starting a longer flow, or to confirm the server is live.' This gives clear usage context, though it does not explicitly name sibling alternatives or state when not to use 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 carry readOnlyHint and openWorldHint; the description adds genuinely new behavioral traits: an uncached city 'is fetched live at most once per 6 hours' (caching/freshness), a 5% discount filter, and a per-city cap of 6 deals. It doesn't describe the full response shape or city-mode sort order, but the added context is substantive.

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 dense sentences, each earning its place: deal definition, worldwide mode, city mode with caching, and output fields. The methodology detail ('1-night stay about two weeks ahead (2 adults, USD)') is specific rather than padded, though the density makes it slightly heavy relative to a front-loaded one-liner.

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?

Covers both invocation modes, caching behavior, filter thresholds, and the key output fields (booking_url, image_url). With no output schema, the description could name the full response field set and city-mode ordering to be fully complete, but the deal-definition sentence implicitly carries much of the output semantics.

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?

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 — 'List today's biggest observed hotel discounts' — and goes further by operationally defining what counts as a deal: Agoda's live rate vs its own listed rate, 1-night stay two weeks ahead, 2 adults, USD, with a 5% discount floor. This precision distinguishes it from siblings like search_hotels (hotel search) and list_tracked_hotels (tracked 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, actionable mode-based guidance: 'Without arguments, returns the single best deal per city' and 'With city ... or city_id, returns the current deals for that city (up to 6)'. It stops short of a 5 because it never explicitly names alternatives or when-not-to-use conditions relative to siblings.

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 readOnlyHint is already provided by annotations, and the description adds useful behavioral context beyond that: all trackings are public, results are sorted by biggest price drops first, and each item includes price change, stay dates, and URLs. This helps the agent understand what to expect without contradicting 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?

The description is a single focused sentence that front-loads the main purpose and then packs in the key output details. Every clause adds useful information with no repetition or 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?

Given that there is no output schema, the description compensates well by naming the returned fields and the sort order. With the parameters fully documented in the schema and read-only behavior in annotations, nothing critical is missing for an agent to invoke this tool 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 coverage is 100% for both parameters, so the baseline is 3. The description adds extra meaning by clarifying that the language parameter applies to track_page_url, and by indicating that limit controls how many tracked hotels are returned. This is helpful beyond the schema alone.

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 clearly states the tool lists currently tracked hotels, with a specific verb and resource. It differentiates itself from siblings like track_hotel_price and list_hotel_deals by focusing on tracked hotels, and it adds useful specifics like price change and sorting.

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 clear context for when to use this tool: when you want to see publicly tracked hotels and their price-drop info. It does not explicitly name alternatives or exclusion conditions, but the phrasing makes the intended use obvious.

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 only declare readOnlyHint/openWorldHint; the description adds substantive behavior: it returns catalog entries (name, address, stars, rating, review count), returns no prices, resolves the city to the best match, and surfaces other_city_matches for multi-city ambiguity. It stops short of auth or rate-limit context, so it is not a full 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?

Front-loads the core purpose and the flow, and every sentence carries information (return fields, price exclusion, language support, city_id fallback). It is somewhat dense and long for a 4-param lookup, which keeps it from a 5.

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 return-value burden and does so — listing the returned fields and the other_city_matches fallback — plus the typical call chain. Nothing an agent needs to invoke this correctly 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 baseline is 3, but the description adds real semantics beyond the schema: accepted languages (Korean/Japanese/Chinese/English), that city is resolved to the best catalog match, that city_id overrides city, and that a hotel name alone still requires a city.

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+resource ('resolve a hotel to the agoda_hotel_id') and explicitly disclaims what it is not ('not a hotel search engine'), naming siblings track_hotel_price and list_hotel_deals. An agent can distinguish this from list_hotel_deals without opening either 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 explicit when-to-use ('lookup step, not a hotel search engine... for prices, track the hotel or use list_hotel_deals') and an end-to-end flow (search_hotels → track_hotel_price → get_price_history). Alternatives and the condition that selects them are named.

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