Event Escapes

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

Beyond the annotations (readOnlyHint=true, etc.), the description discloses user-facing behavior: landing page shows ticket categories, hotels near venue auto-load, and the user completes booking themselves. It also explains the optional hotel_id pinning effect. This adds contextual richness beyond the safety hints.

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 well-structured: first sentence states the core purpose, then user experience, optional parameter behavior, and a clear non-reservation caveat. It is front-loaded and every sentence contributes meaning 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?

For a tool with 6 parameters and no output schema, the description covers the purpose, user journey, optional parameter effect, and an alternative tool. It fully equips an agent to decide when and how to use it, with no significant gaps given the schema richness.

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% (all parameters have descriptions), so baseline is 3. The description adds no new parameter-specific meaning beyond what the schema already provides. It mentions hotel_id behavior, but the schema already documents it identically. No extra value is added over the structured definitions.

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

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

The description clearly states the tool's function: 'Generate a deep link to the Event Escapes event detail page.' It specifies the resource (deep link to event detail page) and distinguishes it from sibling tools by explicitly naming build_package_link as the alternative for curated packages.

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 explicit usage guidance: 'For curated packages, use build_package_link instead' names a direct alternative. It also clarifies when not to use the tool with 'This does NOT make a reservation; it is purely a navigation aid,' setting clear expectations for navigation vs. booking scenarios.

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 discloses that the tool only generates a link and does not perform a reservation, which is beyond the annotations' read-only/idempotent hints. It also notes the tool is for curated packages and emphasizes user interaction on the package page. While annotations already cover safety, the description adds clarity about the tool's non-reservation behavior and its role in the user 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?

The description is three sentences long and front-loaded with the action and resource. It earns every sentence by providing purpose, usage context, and a clear limitation, with no fluff 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?

The tool is simple (generates a link) and the description covers its purpose, when to use it, and what it does not do. Annotations cover safety, and all parameters are documented in the schema. No output schema is needed because the output is self-evident. The description is complete for guiding an agent.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds minimal parameter-specific meaning beyond stating it surfaces a package; it does not explain parameter formats or constraints. However, it reinforces that parameters come from search_packages results, which is useful context but not required because schema already documents each field.

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

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

The description clearly states the tool's function: 'Generate a deep link to a curated Event Escapes PACKAGE detail page'. It specifies the resource (package detail page) and the action (generate deep link), and differentiates from siblings by focusing on packages and explicitly referring to search_packages. The phrase 'does NOT make a reservation' further clarifies its non-booking role.

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 provides explicit usage context: 'Use this AFTER calling search_packages to surface a specific package to the user.' It also states when not to use it: 'This does NOT make a reservation - the user reviews tier/duration/guest selectors and books on the package page.' This clearly directs the agent to use it only after search, and not as a booking action.

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, openWorldHint, idempotentHint, and destructiveHint=false, which cover safety and side effects. The description adds value by disclosing what return fields the tool provides, which is not in annotations. It doesn't contradict annotations, and while it doesn't discuss error behavior, the read-only nature and idempotency reduce the need. The added return-content detail goes beyond annotations, so a 4 is appropriate.

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, front-loaded with the core action and data scope, immediately followed by identifier instructions. Every word earns its place—no filler, no repetition of the title or annotations. This is an exemplary concise structure.

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

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

With no output schema, the description compensates by listing the key return fields (title, venue, date/time, price range, description, image gallery), which sets expectations for the response. It also clarifies the required identifiers. It doesn't cover currency or potential errors, but for a simple read-only lookup with strong annotations, the description is largely complete. A 4 reflects the minor gaps.

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 0% (no descriptions on properties), so the description carries the burden. It explains event_id and slug, including that they are alternatives (via 'or') and that slug comes from search_events, which is helpful. However, it entirely omits the 'currency' parameter, which is part of the schema with an enum. This partial coverage leaves a clear gap, so a 3 is fair.

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

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

The description clearly states the tool's purpose: 'Get full details for one event' and enumerates the specific fields returned (title, venue, date/time, price range, description, image gallery). This differentiates it from sibling tools like search_events (which lists events) and build_event_link (which builds links). The verb 'get' plus the resource 'full details for one event' make a specific and unambiguous purpose.

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 instructs to provide either event_id (UUID) or slug from search_events results, giving clear context on how to obtain valid inputs. It doesn't explicitly state when not to use this tool or name alternatives, but the guidance 'from search_events results' implies a workflow and distinguishes from searching. This is clear context without formal exclusions, meriting a 4.

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 behavioral context by noting prices are estimates and that the output is raw event inventory (tickets only), which is not captured by 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 concise and front-loaded: the first sentence states the core function, followed by coverage, filters, return type, alternative tool, and pricing note. Each sentence adds value, though it could be slightly more compact.

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 no output schema and no parameter descriptions, the description covers the main use case and key filters but lacks details on output structure, pagination, or parameter behaviors like limit and currency. It is adequate for basic orientation but not exhaustive.

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 0% schema description coverage, the description must compensate. It mentions filterable fields (sport, city, country, date range) but omits limit and currency parameters. Thus, it only partially clarifies the parameter meanings beyond the schema.

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

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

