tickadoo Experiences and Events

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds real context beyond them: it returns a concise grounded answer plus cited products with booking URLs, and is intent-aware across budget/audience/timeframe. It omits latency or grounding-source caveats, but the annotation bar is low and this exceeds it.

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 triggering condition, then output shape, then the intent-handling note. Little waste, though the trailing 'via the concierge seam' is internal jargon of marginal value to an agent.

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 not be explained, and the description still characterizes the output (concise grounded answer + cited products with booking URLs). Combined with the clear trigger and annotations, an agent has what it needs to call it, missing only explicit sibling routing.

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 schema fully documents city, city_slug, limit, format, language, and question. The description adds only the abstract notion of intent-awareness (budget, audience, timeframe), which maps to the free-text question rather than adding concrete parameter-level meaning. Baseline 3 applies 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 gives a specific verb ('asks a free-text theatre question') and resource, and illustrates with concrete examples (best musical for kids, romantic show tonight, cheap comedy). It is clearly the natural-language Q&A entry point versus the structured search/recommend siblings, though it never names those alternatives 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?

It states a clear trigger ('Use this when the user asks a free-text theatre question') and reinforces it with examples. However, it offers no when-not guidance or routing to siblings like search_experiences, find_theatre_for_occasion, or get_show_guide, so the agent must infer boundaries.

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 carried structurally; the description's added value is naming the payable outputs (availability, party cost, booking link) and the single-date scope. It does not explain the unusual idempotentHint=false or the pricing freshness/rate-limit behavior, so it is useful but not rich.

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, with the positive trigger front-loaded and the sibling routing placed after it. 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?

An output schema exists and annotations cover safety, so the description need not explain return values; combined with full schema coverage and explicit sibling routing, an agent has everything required to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, including natural-language date resolution, slug formats, format enum, language, and party_size bounds, so the schema does the heavy lifting. The description only gestures at party_size ('what it costs for a party') without adding syntax or semantics 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?

The description names a precise verb+resource+scope: check one specific experience on exactly one date, returning availability, party pricing, or a booking link. It explicitly contrasts with the sibling get_availability, so an agent can route 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 states the triggering condition ('user has picked a specific experience and asks about exactly one date') and names the alternative tool plus the condition that selects it (date-range browsing, upcoming times, live slot prices → get_availability). Nothing 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 and idempotentHint, so safety is transparent. However, the description says it 'Returns a comparison table,' while the schema's format parameter states text format returns 'a short narrative paragraph' — so the claimed output shape is not accurate across all supported modes.

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 use case, and no filler. It earns most of its space, but the 'comparison table' wording is slightly imprecise given the text/narrative format option, which costs a point.

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 the safety profile, the description is mostly complete: it communicates cardinality, required input, and output highlights. The only material gap is the inconsistent return-format claim, which could mislead an agent choosing between json and text.

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 slugs, format, and language. The description only restates the slug requirement and adds no new parameter semantics beyond what the schema provides, so it stays at 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?

The description names a specific operation — side-by-side comparison — and bounds it to 2-5 specific products. It also previews the output (comparison table plus per-axis winners), which distinguishes it clearly from search, recommendation, and detail-lookup 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?

It gives an explicit trigger: 'Use this when the user wants a side-by-side comparison of 2-5 specific products.' It does not explicitly name alternative tools or state when not to use it, so it misses the full 5, but the context is clear.

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, destructiveHint=false, so the safety profile is covered. The description adds the useful input prerequisite (exact coordinates required) but says nothing about radius defaults, result ordering, or how the openWorldHint=false closed-world constraint plays out. Adequate, not rich.

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 waste, and the primary use condition is front-loaded before the fallback tool is introduced.

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 routing rule is complete. The only shortfall is silence on radius/limit defaults and result ordering, which the schema partially covers but which would help an agent choose sensible values.

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 every parameter carries its own description, including limit bounds, format enum meanings, and radius defaults, so the schema does the heavy lifting. The description only reinforces that latitude/longitude must be exact rather than approximate, which is marginal added 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?

