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?

The 'readOnlyHint' annotation already assures safety, and the description adds the context of 'bookable items' without contradicting annotations. No further behavioral traits (e.g., authentication, pagination) are disclosed, but annotations reduce the 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 a single six-word sentence that immediately conveys the tool's purpose with no extraneous information. It is maximally 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?

Given the presence of an output schema and annotations, the description provides minimal additional context. It is adequate but does not explain return structure, result scoping, or edge cases.

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% parameter description coverage, so the description adds no additional meaning beyond 'within a vertical.' The baseline of 3 is appropriate given the schema richness.

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 within a vertical,' differentiating from sibling 'search_all' which presumably cross-cuts verticals. It does not, however, explicitly contrast with other search-related 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?

The description implies usage when a specific vertical is known via the required 'vertical' parameter, but it provides no explicit when-to-use or when-not-to-use instructions relative to alternative tools like 'search_all' or 'find_options'.

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

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

Annotations mark readOnlyHint=true, and description adds details on return structure (results_by_vertical, counts) and auto-narrowing behavior. No contradiction.

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 paragraphs, each with clear purpose. Efficiently front-loaded. Could be slightly tightened (e.g., combine last two sentences), but no wasted 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?

Given output schema exists, description needn't detail return values. It covers purpose, usage, auto-narrowing, and key parameters. Complete for effective tool selection.

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 covers 100% of parameters with descriptions. Description adds value by clarifying query can be empty for browsing and explaining when parameter usage affects behavior (auto-narrowing).

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 'Search every Agentorist vertical at once' and positions it as the answer to 'what's on?'. It distinguishes from siblings by noting auto-narrowing for single-vertical queries.

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?

Explicit guidance: use when request spans verticals or is vague ('what's on tonight'), and for specific queries it auto-narrows. Provides examples and implies when not to use (single vertical) with mention of 'search' as alternative.

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