The description clearly states the tool's function: searching upcoming sporting and music events. It enumerates the covered event categories and explicitly distinguishes itself from search_packages by specifying it returns raw event inventory (tickets only), making the purpose 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 provides clear usage context by noting that search_packages should be used for curated trip packages, and that this tool returns raw tickets. However, it does not mention other sibling tools like get_event_details or search_experiences, so guidance on all alternatives is incomplete.

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, openWorldHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: the default 7-day date window and the specific return fields (name, price, duration, image, free cancellation). This enriches the agent's understanding beyond the annotations.

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

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

The description is three sentences, each adding distinct value: purpose, default behavior, and return data. No redundant or filler content; it is front-loaded and efficient.

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?

Without an output schema, the description compensates by listing return fields. It also explains the data source and default date logic. Remaining gaps (like parameter interplay) are minor given the schema provides formats and defaults, making the overall description sufficiently complete for the tool's complexity.

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 0% schema description coverage, the description carries the burden of explaining parameters. It clarifies that 'city' is the target, indirectly maps categories (tours, attractions, food, nightlife) to the category enum, and explains the date-range default. However, it does not explain limit, country, or currency, leaving some parameters underspecified.

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

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

The description opens with 'Find activities, tours, attractions, food experiences, and nightlife in a city (sourced from Hotelbeds)', which clearly states the action and resource. This distinguishes it from sibling tools like search_events or search_hotels_near_event which focus on different domains.

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 clearly indicates this is for searching city-based experiences and notes the default date range behavior. While it doesn't explicitly name alternatives or exclusions, the scope is well-defined enough for an agent to infer when to use this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond that: it explains the automatic 2-night stay default when no dates are provided and enumerates the specific return fields (nightly price, total cost, distance, transport mode, travel time). This exceeds annotation-only information, though it omits details like pagination 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?

The description is two sentences, front-loaded with the primary purpose, and includes essential behavioral and output information without redundant wording. Every clause adds value.

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

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

Given 8 parameters and no output schema, the description covers the core purpose and return fields, making it adequate. However, it leaves many parameter meanings and usage exclusions unaddressed, so the agent still has to infer significant details. This is a clear gap for a tool of this complexity.

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 0% schema description coverage and 8 parameters, the description must compensate. It explains the check_in/check_out default behavior and implies a radius via 'walking or short-transit distance', but it fails to explain event_id/slug, limit, guests, currency, and radius_km. This leaves most parameters semantically opaque to the agent.

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 the specific verb 'Find' and clearly identifies the resource as 'hotels near event venue'. It also specifies the scope (walking or short-transit distance) and lists the return fields, which distinguishes it from sibling tools like search_events or search_packages.

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 clearly implies when to use this tool—when hotel accommodations near an event are needed. It does not explicitly name alternatives or provide exclusions, but it provides clear context about default date behavior and output, which helps an agent decide on invocation.

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 the safety profile is established. The description adds useful behavioral details beyond annotations: packages live on dedicated /packages/ pages, include preview hotel, ticket category, and sometimes experience list, and 'Prices include all package components.' These specifics clarify what results will contain and how pricing works.

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 concise and well-structured: it opens with a clear one-sentence purpose, then gives a compact list of filtering dimensions, and ends with a direct usage guideline. Every sentence contributes unique information 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?

For a search tool with no output schema, the description explains what packages include (preview hotel, ticket category, sometimes experience list) and that prices include all components, giving the agent a solid picture of the return content. It does not mention pagination or default limit behavior, but the schema's limit parameter defines constraints, so the omission is minor.

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

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

Schema description coverage is 50%, and the description meaningfully supplements the category and package_type enums by listing common values and their meanings (e.g., 'f1 (Formula 1 race weekends)', 'city_multi (multi-event city trips)'). However, parameters like limit, currency, and date range are not fully described in the tool description, leaving gaps that the schema descriptions don't fully fill for those missing ones.

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

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

The description clearly states the tool's function: 'Search hand-curated trip packages bundling event tickets + hotel + experiences with savings vs DIY booking.' It identifies the resource (trip packages) and the specific action (search), and explicitly differentiates from sibling search_events by directing users to 'use search_events' for raw event inventory.

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

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

Usage guidance is direct and actionable: 'Use this when the user wants a complete trip recommendation' and 'For raw event inventory only, use search_events.' This explicitly contrasts the tool with its primary alternative, providing clear when-to-use and when-not-to-use instructions.

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