States a specific verb and resource (find experiences) plus the precise scope condition (near an exact lat/long point). It explicitly contrasts itself with search_local_experiences, so an agent can route 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?

Gives both sides of the decision rule: use this when exact coordinates are held, use search_local_experiences when only a place name, landmark, or neighbourhood is known. The alternative is named and the selecting condition is 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 a safe idempotent read (readOnlyHint, idempotentHint, openWorldHint=false), so the safety burden is lifted. The description adds genuinely useful behavior: results are ranked with fit scores and reasons, and it honours party ages and date. Return structure itself is covered by the 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?

Two tight sentences, front-loaded with the trigger condition and occasion list, then the return behavior. Nothing is 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?

Together with a rich output schema and annotations, the description covers the trigger, the ranked output with fit scores/reasons, and the party/date constraints. It omits sibling differentiation and geographic scoping (city handling), but is otherwise complete for a read-only discovery 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 75%, so the schema documents most parameters (city, date, limit, format, language, city_slug). The description adds the semantic insight that 'party' affects results ('honouring party ages'), but does not explain other parameters. Baseline 3 is appropriate since the schema does most of the 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?

States a specific verb ('find'), resource ('theatre shows'), and the trigger condition (user has an occasion). It distinguishes itself from generic siblings like search_experiences by naming the occasion-based ranking. However it doesn't explicitly contrast with close siblings such as get_date_night or get_family_day, so the differentiation is implied 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?

Explicitly states when to use it – 'when the user has an occasion' – and enumerates the occasion types. It does not name alternatives or when-not-to-use (e.g., versus get_date_night for a pure date-night intent), leaving some routing to inference.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds genuinely useful behavior beyond that: the 60-second cache with a fresh bypass subject to rate limits, the minor-unit currency convention (13125 GBP = GBP 131.25), and venue-local times that carry a real UTC offset and are safe for time math. The one gap is that it doesn't describe failure modes or what happens when a product has no availability, and it sits slightly awkwardly against idempotentHint=false while advertising a reusable idempotency_key.

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 tool's purpose and trigger are front-loaded in the first sentence, and the following sentences pack in high-value caveats about currency units and timezone handling without padding. It is dense but every clause carries information an agent needs, though the return-value detail is somewhat redundant given an output schema exists.

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 100% schema coverage, an output schema, and full annotations, the description supplies the one thing structured fields can't: when to reach for this live-check tool and how to interpret its units and timestamps. An agent could invoke it correctly from this text alone; only sibling disambiguation 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 schema already documents all ten parameters and the baseline is 3. The description reinforces the product_id vs slug+city_slug choice but adds no syntax or format detail beyond the schema, and its richer currency/timezone notes describe return values rather than 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?

The description names a specific verb and resource: checking live bookable dates, times, prices, and remaining spaces for one selected product, and explicitly frames itself as "the live supplier-check tool." That is clear on its own, but it never distinguishes itself from the sibling check_availability, whose name suggests the same operation, leaving the agent to guess which one to pick.

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 trigger condition ("when the user is ready to check live bookable dates...") and tells the agent which identifier to pass (product_id from search, or slug plus city_slug). However, it offers no when-not guidance, no prerequisites, and no routing against the near-identical check_availability sibling.

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 read-only/idempotent/non-destructive. The description adds the valuable insight that the response is raw search rows and that the agent must derive categories and price levels itself rather than expecting structured guides. This is unusually candid about output behavior beyond what annotations 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 use case, then the return-shape caveat. No filler. Slightly dense 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?

An output schema exists, so return-structure detail is less critical, but the description still flags that the output is unsorted-ish search rows requiring derivation, which is the key operational fact. Combined with annotations, this is nearly complete; it could mention pagination or result limits if any exist.

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 already documents city, format, and language with defaults. The description adds no parameter-level guidance (e.g., that 'city' is a slug, which format to prefer). Baseline 3 is appropriate when the schema carries the 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 specific verb+resource: returns a ranked list of a city's most popular bookable experiences, for orientation. The 'when the user wants an orientation overview' framing helps distinguish it from siblings like search_experiences or get_hidden_gems, though it doesn't name a specific alternative.

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 context for when to use: orientation overview for trip planning, as opposed to targeted searches. It doesn't explicitly exclude cases (e.g., 'not for specific queries'), but the guidance is strong enough to route most agents correctly.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds important behavioral nuance: romantic-tagged rows are promoted rather than filtered, out-of-season products are dropped, and budget has no effect yet. This goes well beyond the structured annotations.

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

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

