SlickTrip

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

Annotations already declare non-read-only, idempotent, non-destructive. The description adds real context beyond them: the list keeps searching and alerts when a fare drops under the limit, the tool returns a bucket_id, sensible defaults are applied and should be surfaced to the traveler, and the list can later be changed via update_bucket_list. It does not mention cost, rate limits, or alert frequency, which keeps it short of a 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?

Four short paragraphs, each earning its place: trigger and effect, call-vs-offer rule, defaults policy, and the exclusion/alternative. Front-loaded with the caller's situation and example, with no 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?

For a 31-parameter mutation tool with full schema coverage and an output schema, the description covers everything an agent needs: when to call, what it produces (bucket_id), what defaults to use, how to revise later, and which siblings handle the cases this tool does not.

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 policy-level guidance the schema cannot: use what the traveler gave, fill the rest with defaults (every month on sale, 3-10 nights, 1 traveler) and tell them what was assumed. It does not walk through individual parameters, which is fine given the rich 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 (creates a bucket list that watches a route and alerts on price drops) and gives a concrete example request. It also distinguishes itself from search_flights, track_flight, and update_bucket_list by name, so an agent can route correctly without opening another 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?

Explicit when-to-use (traveler wants alerts over flexible dates, and even 'call it now' vs 'offer it first' depending on whether they asked), and explicit when-not-to-use (fixed dates go to search_flights then track_flight). Alternatives are named with the condition that selects them.

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 beyond the annotations (readOnlyHint=false, idempotentHint=true) by explaining the ongoing behavior: SlickTrip keeps re-searching stays of the given length across the chosen months and alerts when the per-night bar is cleared, and it returns a bucket_id. Missing are operational limits an agent might hit — caps on number of watches, how/when alerts are delivered, or cost — which keeps it off a 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?

Four tight sentences: what it does first, return value second, decision rule third, exclusion last. No filler and no repetition of schema 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?

With 11 parameters, an output schema present, and full annotation coverage, the description carries only the parts structured data can't: the alerting model and the call/offer policy. It leaves out limits on how many watches exist and what an alert looks like, minor gaps for an otherwise complete definition.

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, but the description adds real meaning by explaining how parameters combine into a search: "given length" (nights) across "the chosen months or date window" (months vs start_date/end_date) with a "per-night bar" (max_price_per_night) on a place or "one named hotel". It frames the semantics rather than restating field text.

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 — a flexible-date hotel watch on a place or a single named hotel — and immediately distinguishes it from fixed-date tracking by naming search_hotels and track_hotel as the alternative path. An agent can route correctly 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?

"When the traveler asks to be alerted, call it now; otherwise offer it first" gives an explicit call-vs-offer decision rule, and "Not for fixed dates (search_hotels, then track_hotel)" names the exclusion and the sibling chain that replaces 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=true and destructiveHint=false, so the safety profile is covered. The description adds useful non-annotation context: the result is a set of sellers (airline direct and agencies) each with price and an external checkout link, which sets expectations for an open-world read. It does not add auth, rate-limit, or freshness/caching details, so it falls short of a 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?

Three tight sentences: purpose first, then the prerequisite constraint, then the exclusions. Every clause carries routing or prerequisite information, and nothing is repeated from the schema beyond necessary framing.

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?

Annotations cover the safety profile, the output schema covers return values, and the single parameter is fully documented in the schema. Combined with the description's explicit prerequisites and alternatives, an agent has everything needed to invoke this 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?

With 1 parameter at 100% schema description coverage, the schema already documents itinerary_id, and the description largely restates it (one-way from search_flights, round trip from search_return_flights). The only added nuance is the word 'complete', which is already implied by the schema wording, 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+resource: retrieving the sellers offering a chosen itinerary, with each seller's price and checkout link. It explicitly names the sibling tools it derives from (search_flights, search_return_flights) and the one it is not (track_flight), so an agent can distinguish it 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 an explicit trigger ('when the traveler wants to book flights they have chosen'), an explicit exclusion ('not for an outbound alone – choose a return first'), and an alternative for a different intent ('not a price watch (track_flight)'). The when/when-not/alternative triad is fully covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavior: it reads from 'SlickTrip's records' and 'never runs a new search', which tells an agent the call is cheap/instant and won't refresh live prices, and it previews the return content (drops, rises, new lows, sent alerts). Missing only finer traits such as record staleness or result volume.

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 use case and scope are front-loaded before the return summary and the sibling redirect. It is a dense run-on covering many clauses; each is informative, but the parenthetical example phrase could be trimmed without loss.

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 aggregate tool with one optional parameter and an existing output schema, the description covers scope, data source, no-new-search semantics, time window, and the sibling alternative. Nothing an agent needs to invoke it correctly is absent.

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 since_hours already carries type, default, min/max and the '24 for a daily check' guidance. The description only reuses 'in the last since_hours' when framing the alert window, adding little beyond the schema, 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?

