agentorist

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

Annotations indicate destructiveHint=true, consistent with the described booking action. The description adds valuable behavioral context: it explains the two possible outcomes (inline confirmation or affiliate link) based on API connectivity. This goes beyond the annotation by detailing what happens in each scenario.

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 composed of two concise sentences, front-loaded with the core purpose. No extraneous information; every sentence is justified. It is well-structured for quick comprehension.

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 (indicated by context signals), the description need not detail return values. It covers the two operational modes, affiliate fallback, and logging. It does not mention error handling or rate limits, but for a booking tool this is acceptable. Overall, it provides sufficient context for effective use.

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 input schema has 100% description coverage, so the schema already fully explains all 7 parameters. The tool description does not add significant new semantic meaning beyond referring to 'option_id' and 'vertical' implicitly. It briefly mentions affiliate fallback and logging for some parameters, but this adds marginal value.

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 ('Book') and resource ('option'), and clearly distinguishes from siblings like 'find_options' (which lists options) and 'request_unsupported_booking' (for non-standard bookings). It explains the booking flow depending on API connectivity, making the tool's 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 explicitly states when to expect an inline confirmation vs. an affiliate deep link, guiding the agent on what to return to the user. It does not explicitly list when not to use, but the context of siblings provides that clarity. Overall, the guidance is strong for decision-making.

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 set readOnlyHint=true, so the description's main behavioral claim is that it finds options without side effects. The description adds no significant behavioral details beyond that, earning a baseline score of 3.

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 extremely concise at two sentences, with the first sentence giving the core purpose and the second clarifying usage per vertical. No unnecessary words.

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 explains the two main verticals but fails to mention that the 'location' parameter is required for movies (though the schema describes this). Given the presence of full schema descriptions and an output schema, the description is mostly complete but has a minor 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?

The input schema has 100% coverage with detailed descriptions for all 5 parameters. The tool description does not add new semantic insights beyond the schema, so it meets the baseline expectation.

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 finds concrete bookable options for an item and gives specific examples for movies (showtimes) and events (ticket classes). This distinguishes it from the sibling 'search' tool that returns items, and from the 'book' tool that performs the booking.

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 implicitly indicates this tool should be used after selecting an item via 'search', as it takes an item_id. However, it does not explicitly state when not to use it or mention alternatives like 'search_all' or 'book'.

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 indicate readOnlyHint=true. The description adds that venues are 'marked as bookable or not', which provides useful context. However, it does not disclose other behaviors like rate limits, authentication needs, or pagination.

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 concise sentence with no filler. It efficiently conveys the tool's purpose.

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 an output schema, the description does not need to detail return values. However, it could provide more context on what 'bookable' means or how results are ordered. Overall, it adequately complements the schema and annotations.

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 baseline is 3. The description adds minimal value beyond the schema: it relates 'location' to 'near a location' but does not elaborate on other parameters or their formats.

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 verb 'list' and resource 'venues' with a specific condition 'near a location' and additional attribute 'marked as bookable or not'. This distinguishes it from sibling tools like 'search' and 'search_all', which are more general.

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 implies use when needing venues near a location with bookable status, but does not explicitly state when to use this tool versus siblings or provide any exclusions or prerequisites.

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 description adds return structure (dict with name/description). No additional behavioral traits beyond what annotations imply. Output schema exists but not detailed.

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 succinct sentences, front-loaded with purpose. Every sentence adds value 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?

Adequate for a zero-parameter tool with output schema. Could mention that no arguments are required, but overall complete given simplicity.

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?

No parameters, so baseline 4 applies. Description doesn't need to add parameter meaning.

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?

Description clearly specifies the action (List), resource (booking verticals), and scope (all supported). It also distinguishes from siblings by advising to call this first before constructing other tool calls.

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 call ('first') and why ('to discover what's bookable'). No explicit 'when not to use' but the context is clear for a discovery tool.

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

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

Annotations only provide destructiveHint: true. The description adds meaningful behavioral context: data is sold as monthly missed-revenue insight, and optional email notification when the venue joins. This goes beyond the annotation, though it could mention data retention or privacy implicitly.

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. The first states the core purpose, the second provides business context, and the third adds optional functionality. No redundancy or unnecessary 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 (9 parameters, output schema present), the description covers the essential purpose and business rationale. It does not explain error conditions or post-conditions, but the output schema likely handles return values. The description is adequate for an AI agent to understand when and why to use this tool.

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

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

Schema coverage is 100%, so all parameters are already described in the input schema. The description adds value for the 'user_email' parameter by explaining its purpose for join-notification. Overall, meaning is adequately provided by the schema.

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

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

The description clearly states the tool's purpose: 'Log a booking request Agentorist can't yet fulfil.' This specific verb-resource combination distinguishes it from siblings like 'book' (actual booking) and 'list_venues' (listing capabilities).

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 implies usage when a booking cannot be fulfilled (demand-intelligence engine), but does not explicitly state when to use this tool versus alternatives like 'book' or 'search'. No exclusions or alternative comparisons are provided.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds no further behavioral context such as rate limits, pagination, or result structure. With annotations present, the description adds minimal value beyond confirming read-only intent.

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, efficient sentence with no wasted words. It is front-loaded and to the point. A 5 would require more comprehensive coverage while remaining concise.

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 (not shown), the description does not need to explain return values. However, for a search tool with 7 parameters, the description is too sparse; it lacks context on pagination, sorting, default ordering, or result limits. This under-specifies the tool's behavior.

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

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

Schema coverage is 100% with detailed descriptions for all parameters (e.g., vertical references list_verticals output, query is natural-language). The description does not add significant meaning beyond what the schema already provides, 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?

The description clearly states the verb 'Search' and the resource 'bookable items', and scopes it 'within a vertical'. This distinguishes it from sibling tools like search_all (no vertical limit) and list_venues (list venues, not items).

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 does not explicitly state when to use this tool versus alternatives like search_all or list_venues. While the verb 'search' and scope 'within a vertical' imply that it is for searching in a specific vertical, no when-not-to-use guidance or alternative references are provided.

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

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

Annotations declare readOnlyHint=true; description adds output structure (results_by_vertical, counts). No contradiction. Provides useful behavioral context beyond annotations.

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

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

Two short paragraphs, front-loaded with main purpose, each sentence adds value. No fluff.

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 output schema exists and parameters well-documented, description covers key behaviors, usage guidance, and result structure. Missing some edge cases but adequate for a search tool.

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

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

Schema coverage is 100%, so baseline applies. Description doesn't add significant new meaning to individual parameters beyond the schema, but explains overall auto-narrowing behavior.

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 it searches all Agentorist verticals at once, with concrete examples like 'what's on?'. It distinguishes itself from single-vertical tools, making 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?

Explicitly tells when to use (spanning verticals, vague queries) and mentions automatic narrowing for single-vertical hints, though doesn't name specific sibling tool for those cases.

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