Every sentence carries information: use case, return shape, ranking behavior, parameter caveats, and a pointer to an alternative. The key behavioral warnings are front-loaded and no filler is present.

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 rich input schema, output schema presence, and annotations, the description covers all essential behavioral and selection context. An agent can correctly decide when to call it, what to expect, and which caveats to communicate to the user.

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 schema already documents all five parameters. The description adds crucial meaning for date and budget: date determines the current season, and budget is accepted but not yet applied — valuable caveats an agent cannot infer from the schema alone.

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

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

States a specific trigger ('wants an evening for two'), the exact resource (experiences/search rows), and the shape of the result (flat ranked list, not a structured arc). This clearly distinguishes it from related tools like get_family_day and search_by_mood.

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 when-to-use condition and explains what the tool does not provide ('not a structured pre-dinner/dinner/show arc'). It also names an alternative (search_by_mood) and notes that budget is accepted but not yet applied, which prevents misuse.

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 read-only, idempotent, and non-destructive behavior. The description adds useful context about richer fields but does not disclose edge behavior such as requiring at least one identifier or what happens if neither is provided. No contradiction with 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 concise sentences with the purpose front-loaded and no redundant wording. Every phrase 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 annotations covering safety and an output schema defining the return shape, the description only needs to convey when to call and what identifier to pass; it does both. It would be a 5 if it explicitly required one of product_id/slug, since the schema currently lists zero required parameters.

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 documents all four parameters at 100% coverage, so the baseline is 3. The description adds the 'either product_id or slug' relationship and source context, but it does not add significant meaning beyond the schema and does not explicitly state a one-of requirement.

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

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

The description clearly identifies the tool as the follow-up for a specific experience selected from search results and lists the richer field categories (product, location, supplier, booking). It distinguishes itself from search/recommendation siblings, though it lacks an explicit action verb like 'retrieves'.

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 trigger condition ('user selects a specific experience from search results') and states that either product_id or slug can be used. It does not explicitly name alternatives or exclusion cases, 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?

Beyond the readOnly/idempotent hints, it discloses important behavior: family-tagged rows are promoted, out-of-season products are dropped, and kids_ages/budget are accepted but not applied. The description also explains that date only controls season selection, making the tool's actual behavior predictable.

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

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

Three dense sentences with no filler: use case, output shape/behavior, and parameter caveats. The most decision-relevant facts (when to use and what it returns) are 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?

For a 6-parameter tool with output schema and complete schema descriptions, nothing material is missing. Caveats about ignored params and the guidance to follow up with get_experience_details complete the picture.

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 baseline is 3, but the description adds real semantics: it explains how date influences season selection and explicitly warns that kids_ages and budget have no effect yet. This is exactly the kind of parameter-level caveat an agent needs.

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: returns family-suitable options for a day in one city. It further pins the exact output shape (flat ranked list of experiences) and explicitly contrasts with a structured plan, distinguishing it from nearby tools such as plan_itinerary.

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 when-to-use trigger: when the user wants family-suitable options for a day in one city. It also gives a when-not by saying it is not a structured morning/lunch/afternoon/evening plan, and suggests get_experience_details for age verification, which orients the agent toward the correct follow-up.

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 destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the filtering rules, the preference for highly rated rows with fewer reviews, and the fallback to the standard ranked list with possible overlap. This is exactly the kind of non-obvious behavior an agent needs to know.

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 constructed sentences: the first fronts the primary use case, the second packs the filtering logic, ranking preference, fallback behavior, and overlap caveat. Every sentence earns its place with no filler or repetition of schema/annotation info.

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 filtered-list tool with output schema present, the description covers the trigger, selection criteria, exclusions, fallback, and a caveat about potential overlap with headline search. Safety is covered by annotations, parameter semantics are covered by the input schema, and return shape is covered by the output schema. 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%, with all four parameters (city, format, language, max_results) documented including defaults and constraints. The description adds no parameter-specific detail, but the schema already carries that burden, so the baseline of 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 clearly identifies the tool as returning lower-profile, non-bestseller options with specific exclusions (Bestseller, hop-on-hop-off, CityPass) and a preference for highly rated, low-review-count rows. It avoids tautology and gives concrete selection criteria, but it does not explicitly name or differentiate against a sibling tool, relying instead on the comparison to 'headline bestsellers'.

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 first sentence gives an explicit trigger condition: use when the user wants lower-profile options rather than headline bestsellers. It also discloses the fallback behavior when qualifying rows are too few. However, it does not state when NOT to use this tool or mention alternatives like recommend_experiences or search_experiences by name.

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, non-destructive, closed-world), so the bar is lower. The description still adds real value by disclosing the output shape contradiction ('flat ranked candidate list, not structured day slots or a running cost') and the implied post-processing burden on the caller, which annotations cannot express.

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 triggering condition, then the return-shape caveat, then the caller's responsibility. Every sentence carries information an agent needs and none 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?

