HotelRefund Price Tracker

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?

Annotations already mark the tool as read-only, and the description goes far beyond that by detailing the computed booking_guidance fields, the seasonality caveat, the level-shift handling, and the awaiting_first_price edge state. This gives the agent a faithful model of what the tool returns and how it can behave.

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 long but front-loaded and well organized: core output first, then the booking signal, then URLs, then seasonality, then the edge case. Every sentence carries useful information, though some clauses are dense and could be tightened without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining the return payload, and it does so in detail: price stats, booking_guidance components, track_page_url, report_url/csv_url, seasonality semantics, and the awaiting_first_price state. This is sufficient for an agent to call and interpret the 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 description coverage is 100%, so the baseline is 3. The description largely repeats what the schema already states for tracking_id and language, adding no new param-level detail such as validation rules, additional formats, or default behaviors 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 opens with a specific verb and resource: 'Return the recorded prices for one tracking (tracking_id)'. It enumerates the exact outputs, making the tool's scope clear and distinct from siblings like list_tracked_hotels, track_hotel_price, and get_hotel_price_calendar.

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 that this tool is for retrieving a single tracking's full price history and supporting evidence artifacts. It even mentions practical use cases (best-price-guarantee claims, refund requests, check-in negotiation), but it does not explicitly name alternative tools or state when not to use this one.

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 already declare readOnlyHint=true, and the description adds substantial behavior beyond that: it returns only catalog fields (name, address, stars, rating, review count), never prices, resolves the city to 'the best catalog match', and surfaces other_city_matches when several cities match. These traits — catalog-only, no-pricing, ambiguity handling — are not visible in 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?

Four sentences, each carrying distinct weight: purpose, exclusions/alternatives, parameter usage, and ambiguity handling, with the core purpose front-loaded. It is slightly longer than strictly necessary because the multi-language input hint partly duplicates the schema examples, but nothing is wasted.

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 compensates by naming the returned fields and the other_city_matches disambiguation field, and it explicitly rules out prices so an agent won't expect pricing data. The only gap is unspecified behavior when no city or hotel matches, but for this complexity level the coverage is strong.

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 adds real value on top: multilingual input support ('Korean, Japanese, Chinese or English'), the trigger condition for the hotel filter, and a concrete disambiguation flow for city_id. The only redundancy is that the schema examples already illustrate the multi-language city forms.

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 — 'Resolve a hotel to the agoda_hotel_id that track_hotel_price needs' — giving the tool a crisp identity. It further distinguishes itself from siblings with 'not a hotel search engine' and 'no prices — for prices, track the hotel or use list_hotel_deals', so an agent can tell it apart from the price-focused tools in the sibling 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?

Explicitly routes between alternatives: lookup/ID resolution here, prices via track_hotel_price or list_hotel_deals, and gives the canonical workflow 'search_hotels → track_hotel_price → get_price_history'. It also conditions parameter usage ('when the user named a hotel, the hotel filter') and explains the city_id override path for ambiguous matches.

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?

Adds substantial context beyond annotations: idempotent duplicate handling, automatic periodic price checks, lasting state, timezone-aware check_in validation, and the fact that it is free/anonymous/public. This aligns with and enriches the idempotentHint, openWorldHint, and readOnlyHint=false 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 description is long but every section earns its place: the date/timezone caveat prevents avoidable errors, the stateful behavior explanation is essential for correct use, and the response URL semantics aid later steps. It could be tightened, but it is well-organized and not padded.

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 stateful tool with no output schema, the description fully covers what an agent needs: required inputs, response fields (tracking_id, booking_url, track_page_url), idempotence, side effects, and usage context. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic detail: check_in must be 2026-09-23 or later because of Asia timezone lead, agoda_hotel_id must come from search_hotels, and language influences track_page_url. This goes beyond the schema's basic field 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?

Description states a specific verb and resource: 'Start tracking one hotel ... for one stay' using agoda_hotel_id from search_hotels. It clearly differentiates itself from siblings by emphasizing it creates lasting state and produces tracking_id, which get_price_history later consumes.

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 says this is the tool that creates lasting state and can be queried later with get_price_history, and that agoda_hotel_id comes from search_hotels. It also covers when to use it: before booking to catch a drop and after booking a refundable rate to see when rebooking pays off.

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