The description opens with a specific verb and resource: 'routine check of everything the traveler watches', then enumerates the covered entity types (flights, bucket lists, hotels, seat watches). It explicitly contrasts with the sibling watch_details for single-watch lookups, so an agent can route 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?

It names the triggering scenarios ('daily scheduled check', 'anything new on my watches?') and states the alternative: 'For one watch in full, use watch_details.' Both the when and the when-not are 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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the return shape (cheapest first, airline, stops, search_url) and the pricing mode switch (traveler's exact dates vs each destination's own cheapest dates). It stops short of covering pagination or rate-limit behavior, which is minor here.

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 tightly written sentences, front-loaded with the use case and examples, then the return/pricing behavior. Every clause carries information the agent needs; nothing is repeated from the schema or annotations.

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 a 12-parameter schema with full descriptions, rich annotations, and an output schema, the description is nearly complete: it establishes purpose, usage, return content, and the key date-driven pricing behavior. It does not mention notable optional controls like max_price_usd or user_request, but those are thoroughly documented in the schema and output schema is present, so the omission is small.

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 earns an extra point by explaining the semantic consequence of depart_date/return_date: when supplied, all destinations are priced on those dates; when omitted, each destination is priced on its own cheapest dates in the coming months. That is genuine meaning beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('cheapest place to fly from somewhere', 'ideas for where to go') and explicitly scopes it as an alternative to a trip where the destination is already chosen. The concrete example utterances make the purpose unmistakable without requiring 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?

It clearly defines when to use this tool ('the traveler wants the cheapest place to fly from somewhere... instead of a destination they already chose') and backs it with realistic traveler quotes. It does not name the sibling alternative (search_flights) explicitly, so the when-not is implied rather than enumerated.

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, and non-open-world, so the safety profile is covered. The description adds real behavioral context beyond that: it explains the resolution granularity (one airport vs. all airports in a city) and that the returned code is meant to be fed into origin/destination fields. It stops short of describing result size or fallback behavior on no match.

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 compact sentences, front-loaded with the usage trigger, then the behavior, then the exclusion. No filler and nothing redundant with structured fields.

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?