With an output schema present, return values need not be enumerated, and the description goes further by warning about the flat-list shape and the absence of a computed cost. With 8 parameters fully documented in-schema, 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 description coverage is 100%, including enum meanings, defaults, and the 'family' tag caveat, so the schema does the heavy lifting. The description adds no parameter-level guidance such as how 'pace' interacts with 'days' or how budget bands are applied, 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 names a specific trigger ('user wants a multi-day plan for a single city') and a specific deliverable ('flat ranked candidate list of experiences'), then explicitly negates what it is not (structured day slots, running cost). This is far more precise than the siblings like get_city_highlights or get_family_day, which target different 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?

It gives a clear triggering condition and an important negative constraint (returns raw candidates, not a formatted itinerary), telling the agent it must arrange days and compute totals itself. It stops short of naming sibling alternatives (e.g., get_family_day for single-day family plans), so an agent must infer the boundary from context rather than being routed explicitly.

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

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

Beyond the readOnlyHint annotation, the description discloses that returned time-related fields are not guaranteed and explicitly instructs the agent to confirm with get_availability before asserting availability. This is valuable behavioral context that prevents overclaiming.

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

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

The description is two efficiently packed sentences with the trigger condition front-loaded and the caveat placed at the end. Every clause earns its place, and there is no redundant restating of the tool name or 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?

Given the output schema exists and annotations cover safety, the description covers the key behavioral essentials: use case, ranking, seasonal filtering, field uncertainty, and the mandatory confirmation step. Nothing essential is missing 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%, and the schema already documents all six parameters, so the description does not need to redefine them. The description adds no parameter-specific detail beyond the schema, which keeps it at 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?

The description states a specific verb ('Returns'), resource ('currently-on-sale experiences'), and distinct scope ('within the next few hours', 'seasonal products filtered out', 'ranked by popularity'). This clearly differentiates it from sibling tools like whats_on_tonight or get_whats_on_this_week.

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 phrase 'Use this when the user wants something to do within the next few hours' gives a clear triggering condition. It does not explicitly list when-not conditions or name alternatives, but the condition is specific enough to guide selection.

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-destructive behavior. The description adds meaningful context beyond those: results come from a cached graph and semantic relationships, implying they are not computed live and may not reflect real-time changes. This helps set expectations about freshness and result provenance.

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 tight sentences with no wasted words. The usage condition is front-loaded, and the return characteristics are stated in the second sentence. 'Trio-style widgets' is slightly niche but not repetitive 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?

The description fully covers the core invocation scenario and return style, while the output schema and parameter documentation handle the remaining details like max_results, format, and language. The main gap is that it doesn't clarify how this relates to the similarly named find_nearby_experiences, but the tool is otherwise complete enough to use 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%, so the baseline is 3, but the description adds value by translating the context enum values into natural-language scenarios: 'pair with it, do after it, find nearby, or find similar alternatives.' This gives an agent a clearer mental model of what each context option means before opening the schema.

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

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

