SupaPark — Walt Disney World live data

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

Annotations declare readOnlyHint=true, destructiveHint=false, so safety is covered; the description adds that the response includes past wait-time history and downtime, which tells the agent this is heavier than a point query. No mention of rate limits or data freshness, keeping it from 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?

Two sentences, front-loaded with the resource and payload, then the required input with an inline example. 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?

A read-only detail tool with no output schema is described well enough to call: the nature of the return (attributes + wait history + downtime) is stated. The gap is that the 'range' parameter that scopes the history is never acknowledged, so an agent may not realize history length is configurable.

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 50%: 'slug' is documented in both schema and description with an example, but 'range' (enum today/7d/30d, default 7d) is never mentioned in the description. The description duplicates the slug info the schema already gives rather than clarifying the range semantics.

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 (details) and resource (one WDW attraction) and enumerates the exact fields returned (height requirement, land, thrill level, Lightning Lane tier, wait history, downtime). This clearly distinguishes it from get_live_wait_times (live only) and get_lightning_lane_prices among the siblings.

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

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

Usage is implied: fetch this when you need static attraction attributes plus historical wait data, versus get_live_wait_times for current waits. However no explicit when-to-use vs when-not, no named alternatives, and no note that the caller must supply an already-known slug.

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 read-only, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them: the shape of the result (index, label, drivers) and the default date window when from/to are omitted.

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 verb and resource, then the default-range caveat. Every phrase earns its place 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?

No output schema exists, but the description compensates by naming the returned fields (index, label, drivers) and the default time range. Only minor detail (exact per-day record shape) is left implicit, which is acceptable for this scope.

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 park (with enum) and the from/to dates, making 3 the baseline. The description only reinforces that a single park is forecast and that dates are optional, adding little syntax or meaning beyond the schema.

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

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

States a specific verb (forecast) and resource (day-by-day crowd for one park) and even previews the returned values (0-100 index, label, drivers). It is clearly distinct from siblings like get_live_wait_times or which_park_today, though it never names an alternative to route against.

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

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

Usage is implied (plan around crowd levels) and one default is stated ('covers the next few weeks when no dates are given'), but there is no explicit when-to-use/when-not or comparison to sibling planning tools such as which_park_today.

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

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

Annotations already establish the safe, read-only, closed-world profile, so the bar is lower. The description restates the computed metric rather than adding operational behavior such as data freshness, update cadence, or whether odds are historical vs. predicted; nothing is contradicted, but little is added beyond the annotations.

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

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

A single front-loaded sentence defining the metric and its components, with zero filler. It could be marginally tighter, but every clause maps to real content an agent needs.

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

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

With no output schema, the description does the work of saying what comes back: drop frequency, catch probability, and timing recommendations. Combined with the sparse three-parameter schema, an agent has enough to call it correctly, though the filtering effect of date/park on the returned odds is unstated.

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?

Two of three parameters (date, park) carry schema descriptions and limit has explicit default/min/max constraints, giving roughly 67% coverage. The description adds no parameter-level meaning (e.g., how date interacts with the odds window, or that limit caps returned restaurants), 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 resource (WDW dining reservation drop odds) and enumerates the three outputs it produces: reappearance frequency, catch probability, and best day/hour. It is clearly distinct from a plain listing tool, though it does not explicitly contrast itself with the nearby get_hardest_dining_reservations 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?

