Parky — Park Planning

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

Annotations already cover the safety profile (readOnly, non-destructive, not open-world), so the bar is lower. The description adds genuine behavioral context beyond them: the search corpus is limited to the current Disney/Universal release scope, and the tool deliberately excludes live wait data. It says nothing about result cardinality, ranking, or ambiguity handling when several matches exist.

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, front-loaded with the use case, then the scope constraint, then the exclusion. No filler, and both boundary statements earn their place by preventing misuse.

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

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

For a two-parameter read-only lookup with no output schema, the description supplies the essential context: when to reach for it, what it searches over, and what it does not return. It could be slightly more complete by indicating what the returned identifier looks like or how to handle misses, but nothing critical 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 both parameters are documented in-schema (query semantics plus the optional park_id narrowing purpose), so the baseline is 3. The description adds no further meaning about query syntax, matching behavior, or what happens if both a park and ride share a name.

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 — resolve a named/described park or ride to its canonical Parky ID — and explicitly bounds the scope to 'Parky's current Disney and Universal release scope.' It also distinguishes itself from the wait-times sibling by stating 'It does not retrieve current wait times.' An agent can tell this apart from parky_get_waits 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?

The trigger condition is explicit ('when a visitor names or describes a park or ride and you need its canonical Parky ID'), and there is a clear when-not ('does not retrieve current wait times'). It does not name the sibling tools that handle waits/hours/crowds, so the routing is implied rather than spelled out, which keeps this below 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 readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: the 30-day horizon, park-local time semantics, and the important caveat that results are estimates, not guarantees.

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 usage condition and followed by return description; the estimate caveat is concise. Slightly dense with multiple clauses packed into the second sentence, but no wasted 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, so the description carries the return-value burden and does it well: hourly predicted waits with bounds, weekday typical waits, and best/worst windows in park-local time. Only missing minor details such as what happens when a date has no data or whether waits are per-ride or per-park.

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 ride_id and date are already documented in the schema including the 30-day limit, today default, and ID provenance. The description only restates the 30-day window and ID resolution step, adding little 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?

Names a specific verb+resource ('best time to ride') and frames the intent concretely: avoiding long waits on a given day. The 'hourly predicted waits' framing implicitly separates it from parky_get_waits (actual waits), 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?

Gives a clear trigger ('when a visitor asks when to ride something to avoid long waits') and bounds the context to a specific day within 30 days. It also states a prerequisite ('Resolve the ride ID first') although it does not name parky_find_experience or state when NOT to use this (e.g., for current waits).

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 needs no restating. The description adds real behavioral context beyond that: the dual mode (pass a stop to get times, omit it to list stops) and the provenance of the data ('Disney's own bus tracking'). It stops short of stating freshness/update cadence, which would matter for a prediction 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?

Three short sentences, front-loaded with the when-to-use trigger and immediately followed by the parameter contract and data source. No filler or repetition beyond the single clarifying restatement of the optional-stop behavior.

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-optional-param read tool with no output schema and annotations covering safety, the description gives the agent everything needed to decide and invoke: trigger, input contract, and both call modes. The remaining gap is what the response looks like (e.g., list of upcoming times vs. single next arrival), which the agent must infer.

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 parameter's own description already covers 'Stop name or ID ... omit to list stops.' The description repeats that contract in prose but adds no format, naming convention, or ID-lookup detail beyond the schema. 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 ('get bus times' for 'Walt Disney World bus') and names the exact domain it covers (resorts/stops to parks or Disney Springs). It is trivially distinguishable from siblings like parky_get_waits, parky_get_hours, and parky_get_showtimes, which cover different data.

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?

Opens with an explicit trigger ('Use this when a visitor asks when the next ... bus leaves'), which tells the agent precisely when to reach for it. It does not name or exclude any alternative tool, but the sibling set covers non-overlapping resources, so routing ambiguity is low.

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, non-destructive, closed-world), so the description adds what annotations cannot: the output is a probabilistic forecast with a range, is bounded to a 30-day park-local window, and is not a live measurement. It does not mention rate limits or failure modes, but for a read-only forecast that is a minor 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 short sentences, front-loaded with the usage condition and prerequisite, with each sentence carrying distinct information (when to use, prerequisite, output nature). 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 no output schema and full parameter coverage, the description correctly spends its budget on when-to-use and what the response conceptually is (forecast and range). Enough for correct invocation, though it could say more about the forecast's shape or granularity.

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 date, days, and park_id semantics are already fully documented. The description only reinforces the park-ID prerequisite and the 30-day horizon, adding no syntax or format detail beyond the schema; 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?