The description clearly identifies the resource (related experiences for a selected product_id) and the four relationship types: pair, after, nearby, and similar. It also states what is returned (cached graph and semantic related products). It does not explicitly contrast with overlapping siblings like find_nearby_experiences, but the 'trio-style widgets' framing gives some 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?

The description explicitly states when to use the tool: when a widget or client holds a selected product_id and needs related products in one of four relationship modes. It does not provide negative guidance or name alternatives directly, but the trigger condition is clear enough for an agent to route correctly.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the result is 'One rich guide record fusing live catalogue data with theatre expertise', signalling a single aggregated record rather than a list. That is genuine added context, but nothing about rate limits, auth, or freshness beyond the annotation profile.

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 earning their place: the trigger first, then the nature of the record. 'Fusing live catalogue data with theatre expertise' is slightly promotional but conveys that the record mixes live and editorial data. No filler beyond that.

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 values, and it correctly focuses on triggering and content scope. Combined with 100% schema coverage and rich annotations, little is missing. A note on how the slug/product_id choice affects results would make it 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 description coverage is 100%: slug, city_slug, and product_id are all documented with their dependency (slug requires city_slug). The description only restates 'Accepts slug or product_id', which the schema already makes clear. With the schema doing the heavy lifting, the baseline 3 is correct.

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 ('show guide') and enumerates the payload: duration, age guidance, venue/address, curtain times, dark days, suitability, and this week's performances. That is far more specific than a generic 'get details' tool. It does not explicitly differentiate from siblings like get_experience_details, 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?

It gives a clear trigger condition: 'Use this when the user asks about a specific show.' That is actionable context. However, it names no alternative (e.g. search_experiences vs get_experience_details) and states no exclusion, 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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds real context beyond that: server-side date math resolves the Fri/Sat/Sun dates, results are grouped by day, and it is 'Schedule data, not live seat inventory' – a useful boundary against availability 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?

Three compact sentences that front-load the trigger condition, then the mechanism, then the data boundary. No filler or restatement of the name.

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 structure need not be described, and annotations carry the safety profile. The description supplies trigger, scope, grouping, and data-type boundary, leaving little an agent needs to call it 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%, so the baseline is 3. The description goes slightly beyond by explaining that weekend date resolution is server-side, adding meaning to the 'weekend' enum and city parameters that the schema alone does not convey.

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 with scope: 'returns theatre shows in the city with scheduled performances on those days, grouped by day.' The weekend-only, per-day framing implicitly separates it from whats_on_tonight and get_whats_on_this_week, 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?

Opens with an explicit trigger: 'Use this when the user asks what theatre is on this weekend or next.' Clear context, but no when-not guidance (e.g., redirecting seat-availability questions to check_availability beyond the closing caveat).

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 destructiveHint=false, covering safety. The description adds the behavioral outcome (returns estimates with durations, costs, and directions), which goes beyond annotations and provides useful context for what the agent can expect.

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

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

The description is two sentences with no filler. The first sentence front-loads the usage trigger, and the second lists the return content. Every word earns its place, and it is compact enough to parse quickly.

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 presence of a full output schema, complete parameter descriptions, and safety-related annotations, the description covers the essential trigger, input context, and return content. No critical information needed to invoke the tool 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%, as every parameter (city, format, language, from_type, to_latitude, to_longitude) already has a clear description. The tool description itself adds no additional parameter-level meaning, so the baseline of 3 applies since the schema carries the full 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 uses a specific verb('use'), resource ('transfer guidance'), and scope ('airport, station, or port to a hotel coordinate'), clearly distinguishing it from sibling tools that focus on experiences or city guides. It also names the output content ('taxi, metro, bus, and train estimates'), making the tool's purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'when the user is arriving in a supported city and needs transfer guidance.' It does not mention when-not-to-use or name an alternative sibling, but there is no overlapping sibling tool, so the clear trigger context is sufficient guidance.

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

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