Although an output schema exists (so return shape needn't be documented), the description still conveys the practical payload semantics an agent needs: the code to use, and the airport set a city code covers. With fully documented params and annotations, nothing essential 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, and the description goes beyond it by clarifying that 'query' accepts a place name or a code and by describing how the query is interpreted (single airport, whole city, or code-to-coverage). It adds meaning not present in the schema's field titles.

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 ('matches a place name or code') and the concrete output ('returns the code to pass as origin or destination'), which cleanly separates it from siblings like flight_lookup and search_flights. An agent can identify its role 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?

Explicitly says when to use it ('before searching' when unsure of a code) and when not to ('Not needed for well-known codes like JFK or LHR'), with a concrete example. This is close to ideal routing guidance for a lookup/resolution 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 declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds real behavioral context beyond that: the exact payload fields (departure/arrival times, airline, aircraft, stops) and a negative disclosure that prices are not returned, which prevents misuse. It stops short of volume/pagination or error-shape notes.

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: trigger first, output description second, exclusion and alternative last. No restatement of the title or filler, and every sentence affects selection or invocation.

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 full annotation coverage, the description supplies exactly what structured fields cannot: when to choose it over search_flights/route_airlines, what the result contains, and where its output feeds downstream tools. Nothing essential 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 description coverage is 100% and the parameter docs are unusually rich (city codes, underscore joins, unknown_place errors, user_request quoting rules), so the schema carries the load. The description adds no parameter-level detail beyond the implicit route/date framing, which is the expected baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: which flights operate on a route on a given date, plus what is returned (times, airline, aircraft, stops). It explicitly distinguishes itself from search_flights by saying it returns no prices, so an agent can separate it from the price-oriented siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit triggering conditions (traveler wants flights on a route/date) and a chaining rationale (needed to obtain a flight number for seat_availability or track_seats). It also names the alternative for pricing (search_flights), covering when-not-to-use.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations do not: text alerts only work if a phone is verified on the site. It does not mention caching or refresh behavior, but that is minor given the annotations and output 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?

A single sentence, front-loaded with the usage trigger before the field enumeration, with no filler. The trailing colon-list is long but every item maps to real returned data, so it 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?

With an output schema present, the description need not document return values, and it instead spends its words on the trigger, the contents, and the phone-verification prerequisite for text alerts. Nothing an agent needs to call 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Nothing in the description misleads about inputs, and the field list it does give describes the response rather than arguments.

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 enumerates exactly what the tool returns — name, member since, working alert channels, plan and its free limit, and watched-item counts — which lets an agent distinguish it from update_account and the list_tracked_* siblings. The verb is only implicit (carried by the name 'get'), so it falls just short of a full verb+resource statement.

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 two concrete triggers: 'before offering text alerts' and 'when the traveler asks about their account'. That is clear usage context, but no when-not guidance or explicit routing to update_account as the alternative is provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: the link lands preconfigured without a search, flights links can include a track_url that starts tracking on arrival, and bucket lists save on arrival.

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 front-loaded sentence with no obvious filler, which is efficient. However, the nested parenthetical about bucket_list links saving the list for whoever opens it and 'so never send one' is ambiguous and makes the routing condition harder to parse.

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

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

Given the tool's complexity, full schema coverage, annotations, and an output schema, the description covers the main link kinds and the key no-search landing behavior adequately. Its main remaining gap is weak differentiation from sharing siblings, not missing operational details.

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 26 parameters are already richly documented by the schema itself. The description adds a useful kind-to-page mapping and explains the track_url effect for flights, but it does not add parameter syntax or constraints 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 action: builds a link that lands the traveler fully configured without running a search, and enumerates flights, bucket_list, hotels, and seats variants. It is clear what the tool does, but it does not distinguish itself from sharing-related siblings such as share_link or shared_trip.

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 conditions: continuing on slicktrip.com, sending a flights or hotels search, or when the account is not connected. However, it never names share_link/shared_trip as alternatives, and the warning about bucket_list links ('so never send one') is ambiguous, leaving routing among sharing tools unclear.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context on top: the result is a multi-seller list including the hotel's own site, each entry carries a stay total and a link that leaves the app to open the seller's checkout — which is exactly the openWorld behavior an agent should anticipate. It does not mention auth requirements or result limits, so it stops short of a 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?

Three sentences, each load-bearing: trigger, payload description, input provenance, then the sibling exclusion. The purpose and the 'when' are front-loaded before any 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?

With an output schema present the description need not explain return fields, yet it still characterizes the result well enough to set expectations. Trigger, inputs, provenance, and sibling differentiation are all present for a simple two-parameter read 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 100% and both properties are already documented as coming from search_hotels, so the description's 'Takes the search_key and hotel_id from search_hotels' largely repeats the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 action (retrieve every seller quoting a given hotel for the searched dates), the resource (hotel booking sellers), and the payload shape (stay total plus a checkout link per seller). It also distinguishes itself from the near-named sibling booking_options and from track_hotel by explicitly disclaiming price watching.

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 opens with an explicit trigger ('Use when the traveler wants to book a hotel from search_hotels'), states the prerequisite source for both inputs, and names an exclusion ('Not a price watch (track_hotel)'). An agent knows both when to call it and when not to.

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, openWorldHint and destructiveHint false, so the safety profile is covered. The description adds the data-provenance dependency (both arguments must come from a prior search_hotels call) and the routing constraint on booking links, but no rate limits, caching, or failure modes. Since an output schema exists and annotations handle safety, this is a genuine but modest addition.

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 trigger condition before the alternatives and prerequisites. The mid-sentence enumeration of returned fields is slightly list-heavy but every item is differentiating information, not 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?

An output schema exists so return values need no prose, annotations cover the safety profile, and the description covers trigger, prerequisites, and the two adjacent siblings. Nothing an agent needs to call 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 description coverage is 100% and both param descriptions already say 'from search_hotels', so the description's 'Takes the search_key and hotel_id from search_hotels' largely repeats the schema. It adds the useful implicit constraint that these are search-scoped, not global IDs, but no format or validity details. 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?

Names a specific verb+resource (fetch details/photos/rooms/rating for ONE hotel) and enumerates the payload returned, so the agent knows exactly what it gets. It explicitly distinguishes itself from hotel_price_calendar (prices across dates) and hotel_booking_options (links).

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?

States the trigger condition ('traveler asks for details, more information, photos, rooms or description of one hotel'), the alternative to use for dates/prices, and the sibling for booking links with a gating condition ('call that only when they say book'). Prerequisites for both params are given.

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, so the safety profile is covered. The description adds real context beyond them: the call requires a signed-in account and spans months of results, which is not derivable from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler; the user-intent trigger is front-loaded, then the prerequisite, then the next step. Every clause 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?

Covers the intent, prerequisite chain and follow-up action, and an output schema exists so return values need not be explained. Only minor gap is the lack of explicit differentiation from the sibling price_calendar 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 hotel_id, start_month and end_month (including defaults and formats). The description only restates the hotel_id source, adding no new syntax or semantics. 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+resource+scope: 'one hotel's nightly price by check-in date across a span of months', and frames the user intent ('when is this hotel cheapest'). This clearly distinguishes it from hotel_details, hotel_booking_options and the generic price_calendar sibling.

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 trigger phrase, a required prerequisite ('Needs a hotel_id from search_hotels'), and a follow-up workflow ('Then search_hotels with the chosen dates to track it'). It does not, however, explicitly contrast with the sibling price_calendar, leaving some ambiguity for an agent choosing between the two calendars.

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, and openWorldHint=false, so the safety profile is covered. The description still adds real value by disclosing the payload contents (settings, best deals found so far, bucket_id) rather than just repeating 'list'. It doesn't mention pagination beyond what the schema's limit field implies, which is the only 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?

A single well-formed sentence that front-loads the purpose and then appends the return-value details and the sibling linkage. Dense but every clause carries information; no filler or repetition of the title.

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 safety profile and an output schema covering the return shape, the description only needs to state scope and purpose, which it does. The downstream bucket_id pointer is a genuinely useful addition for a tool in a large, mutation-heavy sibling set.

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 the name filter and the limit ordering ('newest first') are already documented in the schema. The description adds no syntax, format, or filtering hints beyond that, which is fine but earns only the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('see the flight and hotel bucket lists on the signed-in account') and enumerates what each entry contains, which cleanly distinguishes it from the add_*, update_*, and remove_* siblings. An agent can tell this is the read-side of the bucket-list family without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening 'Use to see...' plus the mention that entries carry the bucket_id consumed by update_bucket_list, remove_bucket_list, and share_link makes the read-before-mutate usage pattern clear. It stops short of explicit when-not-to-use guidance, but the alternatives are implied by naming the downstream 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: it is scoped to the signed-in account, it discloses that each itinerary is shown as current price versus price at tracking start, and it surfaces the IDs needed by mutation tools.

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 opens with the usage verb and then lists return contents without filler. The enumerated list is dense but every item is informative, though the sentence is on the long side for a one-parameter list tool.

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 explained, yet the description still calls out the account scoping, the price-comparison semantics, and the downstream ID handoff — precisely the context an agent needs to route and chain correctly. Nothing material 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 description coverage is 100%, so the single 'limit' parameter (1-200, newest first, default 50) is fully documented in the schema. The description adds no further parameter guidance such as pagination or default-ordering notes, 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 ('see the flight price alerts on the signed-in account') and then enumerates the exact contents returned: route, dates, cabin, alert settings, price deltas, and the search_key/fid identifiers. It also names the sibling tools that consume those identifiers, so the agent knows how this read tool fits the tracked-flights workflow.

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 opening clause 'Use to see...' gives a clear when-to-use context tied to the signed-in account, and mentioning stop_tracking_flight/update_flight_tracking implies the follow-up workflow. There is no explicit statement of when not to use it or a direct pointer to list_tracked_hotels/list_tracked_seats as alternatives, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lower; the description still adds value by scoping results to the signed-in account and disclosing the comparison semantics (current price vs. price when tracking began). It does not mention pagination or ordering beyond what the limit param implies.

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 purpose comes first and the field inventory follows. It is somewhat dense in its enumeration but every clause carries information.

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 needn't document return values, yet it still previews them and links to the downstream update/stop tools. Annotations plus the 1-param schema leave nothing an agent needs 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?

Only one parameter and its schema description is fully covered (default 50, range 1-200, newest first). The prose adds no parameter detail, which is acceptable given the schema does the work, 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 ('see the hotel price alerts on the signed-in account') and enumerates what the listing contains: stay dates, guests, current vs. starting price, and the tracking_id/hotel_id. The 'hotel' qualifier and account scoping cleanly separate it from list_tracked_flights and list_tracked_seats.

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 opening 'Use to see...' establishes the context of use and the trailing clause implicitly routes the agent to the update and stop tools by naming the IDs they consume. It never states exclusions or an explicit alternative (e.g., when to prefer this over hotel_booking_options), so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely useful context beyond that: results are scoped to the signed-in account, and the tracking_key it returns is the handle the update/stop tools take, which tells the agent how to chain calls.

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?

One sentence, front-loaded with the 'Use to see...' intent and no filler. It is dense and slightly run-on with its comma-separated field list, but every clause carries information.

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 listing return fields is not strictly required, and annotations cover the safety profile; the description still fills the remaining gaps (account scoping, tracking_key handoff). 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 description coverage is 100% and the single 'limit' parameter is fully documented in the schema (1-200, newest first). The description adds nothing about the parameter, so the baseline 3 for schema-carried semantics 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 ('see the seat alerts on the signed-in account') and enumerates the returned fields (flight, departure, cabin, watched seats, open status). This cleanly separates it from the sibling list_tracked_flights and list_tracked_hotels, which cover different tracked entities.

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 context ('seat alerts on the signed-in account') and implicitly routes the agent onward by noting the returned tracking_key is what the update and stop tools consume, which is a real workflow hint. It stops short of an explicit when-not or a named alternative 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 declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: every price is for one exact trip (fixed nights, cabin, traveler count, stops/airlines/times) and any guessed input invalidates the whole calendar. It also discloses the call-count budget and what the response expects downstream ('the answer tells you how to close'), which annotations 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?

Front-loaded and well structured: eligibility first, then what it returns, then preconditions, then exclusions and closing behavior. It loses a point for repetition — 'flexible within a period they named' and 'Do not choose a month/trip length for the traveler' appear twice, and the same prohibition is restated in the schema.

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 26-parameter tool with an output schema and rich annotations, the description covers everything an agent needs before calling: who it is for, which inputs are mandatory versus optional preferences, what must be asked rather than assumed, and the fallback path when inapplicable. Return-value detail is correctly delegated to the output schema.

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 100% schema coverage the schema carries the per-field detail, but the description still adds decision-level meaning: month and trip_length_days must come from the traveler and must not be guessed, and max_stops=0 changes the output to flag nonstop days. It does not explain interplays like depart_from/depart_to window semantics or user_request, which the schema handles.

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 (shows the cheapest fare for each departure day over a roughly two-month window) and pins down the exact traveler situation it serves: flexible within a named period, known trip length, wanting the cheapest days. It is immediately distinguishable from search_flights (fixed dates) and add_flight_bucket_list (no dates at all).

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 gives when to use, when NOT to use ('Do not call this tool when the traveler has given you dates ... Do not call this tool when the traveler has given no dates at all'), and names the substitute for each case (search_flights, add_flight_bucket_list). It also caps invocation frequency ('once, or twice at most, per answer') and specifies the pre-call information gathering (ask in one question, never invent a month or trip length).

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine non-structured context: no authentication required, and that results are alerts SlickTrip actually sent (a sent-history feed) rather than computed-on-demand prices. It leaves the freshness window (how far back "recent" reaches) undefined.

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?

One tightly packed sentence plus a short negating clause: the usage trigger, the data source, the category breakdown and the no-auth note all land up front with no 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, return values need no explanation, and the description correctly focuses on source, categories and auth. The only meaningful gap is the undefined recency window, which an agent would need to interpret "freshest" or set user expectations.

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 baseline is 4; there is no argument syntax for the description to clarify. It does usefully enumerate the category dimension of the result, which is the only knob-like concept here, but that belongs to the output rather than the input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource (the freshest price-drop alerts SlickTrip actually sent) and scope (by category: flights, hotels, seats, flexible routes), and explicitly contrasts itself with search tools. An agent can distinguish it from search_flights/search_hotels/price_calendar 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?

It gives a concrete usage trigger ("any deals right now?") and an exclusion ("Not a search"), plus the precondition that no account is needed. It does not name a specific sibling to use instead when the user wants a targeted search, so it falls just short of the full when/when-not/alternative triad.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds genuinely new behavioral context: the action cannot be undone and the caller should confirm first, which is a workflow requirement not encoded 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?

A single front-loaded sentence carrying purpose, parameter provenance, irreversibility, and a confirmation cue. No filler and nothing redundant.

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 destructive tool with annotations covering safety and an output schema covering returns, the description supplies the missing prerequisites and reversibility warning. Only the absence of alternative-tool routing keeps it from being fully 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 coverage is 100% and the single parameter's description already states it comes from list_bucket_lists, so the description largely repeats the schema. It adds no format, type, or validation detail beyond provenance. Baseline 3 is appropriate 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 names a specific action on a specific resource (stop a bucket list) and its title matches 'Remove a bucket list'. The verb 'stop' is slightly softer than the actual destructive removal, but the reference to bucket_id from list_bucket_lists anchors it clearly against siblings like add_flight_bucket_list and update_bucket_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?

It gives a clear precondition (obtain bucket_id from list_bucket_lists) and an operational instruction ('confirm first'), which is more than most definitions offer. It does not explicitly contrast itself with update_bucket_list or the add_* siblings, so it stops short of full when/when-not 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 declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description still adds non-trivial behavior the annotations do not: nonstop-first ordering and the fact that returned codes are the same codes the airline filters accept, which matters for chaining into a filtered search. It stops short of describing pagination or result size, so a 4 rather than a 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?

One dense sentence opening with the usage trigger, followed by a three-word exclusion. Every clause earns its place and the most decision-relevant information is 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?

An output schema exists, so return values need no explanation, and the description covers purpose, trigger conditions, ordering and the nearest competing tool. Only the error/edge path (unknown_place handling) is left entirely to the schema, which is a minor gap for a read-only lookup.

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 carry exhaustive guidance (airport vs city codes, underscore-joined multi-place, unknown_place errors, find_places fallback). The description adds nothing parameter-specific beyond the code-format hint implied by 'codes the airlines filters take', 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 ('the carriers on the route') plus the ordering rule ('nonstop ones first'), and explicitly distinguishes itself from a fare search. An agent can tell it apart from search_flights or flight_lookup 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 two concrete triggers ('the traveler asks who flies a route', 'before filtering by airline') and an explicit exclusion ('Not a fare search'), which routes the agent away from the fare/booking siblings. Nothing about when to reach for this tool 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 declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds real sequencing/behavioral context (search as soon as prerequisites are met, SlickTrip fills only what the traveler's words say and does not guess, results are cheapest-first with itinerary_id/search_url), but it does not disclose auth, rate limits, or error behavior beyond the unknown_place note in the 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?

Front-loaded with purpose and prerequisites, then alternatives and return shape. It is long, but justified for a 30-parameter agentic tool; the only redundancy is the closing sentence re-stating the add_flight_bucket_list guidance already given mid-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?

Given complexity (30 params, nested legs, open-world search) the description covers the full workflow: prerequisites, routing to alternatives, flexible-date syntax, and the shape/next-steps of results. With an output schema present, return-value detail is optional and its presence is a bonus, not a gap.

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 30 parameters thoroughly. The description partly restates this by listing origin/destination/depart_date/return_date and the query fallback, adding only light workflow framing rather than new parameter meaning; baseline 3 is appropriate when the schema carries the load.

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 (search) and resource (flights) and immediately scopes the behavior: one-way, round trip, two dates per direction, up to three airports per side. It also names the sibling it is not (add_flight_bucket_list) for the no-dates case, so an agent can route without opening schemas.

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 states the precondition (four traveler facts), what to do when they are missing (ask once, never guess dates or trip type), and the alternative tool when the traveler has no dates. It even handles the tempting edge case ('cheapest flight from Newark to LA') by requiring dates first.

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 this as a safe, read-only, idempotent, open-world search. The description adds useful behavioral context beyond that: results are cheapest first, include star class, guest rating, per-night and whole-stay price, hotel_ids, search_key, and search_url, and the search_key feeds track_hotel and hotel_price_calendar. It does not discuss failure modes or pagination, but the added return-format and follow-on-tool context is substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the use case, then return behavior, then filter scope, then a clear exclusion. Despite being dense, every sentence adds routing or behavioral value, and the sibling exclusion is placed where it is most useful.

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 18 parameters, full schema descriptions, an output schema, and rich annotations, the description supplies the remaining context an agent needs: when to use it, what it returns, how results are ordered, and which sibling handles a different case. 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 description coverage is 100%, so every parameter is already documented in the schema, including filter enums, ranges, and examples. The description adds only a high-level enumeration of filter categories ('price, stars, guest rating, property kinds, amenities, free cancellation, hotels or vacation rentals, bedrooms, sort') and does not add syntax or semantics beyond the schema. This meets the baseline for fully covered schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource (search hotels) plus the precise condition for use: known dates. It also distinguishes this tool from add_hotel_bucket_list for flexible-month searches, so the agent can route correctly 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?

It explicitly says when to use the tool ('traveler wants a place to stay for known dates') and when not to use it ('Not for flexible months'), naming the alternative sibling tool. No inference is required.

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, open-world, so the safety profile is covered. The description adds genuine workflow behavior beyond that: it consumes an existing itinerary_id, and the response carries a trip total plus a needs_leg flag that goes false once the trip is complete. That state-machine detail is the most valuable thing here and is not 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?

Four dense sentences, no filler, and the ordering is right: usage condition first, required input second, return semantics third, exclusion last. Nothing here restates the title or the annotations.

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 21-parameter tool with an output schema, the description covers the parts structured fields cannot: when in the booking flow to call it, that it must be called once per remaining leg, how filters scope, and what makes the trip 'whole'. Safety and parameter detail are already handled by annotations and the schema.

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% across 21 parameters, including long, well-illustrated descriptions for display, bag fees, price totals, and layover filters, so the schema carries the full per-parameter burden and baseline 3 applies. The description's one global clarification — 'Filters apply to the leg being chosen' — is useful scoping information, but it is not parameter-specific detail.

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 verb and resource (search return flights) and anchors it to a named sibling: 'Use after search_flights'. It also states the scope precisely — one call per remaining leg of a multi-city trip — which an agent could not infer from the name 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?

Explicit sequencing rule (after search_flights), explicit trigger (traveler wants a specific return, or the next leg), explicit cadence (once per remaining leg), and an explicit exclusion: 'Not needed for an outbound watch.' This routes the agent correctly against the large sibling set.

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 safety is largely covered. The description still adds real context the annotations cannot: the account/auth requirement and the reassurance that 'nothing is charged or changed', plus the shape of what comes back.

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 tight sentences, front-loaded with the purpose before the prerequisite and the routing note. It packs in a fair amount of detail about return contents, but no sentence is filler and the negative scoping ('Not for prices') lands last for emphasis.

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 query tool with an output schema, a complete annotations set and 100% schema coverage, the description supplies everything an agent needs: auth prerequisite, what the result contains, the natural follow-up tool, and what the tool is not for.

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 parameters (including the detailed origin/destination code rules and the user_request quoting behavior) are already fully documented in the schema. The description only restates that flight number, route and date are needed, adding no syntax or format detail beyond it — the baseline 3 for schema-covered parameters.

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 precise verb and resource with scope: 'see which seats are open right now on one flight'. It also distinguishes itself from siblings by naming track_seats as the follow-up and declaring 'Not for prices', so an agent can separate it from price_calendar, flight_lookup and list_tracked_seats without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the when ('see which seats are open right now'), the routing alternative ('Then track_seats to be told when a seat opens'), and an explicit exclusion ('Not for prices'). The only prerequisite, a signed-in SlickTrip account, is stated 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered structurally. The description adds real value beyond that: it discloses what the call surfaces (itinerary or bucket list plus current price) and the downstream intent (starting one's own watch). It omits anything about resolution failure on a bad/expired code, which is the only remaining behavioral 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?

Three tight sentences, with the trigger condition front-loaded ahead of the exclusion. Only the 'Takes the link or its code' clause is wasted, since it duplicates the schema description. No other 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?

An output schema exists, so return values need not be explained, yet the description still characterizes the payload (itinerary/bucket list + current price). With annotations covering safety and the schema covering the single argument, an agent has everything needed to select and invoke this 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% and the single parameter's description already spells out 'a slicktrip.com/share/<code> link, or just the code.' The description's 'Takes the link or its code' restates that verbatim and adds no format, validation, or normalization detail. Baseline 3 is correct when the schema carries the full parameter burden.

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 action ('open a shared trip') bound to a concrete trigger artifact (a slicktrip.com/share link) and says what comes back: the itinerary/bucket list plus its current price. It also explicitly names the sibling it is not (share_link), so an agent can separate ingest-a-link from create-a-link without reading 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 an explicit invocation condition ('Use when the traveler pastes a slicktrip.com/share link') and an explicit exclusion ('Not for making a link (share_link)'). The when-to-use and the alternative are both stated, not inferred.

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

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

The annotations already declare idempotency, open-world behavior, and non-destructiveness, so the description usefully adds privacy context: the link shows itinerary and price and nothing about the account. It also explains that the link is made once and reused, but it does not explicitly state account/sign-in requirements beyond implying them through the contrast with handoff_link.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the primary use case, then adds the key alternative and one important exclusion. Every sentence carries actionable information: purpose, link behavior, reuse, and handoff_link distinction.

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/idempotency traits, the description supplies the remaining selection context: what the link exposes, when it is appropriate, and which sibling to use instead. Nothing critical for correct invocation appears to be 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?

The schema has 100% description coverage for both optional parameters, so the schema already tells the agent what bucket_id and search_key mean and where to get them. The description reinforces the two supported resource types but adds no syntax, format, or selection detail beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: sharing a tracked route or flight bucket list as a public slicktrip.com link, equivalent to the site's Share button. It clearly distinguishes this from handoff_link and shared_trip-style behavior by naming what the link contains and what it does not contain.

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 explicitly says when to use this tool and when to use handoff_link instead for unwatched flights or hotels searches. It also gives a clear exclusion: never use a bucket_list handoff link because that saves the list for whoever opens 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 destructiveHint=true and idempotentHint=true, so the irreversible nature is partly covered. The description still adds actionable context beyond that: the irreversibility is stated in plain language and paired with a 'confirm first' instruction the agent can act on, though it says nothing about what state remains after removal (e.g., whether the route disappears from list_tracked_flights).

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 sentence that front-loads the purpose, then nests the two mutually exclusive scoping options, ending with the safety caveat. No filler and nothing an agent must read past to find the core action.

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 only two parameters, full schema coverage, an output schema, and annotations carrying the mutation/ idempotency profile, the description covers everything an agent needs: what it does, the two modes, the identifier source, and the irreversibility warning. Nothing material 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 description coverage is 100% – both search_key and fid are fully documented in the schema, including that fid preserves the route while targeting one itinerary. The description repeats the sourcing of both params without adding format or validation detail, so the baseline of 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 a specific verb ('stop price alerts') plus a precise resource and two levels of scope: a whole tracked route via search_key, or a single itinerary via fid. That scope distinction is exactly what separates it from siblings like update_flight_tracking (modify) and stop_tracking_hotel/stop_tracking_seats (other resources).

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 tells the agent where both identifiers come from (list_tracked_flights) and the consequence ('Cannot be undone; confirm first'), which is clear operational context. It stops short of explicitly naming the alternative to use when the intent is to edit rather than end tracking, so it is not a full 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?

Annotations already flag destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description goes beyond them by stating the action is irreversible and instructing the agent to confirm first, which is meaningful guidance for an agent acting on a user's behalf.

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 sentence that front-loads the action and scope, then adds the consequence. No wasted words and the parenthetical identifier hints are tightly embedded.

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 destructive two-parameter tool with full schema coverage, annotations, and an output schema, the description supplies everything an agent needs: action, scope options, identifier source, and the confirmation requirement.

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, and the description adds where tracking_id comes from and clarifies that hotel_id narrows the scope to one hotel. That provenance detail is useful orientation beyond the schema's own per-field text.

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: stop price alerts for a tracked stay or a single hotel within it. It clearly separates itself from track_hotel and update_hotel_tracking by naming the termination action and the two possible scopes.

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 context for when to call it (ending alerts on a tracked stay) and points to list_tracked_hotels as the source of tracking_id. It does not explicitly contrast with update_hotel_tracking or track_hotel, but the destructive framing makes the distinction inferable.

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 destructive=true, idempotent=true and readOnly=false, so the safety profile is mostly covered. The description still adds value beyond them: it states the action cannot be undone and requires confirmation, which the hints do not convey. Nothing is claimed that conflicts with 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 short sentences, front-loaded with the action and followed by the parameter source and the irreversibility 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?

For a one-parameter destructive tool with an output schema, the description covers what it does, where the parameter comes from, and the crucial irreversibility/confirm step. An agent has what it needs to call it correctly; only cross-references to the sibling stop/update tools are absent.

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 the single tracking_key parameter, and the schema already names list_tracked_seats as its origin, so the description largely restates structured data. Baseline 3 applies; no additional format or validation detail is supplied.

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 (stop the seat alert) and scopes it to one flight, which separates it from stop_tracking_flight and stop_tracking_hotel by resource. It does not name those siblings explicitly, but the resource word 'seat' plus the tracking_key reference makes the domain unambiguous.

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 context: use it to cancel a seat alert, and it points to list_tracked_seats as the source of the required tracking_key. It also adds a prerequisite ('confirm first'), which is real operational guidance. It stops short of naming the related stops/update tools for the other tracking types.

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 openWorldHint=true, idempotentHint=true, and readOnlyHint=false with destructiveHint=false, so the write/safety profile is partly covered. The description adds real behavioral context beyond that: alerts route to the account's channels, fire on a new low, 'any' fires on every move, and target_price_usd replaces alert_rule. It does not clarify persistence or how to undo the tracking, which is what stop_tracking_flight/update_flight_tracking presumably cover.

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 'Use to...' framing followed by trip-type branching, so the most important routing rule comes first. It is dense and slightly run-on, but nearly every clause carries a distinct routing or alert-behavior fact.

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 tracking-creation tool with 5 params, one required, full schema coverage, and an output schema present, the description covers the confirmation precondition, the per-trip-type ID requirement, alert channel routing, and the alert_rule/target_price_usd interaction. Nothing an agent needs to call it 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 the baseline is 3, and the description earns above that by explaining that itinerary_id's meaning shifts by trip type (outbound vs complete pairing) and that target_price_usd supersedes alert_rule rather than combining with it. It adds usable semantics the flat schema cannot express.

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 ('start price alerts on an itinerary from a search') and immediately differentiates from siblings like update_flight_tracking, list_tracked_flights, and stop_tracking_flight by describing it as the creation action. An agent can identify the tool's role 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?

Explicitly routes the agent by trip type: one-way uses any itinerary_id from search_flights, round trip uses either an outbound or a complete itinerary_id, multi-city needs a complete one. It names the sibling source tools (search_flights, search_return_flights) and the precondition that the traveler has confirmed, which is a strong when-to-use signal.

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 the safety profile (non-destructive, idempotent, open-world), and the description adds a genuinely useful side-effect disclosure: alerts are pushed to the account's channels when the price drops. It stops short of saying how channels are chosen or how failures surface, but it exceeds the annotation baseline.

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, no waste. Usage and prerequisite are front-loaded, and the consequence (alerts to account channels) follows immediately after.

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 and idempotency, the description only needs to cover prerequisites and post-call behavior, which it does. A brief note on what a repeated call does (idempotent re-tracking vs duplicate alert) would round it out.

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 hotel_id, search_key, search_url, alert_rule, target_price_usd, text and email are already fully documented in the schema. The description adds nothing about parameter syntax or defaults, 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: 'start price alerts on one hotel'. The word 'start' implicitly separates it from update_hotel_tracking and stop_tracking_hotel, but no sibling is named explicitly, so an agent must infer the boundary.

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?

Clear conditions: the hotel comes 'from search_hotels for those dates' and the action happens 'after the traveler confirms'. It gives no explicit exclusions or alternative tools (e.g. add_hotel_bucket_list, update_hotel_tracking), so routing is implied 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 this is a write (readOnlyHint=false), non-destructive, and idempotent, so the safety profile is covered. The description adds real behavioral context beyond that: alerts are delivered to the account's channels only when a watched seat opens, and the call should follow traveler confirmation. It does not say how alerts are later modified or stopped.

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 action and scope, with the mode options and the alert-delivery outcome packed in without filler. Nothing restates the schema verbatim and every clause carries information.

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, return values need no explanation, and the annotations carry the mutation/idempotency profile. The description covers what gets created, the two watch modes, and where alerts land; it omits lifecycle details such as duplicate-alert behavior or how to stop/modify tracking, which sibling tools cover.

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, but the description adds the semantic relationship the schema documents only field-by-field: 'named seats, or every seat of a kind', plus 'only when N seats open together in a row' clarifying seats_together as a conditional filter on the other two.

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: 'start seat alerts on one flight', and enumerates the two watch modes (named seats vs. seat type). It is distinguishable from stop_tracking_seats/update_seat_tracking by the word 'start', but it never names those siblings to make the boundary explicit.

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?

'Use to start seat alerts on one flight, after the traveler confirms' gives a clear activation context and a prerequisite (traveler confirmation). It stops short of saying when NOT to use it or pointing to update_seat_tracking/list_tracked_seats for the adjacent tasks.

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