Specific verb+resource ('how crowded one supported park may be'), explicit scope (next 30 park-local days), and an explicit contrast with what it is not ('not a guarantee or a live wait'), which cleanly separates it from parky_get_waits. An agent can distinguish this from siblings 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?

States the triggering user intent and a prerequisite ('Resolve the park ID first'), and implicitly routes live-wait questions elsewhere via 'not ... a live wait'. It never names the alternative tool explicitly, so routing for edge cases 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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: a 60-day coverage window and the explicit boundary that Parky cannot sell tickets, which prevents an agent from promising a purchase flow.

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, front-loaded with the usage trigger, followed by what is returned and then the capability boundary. No filler and nothing buried.

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

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

With no output schema, the description carries the burden of describing the return and does so (on-sale/sold-out nights plus lowest price). Combined with full parameter coverage in the schema and complete safety annotations, an agent has everything needed to call 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 description coverage is 100%, so all three parameters (resort, from, to) are already documented with defaults and limits in the schema. The description's 'Covers up to 60 days' restates the schema's 'at most 60 days in all' rather than adding format or syntax guidance, 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 (ticketed event nights at a supported resort) and pins down the returned facts: which nights are on sale or sold out, and the lowest price. The named event examples (Mickey's Not-So-Scary Halloween Party, Jollywood Nights, Halloween Horror Nights) make it unmistakable against siblings like parky_get_ticket_prices and parky_get_showtimes.

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 — 'Use this when a visitor asks about separately ticketed event nights' — which is a clear context for selection. It does not, however, name the alternative to use for general admission tickets or explain what to do when the resort isn't supported, so the routing guidance is good but not exhaustive.

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 readOnly/non-destructive/closed-world, so the bar is lower; the description still adds real value by disclosing the 60-day window, that Early Entry is an eligibility window rather than a ticketed event, and that schedules are operator-reported and subject to change. Return shape and pagination behavior are not described, 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?

Front-loaded with the usage trigger, then constraints, then data caveats; three sentences with no filler. Slightly dense 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 no output schema, the description partly compensates by explaining what schedule windows contain (categories, labels, Early Entry semantics) and that data is operator-reported. It leaves the exact response structure unstated, but covers enough 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?

Schema description coverage is 100%, so the schema already documents date, days, and park_id formats and defaults. The description only adds 'resolve the park ID first,' which does not meaningfully extend the schema's parameter documentation.

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 ('Get park operating hours') with explicit scope: one supported park, next 60 park-local days. It does not explicitly differentiate itself from near-siblings like parky_get_park_availability or parky_get_park_conditions, so it stops short of a 5.

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

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

Gives a clear triggering condition ('when a visitor asks about operating hours') and a prerequisite ('Resolve the park ID first'). It names no alternative tool for adjacent questions such as availability or showtimes, so no explicit 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior the annotations don't: return times are today-only, prices span the next 30 park-local days, and the tool cannot transact. It stops short of describing response shape or how many rides are returned.

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 use trigger, followed by temporal constraints and the capability boundary. Every sentence carries information; there is 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?

With no output schema, the description carries the burden of describing returns, and it does explain what the two data modes yield (prices vs. return windows) plus their date limits. It is slightly thin on the response shape (e.g., per-ride list structure, whether prices vary by ride), which keeps it from a 5.

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 park_id, date, and ride_id are all already documented in the schema with their defaults and formats. The description's temporal notes ('return times only for today') overlap with the date parameter's own description rather than adding new parameter-level meaning. 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 names a specific resource (Lightning Lane / Universal Express prices and return times) with clear scope, and it implicitly distinguishes itself from sibling parky_get_ticket_prices by scoping to Lightning Lane rather than admission. An agent can tell exactly what data this returns 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 states the triggering user question ('when a visitor asks what Lightning Lane costs... or which rides have return times available now'), the temporal validity of each data type, and an explicit negative boundary ('Parky cannot buy or book Lightning Lane'). 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=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds content those annotations cannot: the result is segmented by ticket/pass type, the horizon is capped at 7 days, and the data comes from Disney's and Universal's own calendars, which tells the agent how authoritative and how fresh the answer is.

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, both load-bearing: the first gives the trigger, the second gives the return shape and scope. The most decision-relevant information (when to use it) is front-loaded with no preamble.

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 tool with a fully documented 3-parameter schema and no output schema, the description supplies the missing return-shape context (segment granularity, 7-day window, data source). It does not cover failure cases such as an unsupported resort key or a date range with no published calendar, which is a minor remaining 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%, with the date format, the 1-7 day range and the resort keys (wdw, dlr, uor, ush) all documented in the schema. The description only loosely echoes this ('for up to 7 days', 'given dates', 'supported resort') and adds no new parameter guidance, 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 ('get park reservation availability') and then defines exactly what gets returned: reservation/blockout status by ticket-or-pass segment. It is clearly distinguishable from adjacent siblings like parky_get_hours and parky_get_ticket_prices, which cover different visitor questions.

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 gives an explicit trigger: 'Use this when a visitor asks whether a park has reservations or blockout dates for a ticket or pass type on given dates at a supported resort.' That is a precise when-to-use condition scoped to a supported resort, though it stops short of naming an alternative tool or an exclusion case.

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 safety (readOnly, non-destructive, closed-world). The description adds meaningful behavioral context beyond that: the data source (NWS latest observation and alerts) and the crucial temporal caveat that this is current conditions, not a forecast. It doesn't mention freshness windows or rate limits, but the additions are substantive.

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

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

Two sentences, front-loaded with the usage trigger, followed by the data-provenance caveat. Every clause earns its place with no redundancy.

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

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

For a single-parameter read tool with no output schema, the description conveys the key content (weather, alerts, ride-down count) and the current-vs-forecast distinction. It could say a bit more about what 'rides are down' returns or freshness, but it is 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?

Schema coverage is 100% and the schema itself documents park_id thoroughly (canonical ID from parky_find_experience, park-key fallback). The description adds nothing about the parameter, so the schema does the heavy lifting and 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 (retrieve current park weather and ride-down counts) and scopes it to 'one supported park right now'. This clearly distinguishes it from siblings like parky_get_waits, parky_get_hours, or parky_get_ride_outages.

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 trigger conditions ('when a visitor asks about weather, storms, heat, lightning, weather alerts, or how many rides are down'), which is strong contextual guidance. It does not, however, name an alternative tool or state when NOT to use it, so it stops short of the 5-level routing clarity.

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 safety profile is covered. The description adds genuinely useful context beyond that: facts vary per ride and missing facts are omitted rather than guessed, telling the agent how to interpret partial results and that no fabrication occurs.

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, front-loaded with the usage trigger, followed by the prerequisite and the data-quality caveat. The fact enumeration is long but earns its place by defining scope; only the ride-ID instruction mildly duplicates 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 one-parameter, read-only lookup with no output schema, the description covers when to use it, what facts come back, and how missing data is handled. The only residual ambiguity is the boundary with parky_get_lightning_lane for Lightning Lane questions, which is not addressed.

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 ride_id parameter, and the schema already states it is a canonical Parky ride ID from parky_find_experience. The description's 'Resolve the ride ID first' reinforces but does not extend that information, 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?

Names a specific verb+resource ('get ride facts') and enumerates the exact fact set (height requirement, ride length, top speed, drop, ride type, land, Lightning Lane) so the agent knows the scope precisely. This distinguishes it from siblings like parky_get_waits, parky_get_ride_reliability, and parky_get_lightning_lane 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?

'Use this when a visitor asks about a ride itself' gives clear triggering context, and 'Resolve the ride ID first' supplies the prerequisite step. It does not explicitly name the alternative tool for overlapping topics (Lightning Lane details are also served by parky_get_lightning_lane), so routing is implied 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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that: the data provenance ('Disney's and Universal's own live feeds') signals freshness/live status, and the time windows (last 1-30 days vs. today) are disclosed. It does not describe pagination or result size.

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 dense sentences, front-loaded with the trigger, then the two modes. Every clause carries information and nothing is repeated from 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 3-param read tool with no output schema, the description covers both invocation modes, the time windows, and the fields returned (start/end times), which is what an agent needs. It could note result volume or ordering, but 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 baseline would be 3, but the description adds real semantics beyond the schema: the conditional behavior of ride_id (per-ride history vs. park-wide today) and that outages include 'rides down right now'. The days default and 'ignored without ride_id' rule live in the schema, not the description.

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

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

States a specific verb+resource ('get ride outages') and spells out the two operating modes: per-ride history with ride_id, park-wide current outages without it. An agent can distinguish this from parky_get_ride_reliability and parky_get_waits 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 ('Use this when a visitor asks whether or when a ride broke down'), which is clear usage context. It does not explicitly name an alternative tool or state when NOT to use it (e.g. versus parky_get_ride_reliability for aggregate stats), 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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the returned metrics and the ordering behavior (least reliable first), which compensates for the absent output schema; it omits pagination or rate-limit context.

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, front-loaded with the trigger and immediately followed by the return payload and prerequisite; 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?

For a two-parameter read tool with no output schema, the description covers the trigger, the metrics returned, sort order, and the park ID prerequisite, which is enough to invoke it correctly. Minor gaps remain around result volume or whether a single park's full ride list is returned by default.

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%, with park_id documented as the canonical key (magic-kingdom accepted) and ride_id as an optional single-ride filter, so the schema carries the semantics. The description only reinforces the park ID prerequisite and adds no syntax or format detail beyond the schema, matching the baseline 3.

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?

Specific verb+resource with scope: it returns 30-day uptime, outages per day, and average/longest outage, sorted least-reliable first. It clearly distinguishes itself from siblings like parky_get_waits and parky_get_ride_facts by naming the reliability domain and the user question it answers.

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?

Opens with an explicit trigger ('when a visitor asks how often a ride breaks down or which rides are least reliable') and states a prerequisite ('Resolve the park ID first'). It does not explicitly name a competing sibling tool or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: 'Times are usually published for today only,' warning the agent that future dates may return nothing. It does not describe return shape or ordering, but that is a minor 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?

Two sentences, front-loaded with the usage trigger followed by the data-availability caveat. Every clause carries information; nothing is redundant or padded.

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

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

For a simple read-only lookup with no output schema, the description covers the trigger, scope and a key freshness caveat. It could briefly note what is returned (a list of timed show/parade entries), but nothing an agent needs in order 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 both parameters are already documented, including the park-local date default and the park_id source. The description only implies the date window ('today or within the next week') and the single-park constraint, adding little beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb+resource ('get when a show, parade, fireworks or character meet happens') and scopes it to one supported park within today or the next week. This clearly separates it from siblings like parky_get_hours, parky_get_waits and parky_get_event_nights, which cover different entity types.

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 an explicit trigger condition ('Use this when a visitor asks when a show, parade, fireworks or character meet happens'), which is clear usage context. It stops short of naming alternative tools for adjacent questions (e.g., park hours or event nights), so there is no explicit 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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description goes beyond them by disclosing data provenance and staleness ("prices ... shown Parky on its last check") and by ruling out transaction behavior, which is genuinely useful context for an agent, though it says nothing about coverage gaps or missing-price behavior.

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

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

Three tight sentences with the trigger front-loaded, followed by the return semantics and the capability boundary. No filler and no 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 no output schema, the description correctly takes on the burden of describing what comes back (last-observed prices from Disney or Universal). For a two-parameter read tool with full schema coverage and safety annotations, nothing an agent needs 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 a baseline of 3 applies, but the description adds real meaning beyond the schema: the date must fall within the next year, and the resort parameter maps to the enumerated set of supported resort keys. That constrains valid inputs in a way the schema alone does not.

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 (get ticket prices) plus the exact scope: a supported resort and a start date within the next year. The supported-resort list makes it instantly separable from sibling tools like parky_get_hours or parky_get_waits, which cover different 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?

Explicitly frames the trigger ("Use this when a visitor asks what park tickets cost") and adds a boundary condition ("Parky cannot sell or book tickets"), which prevents the agent from treating this as a booking path. No inference is required to decide when to call 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 cover the safety profile (readOnly, non-destructive, closed-world), so the description's value-add is the data semantics: ride entries are always present and reported as 'unavailable' rather than closed when no live value exists, while experience/show/meet entries appear only while reported. That is genuine behavioral context beyond the annotations, though it says nothing about freshness or rate limits.

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 trigger condition and followed by prerequisite, return-shape caveats, and scope exclusion. 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?

With no output schema, the description carries the burden of explaining the returned entry types and their listing rules, and it does so clearly. Minor gaps remain around result freshness and how 'unavailable' should be surfaced to a user, but 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 both park_id and ride_id are already documented in the schema, including the park-key fallback and the 'one ride only' behavior. The description only echoes the park-ID prerequisite, adding no format or edge-case detail beyond the schema. 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 ('current posted ride waits or operating status') and scopes it to 'one supported park', which cleanly separates it from siblings like parky_get_ride_outages, parky_get_best_time and parky_get_showtimes. An agent can identify the tool's job 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 an explicit trigger ('when a visitor asks for current posted ride waits or operating status'), a prerequisite ('Resolve the park ID first'), and a negative boundary ('does not predict future waits'). It stops short of naming the alternative tools for prediction (e.g. parky_get_best_time), so the routing is implied rather than explicit.

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