Annotations already mark this as read-only and non-destructive, so the description adds useful behavioral context beyond that: it drops out-of-season products, returns search rows rather than a calendar, and instructs the agent to assemble the weekly structure itself. This is strong behavioral disclosure for a safe read operation.

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 concise sentences cover the trigger, core behavior, limitation, and alternative tool call. The most important use-case guidance is front-loaded, and no sentence is wasted.

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

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

The tool has a clear scope, documented parameters, an output schema, and annotations covering safety. The description provides the missing context about ranking, on-sale filtering, out-of-season dropping, and the need to verify specific dates with get_availability. This is complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already fully documents city, format, and language. The description reinforces the overall purpose but adds no parameter-specific meaning beyond 'city' context, which is already clear from the schema.

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

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

The description uses a specific verb and resource ('ideas for the coming week in a city') and clearly defines the result as a ranked list of currently on-sale experiences, distinct from a day-by-day calendar. It also explicitly contrasts itself with get_availability, helping differentiate from sibling 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?

It opens with an explicit 'when to use' trigger: when the user wants ideas for the coming week in a city. It also gives a clear exclusion (not a day-by-day calendar) and names an alternative tool, get_availability, for verifying specific dates.

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 read-only, idempotent, and non-destructive behavior. The description adds useful context by noting the tool returns product counts and is a browsing/pre-search operation, but it does not disclose details like default limit, ordering, or localization behavior beyond what the schema and output schema already imply.

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

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

The description is a single, front-loaded sentence that immediately states when to use the tool and what it returns. Every phrase earns its place, with no filler or redundant restating of the tool name.

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 list tool with four fully documented optional parameters and an output schema, the description provides the necessary trigger context and return summary. There are no hidden side effects, required permissions, or complex usage prerequisites to disclose.

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 each parameter has its own description, so the baseline is 3. The tool description itself mentions the output fields but adds no extra parameter semantics; the schema handles that 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 states a clear verb ('browse') and resource ('supported cities') and explicitly positions the tool as a pre-search step, distinguishing it from the many search and recommendation siblings. It also names the return payload (city names, slugs, country codes, product counts), making its role 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?

The description gives explicit context for when to use the tool ('when the user wants to browse supported cities before searching'). It doesn't name specific alternative tools or give exclusion criteria, but the phrase 'before searching' adequately guides selection relative to the sibling search 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 readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds meaningful behavioral detail beyond the schema: it parses for audience, mood, constraints, occasion, and time of day, and returns scored recommendations with a reason field. This helps the agent anticipate the tool's reasoning and output characteristics.

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

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

The description is two sentences with no filler. The usage trigger is front-loaded, the parse behavior is summarized in a compact list of dimensions, and the output characteristic (scored recommendations with reason field) is included without redundancy.

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

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

Given the output schema exists and annotations cover safety and idempotency, the description is complete enough for tool selection and invocation. It covers the trigger, parse behavior, and result shape. It could more explicitly distinguish from overlapping siblings like compare_experiences or get_date_night, but this is not a critical 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 baseline is 3. The description adds extra semantic value by specifying the dimensions parsed from the query (audience, mood, constraints, occasion, time of day), which enriches understanding of the query parameter beyond the schema's examples. This justifies a slight upgrade.

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 trigger (user describes desires in natural language), names the tool's action (parses and returns scored recommendations), and distinguishes it from category-based tools by saying 'rather than naming a category.' This makes it clear how recommend_experiences differs from siblings like search_experiences or search_by_mood.

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 opens with an explicit when-to-use condition: use this tool when the user describes preferences in natural language rather than naming a category. It gives a clear exclusion ('rather than naming a category') but does not name a specific alternative sibling tool, so the guidance is strong but not fully explicit about alternatives.

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 (readOnlyHint, destructiveHint=false, idempotentHint, openWorldHint=false), and the description adds real behavioral constraints beyond them: pass only product_id values and never full product rows, and render a single card view per result set to avoid duplicate cards. It omits any mention of the idempotency_key reuse window, which 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?

Front-loaded with the use condition, then parameter guidance, then the duplicate-avoidance constraint; every sentence carries an instruction. It is slightly dense and could be tightened, but there is 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?