"For hard-to-book Walt Disney World restaurants" gives a clear usage context that tells the agent this is for high-demand venues rather than all dining. It stops short of any exclusion or named alternative (e.g., use get_hardest_dining_reservations to rank candidates first), so it is context without routing.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond that: the data provenance ('SupaPark's own availability checks'), the freshness window ('last 30 days' for drops), and the meaning of each reported field, which is valuable since there is no 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 front-loaded sentence that leads with the resource and ranking metric before the supporting detail. Dense but every clause (tier, share of checks, drops) carries information; the parenthetical gloss on 'drops' is minor padding.

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 list tool with no output schema, the description covers what is returned and the ordering. It leaves the default result size (limit=10) and whether ranking is global or per-park unstated, but nothing critical to invoking 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 50%: 'park' is documented in the schema with an enum, while 'limit' carries only constraints (default 10, max 25) and no description. The description mentions neither parameter, so it adds nothing over the structured fields; baseline 3 is appropriate given the schema still conveys the enum and bounds.

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

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

States a specific resource (Walt Disney World restaurants) and the ranking criterion (how rarely a reservation opens), plus the fields produced. It implicitly separates itself from the per-restaurant odds tool by being a ranked list, but never names get_dining_drop_odds or watch_dining as the alternative for narrower needs.

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

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

No when-to-use or when-not-to-use guidance is given. With siblings like get_dining_drop_odds and watch_dining in the same domain, the agent gets no signal about which one to pick for a specific restaurant versus a global ranking.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that pricing is compared against a 30-day min/median/max window, which is useful behavioral context, but says nothing about data freshness, caching, or refresh cadence for a 'today's prices' tool.

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 enumerating the returned metrics with no filler. Slightly dense as a comma-listed noun phrase rather than a crisp sentence, but 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?

With no output schema, the description usefully enumerates the return payload (30-day min/median/max, current posted wait, minutes saved per dollar, value verdict), which is exactly what an output schema would otherwise carry. It stops short of clarifying freshness or whether 'today' is implicit or derived, a minor gap for a single-parameter 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% with a single enum-constrained 'park' parameter, so the schema carries the parameter semantics. The description only restates that results are per-park ('at a Walt Disney World park') and adds no syntax or scoping detail beyond that. Baseline 3 is appropriate.

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

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

The description names a specific verb+resource ('Lightning Lane Single Pass prices per attraction') and pins the scope to a single park. The 'Single Pass' qualifier distinctively separates it from siblings like get_multi_pass_price and get_lightning_lane_sellouts without needing to open 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The closest siblings (get_multi_pass_price, get_lightning_lane_sellouts) are never referenced, so an agent must infer which price tool to pick from the names alone.

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=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the data source (SupaPark), the timezone ('Times are Eastern'), and the sentinel value 'still available' for rides not yet sold out. Return shape details like sort order or pagination are absent, but the added context is meaningful.

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

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

The core purpose is front-loaded in the first sentence, with mode definitions following as tight fragments. Every clause carries information; nothing is padded. The sentence is long and slightly dense but not wasteful.

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

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

For a read-only, no-required-parameter query with no output schema, the description supplies the domain semantics an agent needs: what is measured, the two modes and their returned statistics, the timezone, and the 'still available' case. Annotations cover the safety profile, so nothing critical is missing.

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

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

Schema description coverage is only 33%, so the description must compensate and largely does: it defines both enum modes of 'range' in detail, including the derived statistics for 'week' (days sold out, days gone before 7:00 AM). The 'limit' parameter remains entirely undocumented in both schema and description, and 'park' filtering is only covered by the schema's own description.

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

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

States a specific verb+resource: 'when each Walt Disney World ride's Lightning Lane sold out,' which is clearly distinct from sibling get_lightning_lane_prices (prices vs. sellout timing). The SupaPark attribution clarifies the data source. It does not explicitly name the neighboring pricing tool, so sibling differentiation is implicit rather than stated.

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

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

The description explains what each 'range' mode yields, which implies when each mode is appropriate, but never states when to use this tool versus get_lightning_lane_prices or get_live_wait_times, nor any prerequisites. Usage is inferable but not guided.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely new behavioral context: a refresh cadence of every few minutes, and that it is only meaningful during park hours, which tells the agent when data may be stale or empty.

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, zero filler; the payload description comes first and the freshness constraint second. Every clause earns its place and 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?

With no output schema, the description usefully enumerates the returned fields (estimate, range, confidence, ghost flag) so the agent knows what to expect. It is complete enough for a single-parameter read tool, with only minor gaps around data availability outside park hours.

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 enum parameter already documents that omitting `park` returns all four parks. The description adds no further semantics about the parameter, 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?

Names a specific resource (current posted wait times for Walt Disney World attractions) and enumerates the exact payload: Real Wait estimate, low/high range, confidence, and ghost-wait flag. The scope is unmistakably distinct from get_crowd_forecast and get_attraction_details, though no sibling is named explicitly.

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

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

"Current" and "Refreshes every few minutes during park hours" imply this is the right tool for real-time wait checks, but there is no explicit when-to-use statement or routing to alternatives like get_crowd_forecast for future dates. Usage is inferable rather than stated.

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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is already covered and the description does not contradict it. The description adds no extra behavioral context beyond the date default, such as whether the price is date-dynamic or subject to availability; with annotations present, this is adequate but thin.

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 the resource named first and the qualifying scope immediately after; nothing is wasted, though it is short enough that it earns no special credit for structure.

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 trivial two-parameter read tool with no output schema, the description conveys the resource, the scoping inputs, and the default well enough to invoke correctly. The missing pieces are the returned price's format/currency and the distinction from get_lightning_lane_prices, both minor.

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 parameters carry descriptions and 'park' has a full enum. The description's mention of the date default merely restates what the schema already says, adding no new semantic detail, 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 (the Lightning Lane Multi Pass price) scoped to a Walt Disney World park and date, which is concrete and unambiguous. It does not, however, differentiate itself from the sibling get_lightning_lane_prices, leaving the boundary between the two to inference.

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 parenthetical '(defaults to today)' gives a small practical hint, but there is no when-to-use guidance, no prerequisites, and no routing to or away from the sibling get_lightning_lane_prices that clearly overlaps in topic.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is well covered. The description adds genuinely new behavioral context: the account-linkage precondition and the fact that the response carries plan tier and alert-delivery mode. No explicit note on what happens if no pairing key exists, which keeps it from 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?

Two sentences with no filler; the capability statement is front-loaded and the prerequisite follows. 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?

There is no output schema, but the description compensates by naming the fields returned (link status, plan, alert delivery), and annotations carry the safety profile. Only the unlinked/error path is undocumented, a minor gap for a zero-arg 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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4.

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 whether this assistant is linked to a SupaPark account') and enumerates the returned data (plan tier, alert delivery). No sibling tool touches account state, so it is trivially distinguishable from the watch/price/forecast tools.

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

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

Usage is implied rather than stated: the description notes a prerequisite ('Requires a linked SupaPark account (pairing key)') but never says when to call this versus other tools or what to do when unlinked. Adequate context, but no explicit when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: only ACTIVE watches are returned (not the full history), the id field is included, and an account-link auth requirement is disclosed.

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 what is returned and followed by the prerequisite. No wasted wording.

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 parameterless, read-only list call with no output schema, the description covers what comes back (active watches with ids) and what is needed to call it. Slightly thin on the exact shape/number of returned fields, but sufficient for correct invocation.

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 no parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate against the schema.

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

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

States a specific verb (Lists) and resource (active ride and dining watches/alerts), and adds that each entry carries an id. The resource is clearly distinct from watch_ride/watch_dining (create) and remove_watch, so an agent can route 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 precondition for use — a linked SupaPark account via pairing key — and scopes the result to active watches. It does not name alternatives or a when-not case, but the context is unambiguous for a zero-param list 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context: the removal is recoverable ('It can be restored in the SupaPark app') and requires a paired account, which meaningfully informs the agent's risk assessment without contradicting the destructive hint.

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, purpose front-loaded, followed by reversibility and prerequisite in that order of importance. No filler or repetition of 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?

For a single-parameter mutation with no output schema, the description covers what it does, the account precondition, and the recoverability of the effect. 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?

Only one parameter and schema coverage is 100%, with the schema itself documenting 'id' as a UUID. The description's 'by watch id' adds no syntax or format detail 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?

States a specific verb and resource ('Turns off one watch on the linked SupaPark account, by watch id'), which cleanly separates it from the sibling creators watch_dining/watch_ride and from list_my_watches. An agent can pick it without opening the schema.

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

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

Gives clear context for use plus a prerequisite ('Requires a linked SupaPark account (pairing key)') and points to where the action is undone (the SupaPark app). It stops short of naming alternatives or stating when not to use it.

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

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

Annotations already declare this a non-read-only, non-destructive, idempotent operation, so the safety profile is covered. The description adds value beyond that: it discloses the actual side effect (an alert is created on the linked account), the event that fires it (a reservation opening), and the auth precondition (pairing key). It stops short of saying how alerts are delivered or that remove_watch cancels them.

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, zero filler, and the core effect ('creates an alert... fires when a reservation opens') is front-loaded ahead of the prerequisite. 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?

For a 3-parameter tool with no output schema, the description covers the action, its trigger, and the account prerequisite, and annotations carry idempotency and non-destructiveness. The main gap is that with no output schema it never hints at what the call returns (e.g., a watch id or confirmation), which an idempotent create tool arguably should mention.

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 67%, with 'date' documenting the 180-day window and 'restaurant' giving a slug example, but 'party_size' has only min/max bounds and no prose. The description only restates 'the given date and party size' and adds no syntax, format, or matching semantics (e.g., fuzzy name matching, slug lookup behavior) beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb ('Creates an alert') and a precise resource ('a reservation opens at a Walt Disney World restaurant'), with the trigger condition spelled out. The dining-restaurant scope cleanly separates it from the sibling watch_ride, so an agent can choose between them 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 supplies a real prerequisite ('Requires a linked SupaPark account (pairing key)'), which is genuinely useful context for whether the call can succeed. However, it never says when to prefer this over alternatives such as watch_ride, list_my_watches, or remove_watch, nor any when-not-to-use condition. Usage is implied rather than guided.

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 mark it as a non-read-only, idempotent, non-destructive mutation, and the description aligns by saying it creates an alert. It adds behavior annotations don't carry: the account-link/auth prerequisite (pairing key) and that the delivery channel follows the account plan. It does not state what happens on re-creation or what a returned alert looks like.

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 core action ("Creates an alert...") followed by compact per-kind semantics and prerequisites. Every sentence carries information; no filler or restatement 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?

For a mutation tool with no output schema, the description covers the essentials: auth requirement, delivery behavior, and kind semantics. It could add what happens on success (e.g. a returned watch and how it relates to list_my_watches), but nothing critical to invoking 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 75% and the schema documents date and threshold_minutes, but the description adds real meaning for kind by translating each enum value into the triggering condition (return times open vs wait drops to threshold). This goes beyond the bare enum and threshold fields, though ride itself is only covered by the schema.

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

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

States a specific verb and resource: "Creates an alert ... for a Walt Disney World ride," and the two kinds clarify the scope. It is clearly distinct from watch_dining by resource, but it never names a sibling or explicitly contrasts itself, so it stops short of the tier-5 sibling differentiation.

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 explains when each kind applies (lightning_lane vs wait_drop), which is real usage guidance, but there is no guidance on when to choose this creation tool versus siblings like get_live_wait_times, get_crowd_forecast, or list_my_watches. Usage is implied through the kind semantics rather than stated as when/why to pick this 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 establish read-only, non-destructive, closed-world behavior, so the bar is lower. Beyond that, the description usefully discloses that this is a composite/real-time aggregation (live crowd levels + today's forecast + remaining hours) and enumerates what comes back (rank, live average wait, open/close, one-line reason) — context the annotations cannot provide.

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, then the return shape. No filler, no restated title, every clause adds 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 no input schema and no output schema, the description carries the burden of explaining returns, which it does adequately. Minor gaps remain: no note on data freshness/refresh cadence or tie-breaking logic in the ranking, which would matter for a 'right now' recommendation tool.

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

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

The tool takes no parameters (0 params, empty schema), so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly conveys that no input is required.

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 gives a specific verb plus resource plus scope: 'Ranks the four Walt Disney World theme parks for visiting right now'. It also names the exact inputs being combined (crowd levels, forecast, park hours), which cleanly separates it from siblings like get_live_wait_times or get_crowd_forecast that expose only one signal.

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 'right now' framing implies a real-time, decision-support use case, but the description never states when to prefer this over the more granular siblings (get_live_wait_times, get_crowd_forecast) or any exclusions. Usage is inferable rather than spelled out.

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