An output schema exists so return values need no explanation, and the description covers trigger, ID-sourcing, render_type selection, optional context, and duplicate avoidance for a 4-parameter nested-schema tool. Only the idempotency_key behavior is left entirely to 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it maps experience_ids to 'the product_id values from that result' and clarifies that render_context (whose inner intent_summary is required by the schema) is itself optional and used to set the heading. The 'never full product rows' warning guards a real misuse mode not stated in the schema.

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

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

The description frames the tool as a rendering/presentation step for a 'discovery result from a supported search tool', which distinguishes it from the many search_*/get_* siblings that produce results rather than display them. The action verb is implicit ('cards would help present') rather than stated as 'renders cards', so it is clear but slightly trigger-phrased rather than action-phrased.

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 when-to-use condition ('when visual cards would help present a discovery result') plus an operating constraint ('keep each result set to one card view to avoid duplicate cards'). It does not name a specific alternative or state when-not to render, so it falls short of explicit routing 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 idempotentHint, readOnlyHint, and destructiveHint, so the bar is lowered. The description adds useful behavioral context: the 30-day validity window, the requirement for a 'real forward-event' request, and idempotency per caller. No contradiction with annotations exists.

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

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

Three dense sentences: purpose, examples, and key constraints. Every sentence adds value, and the most important information is front-loaded. No wasted words or repetition of schema details.

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 moderate complexity (3 params, rich schema, output schema, useful annotations), the description covers purpose, examples, prerequisite, and idempotency. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema itself already documents formats, constraints, enums, and special cases (e.g., notes required for 'other', PII exclusion). The description adds no significant parameter-level meaning beyond restating the 30-day requirement already in the schema, 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?

States a specific verb ('push') and resource ('quality signal back to tickadoo') with a clear target ('an experience or recommendation you previously surfaced'). Concrete examples clarify the scope, and the operation is clearly distinct from the sibling tools, which are all retrieval/planning/search 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?

Provides clear context for when to use the tool, including concrete scenarios (stale availability, failed click-through, supplier outage, misleading content) and a prerequisite (real forward-event request_id within 30 days). It does not explicitly name alternatives or when-not-to-use cases, but no sibling tool performs a similar function, so the guidance is sufficient.

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 signal read-only, idempotent, and non-destructive behavior. The description adds useful context beyond the schema by revealing that moods are mapped to preset search filters rather than used as free-text search keywords. This is meaningful behavioral information without contradicting the annotations.

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

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

The description is two tight sentences with the usage trigger front-loaded and the core behavior stated immediately after. Every sentence earns its place, and there is no redundant detail or filler.

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

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

With full parameter schema coverage, an output schema, and read-only annotations, the description provides exactly the missing contextual information: when to invoke the tool and what distinguishes it from category-based search. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds a few mood examples, but these are also present in the enum. It does not add deeper meaning for city, limit, format, or language beyond the structural schema, so the baseline score of 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 clearly states a specific trigger ('when the user describes the feeling or vibe they want') and a specific behavior ('Maps the mood to preset search filters and returns matching experiences'). It distinguishes itself from category-based search, which separates it from sibling tools like search_experiences.

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: when the user describes a feeling or vibe rather than a category. The examples help an agent identify the right call, but it does not explicitly name an alternative tool or state when not to use it, so it falls short of full routing 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/non-destructive, so safety is covered. The description adds the non-obvious fallback behavior (match_type "fallback_city_ranked", reason_codes including "fallback_no_text_match") and the downstream render_experience_cards handoff, which are real behavioral disclosures beyond structured data. It does not cover pagination or rate limits, so not 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 alternatives, then fallback caveat, then return fields, then composition hints. Dense and mostly waste-free, though the return-field enumeration is partially redundant with the output 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 13-parameter search tool with a full output schema, the description covers the decision context, the silent-fallback pitfall, and composition with sibling tools. Return values are listed despite an output schema existing, which is slight redundancy rather than 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% and the schema itself is unusually rich (tag taxonomy, price cap semantics, the restrict_to_top_rated WHERE-clause warning). The description mainly restates query semantics already documented in the schema, so 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?

Opens with a precise verb+resource+trigger condition: a named city plus category/query/filter set yielding a ranked list of bookable experiences. It explicitly distinguishes itself from search_by_mood (mood/theme) and recommend_experiences (free-text 'what should I do'), 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?

Names the two closest alternatives and the exact conditions that select them. It also flags the edge case where a non-matching query silently yields city top-picks, telling the agent when results are not genuine matches.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely valuable behavior the schema/annotations do not: that the topic argument performs no filtering and every topic yields the same city ranking, plus an explicit note that no tips/logistics text is returned. That is exactly the kind of honesty that prevents misuse.

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 sentences, front-loaded with the usage trigger followed by the return shape and the caveats. Every sentence carries information; minor room to tighten the redundancy between the topic caveat and the payload note.

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 not be explained, and annotations cover the safety posture. The description completes the picture by flagging the topic no-op and the absence of tips/logistics content. Only the sibling-disambiguation gap 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 the schema already documents city, the topic enum, format and language. The description's statement that topic is a no-op duplicates the schema's own note but reinforces it, which is helpful yet not net-new information. 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 (ranked search of bookable experience rows) and scopes it to a city plus keyword/topic. It does not name any of the many sibling search tools (search_experiences, search_local_experiences, search_by_mood), so an agent cannot fully disambiguate from siblings on the description 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?

Gives a clear trigger condition ('when the user asks for bookable experiences by keyword or topic in a city'), which is real guidance. However, with ~27 siblings including several near-identical search tools, it offers no when-not or alternative routing, so the agent must infer which search tool to pick.

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 disclose readOnly, idempotent, non-destructive, and non-open-world behavior. The description adds useful behavioral context beyond annotations: results are matched first by exact venue/neighbourhood, then by city centre fallback. It does not detail pagination or rate limits, but output schema coverage reduces that burden.

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 usage condition, followed by examples, return behavior, and an exclusion. It is appropriately sized for the amount of selection guidance needed, 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?

Given the existence of an output schema and 100% schema description coverage, the description does not need to explain return fields or parameter syntax. It covers the key selection criteria, fallback behavior, and the sibling alternative, making it complete for an agent to choose and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters thoroughly, including tags, date fields, radius_hint, and place_hint. The description reinforces place_hint semantics through examples and fallback behavior, but does not add meaning beyond the rich schema for the remaining 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?

The description states a specific action and resource: searching local experiences based on a place reference. It clearly distinguishes this from general city-wide search by naming search_experiences as the alternative, and gives concrete examples such as 'near the Louvre' and 'in Trastevere'.

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 explicit when-to-use guidance ('when the user mentions a place, neighbourhood, landmark, or area but does not give exact coordinates') and explicit when-not-to-use guidance ('Do not use for general city-wide search; use search_experiences for that'). The alternative tool is named directly.

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 description richly discloses behavior beyond the annotations: out-of-season filtering, evening-led ranking, multi-day passes/transport ranked last, start_time presence meaning a confirmed live-supplier evening slot, and the sort semantics within a relevance band. It also explains what missing start_time means, which is critical for correct interpretation.

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

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

Every sentence earns its place: the trigger, the ranking behavior, the start_time semantics, and the required confirmation step. The description is dense but not bloated, and the most important usage condition 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?

With an output schema present, return structure is covered externally. The description supplies the query intent, ranking/filtering rules, a caveat about unconfirmed times, and a mandatory next step. An agent has enough information to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so parameter meaning is already fully documented in the input schema. The description adds context about the tool's overall behavior but does not need to repeat parameter details. This meets the baseline for a fully covered 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: returns evening-appropriate experiences for a city tonight. It clearly differentiates from siblings like get_whats_on_this_week by anchoring on 'tonight' and the user's 'what is on' intent. The scope is further sharpened by filtering and ranking constraints.

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 condition: 'Use this when the user asks what is on in a city tonight.' It also tells the agent to follow up with get_availability before confirming bookability. It does not enumerate when to prefer sibling tools like get_whats_on_this_week or search_experiences, so it falls just 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.