events

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

Description says 'add' implying mutation, but annotation readOnlyHint=true indicates read-only. This is a direct contradiction. No additional behavioral details provided.

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?

Single sentence, concise and to the point, with no wasted words. Front-loads the purpose effectively.

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?

Despite high schema coverage and existence of output schema, the annotation contradiction undermines completeness. Missing details about error handling or calendar file format. Incomplete for a create operation.

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 parameter descriptions are already clear in the schema. The tool description does not add extra meaning beyond what is 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?

Description clearly states the action ('add a Dizko event to their calendar') and the context ('after choosing or buying tickets'), which effectively distinguishes this tool from 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?

Provides specific usage condition ('after choosing or buying tickets'), offering clear context. No explicit when-not or alternative tools mentioned, but the condition itself acts as a usage guideline.

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 provide no destructive or read-only hints, and the description adds a key condition (must not have existing profile) but does not disclose what happens if consent is false or if a profile exists (e.g., error vs overwrite). No mention of authorization or side effects.

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 sentence front-loaded with the use case. While concise, it could be restructured to list key conditions more clearly. No verbose filler, but it trades completeness for brevity.

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 complex nested input schema and the presence of an output schema (not shown), the description is too minimal. It does not explain return values, error conditions, or the full semantics of preferences and day_filters, which are critical 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 50%, but the tool description only adds meaning to the consent parameter (must be true after user agreed) and partially explains day_filters (additive/override). Many nested parameters are left unexplained, forcing the agent to rely on 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?

The description clearly states the tool creates a preference profile when the user explicitly agrees and does not already have one. It uses a specific verb ('create') and resource ('event preference profile'), and the condition distinguishes it from update/delete 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?

The description gives explicit conditions for use ('when a user explicitly agrees...does not already have a profile') implying when to use vs. alternatives like save_event_preferences. However, it does not name the alternative tool explicitly, so it falls short of a 5.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds specificity about what is deleted (preferences and feedback history) but does not disclose other behaviors like permissions or side effects.

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 sentence that is concise and front-loaded with the purpose. Every word is necessary and there is no wasted text.

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 simplicity and the presence of comprehensive schema descriptions and annotations, the description is adequate but minimal. It could mention the need for user confirmation or the irreversible nature, but these are covered elsewhere.

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?

Input schema has 100% coverage with clear descriptions for each parameter. The description does not add any extra meaning beyond the schema, so 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 uses specific verb 'delete' and resource 'Dizko saved event preferences and feedback history'. It clearly distinguishes from sibling tools like get_event_preferences and save_event_preferences.

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 'Use this only when a user asks to delete', providing clear context for when the tool should be invoked. However, it does not elaborate on when not to use it or mention 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool uses a profile's featuring list and that artists can be omitted, but these are parameter behaviors rather than new behavioral traits 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 sentences with zero wasted words. The description is front-loaded with the primary use case, followed by the alternative mode. It is appropriately sized for the tool's simplicity.

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 comprehensive parameter descriptions, the description covers the essential use cases. The tool is straightforward (read-only query), and the description provides sufficient context for the two ways to invoke it.

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 each parameter is well-documented. The description adds value by clarifying the two usage modes (explicit artists vs. profile-based), which groups parameters meaningfully. This goes beyond the individual parameter descriptions.

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 fetches upcoming events for artists, specifying types like DJs, performers, comedians. It distinguishes between explicit artist lists and using profile saved lists, 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 explicitly states when to use the tool (asking about upcoming shows) and describes the alternative of using a profile's saved artists. However, it does not differentiate from sibling tools like search_events, which might offer similar functionality.

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, destructiveHint. Description adds value by detailing the type of output (busiest nights, top venues, genre mix, headline events with evidence counts), enhancing behavioral understanding beyond safety traits.

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 well-structured sentences, no wasted words, front-loaded with usage context. Every sentence 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?

Given the tool has an output schema and 4 parameters with full schema coverage, the description adequately covers the high-level output and context. No missing information for an agent to select and invoke 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% with parameter descriptions. The tool description does not add additional meaning beyond what the schema already provides, so baseline score 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?

Description uses specific verbs and clarifies the resource ('city pulse' aggregated event scene). It distinguishes from sibling tools like search_events or get_artist_events by focusing on aggregate trends and momentum.

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 ('when a user asks what is hot, where the momentum is'), providing clear context. Lacks explicit when-not or alternative tool mentions, but the context is sufficient for 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 readOnlyHint and idempotentHint, so the agent knows it's safe. The description adds behavioral context about personalization via profile_id/profile_secret and date handling, which is valuable information 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?

The description is two sentences, efficient and front-loaded with the main purpose. It could be slightly more structured with bullet points, but it conveys essential information without wordiness.

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 15 parameters, only 1 required, and an output schema exists, the description provides enough context for the agent to understand the tool's purpose and when to use it. It explains personalization and date handling, though it doesn't detail all parameters or the return structure.

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 60%, and the description adds meaning to profile_id/profile_secret by explaining they personalize picks. For other parameters like free, vibe, or event_types, the description only hints at categories but doesn't fully compensate for missing schema descriptions. 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 states the tool provides a daily digest of events in a city, including specific sections like parties, live music, and art. It distinguishes itself from siblings by emphasizing personalized picks and daily roundup format, which is different from search_events or recommend_events.

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 says 'Use this when a user wants a daily digest' and 'Ideal for recurring morning briefings', providing clear usage context. It does not explicitly list alternatives or when-not-to-use, but the context effectively guides selection among 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, idempotentHint, destructiveHint. Description adds no additional behavioral traits 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?

Single sentence, no wasted words, front-loaded with purpose. Efficient and clear.

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?

Tool has output schema, so description needn't explain return values. However, description is minimally adequate; could mention that it returns full event details.

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 parameter 'id' with description 'Event id.' Description does not add further details about format or source beyond mentioning origin in search/recommendations.

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 retrieves details for a specific Dizko event by its ID, distinguishing it from sibling tools that perform searches or create resources.

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

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

Specifies use when a user asks for details about an event ID from search, recommendations, or night plan. Clear context but lacks explicit when-not-to-use or alternative 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 indicate readOnly, idempotent, non-destructive. The description confirms it's a prompt generator, adding that it's for asking a follow-up. No contradiction; the description complements annotations with specific behavior context.

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

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

Single sentence that is front-loaded and conveys the essential condition and purpose. Every word earns its place with no redundancy.

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

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

Given the output schema exists, the description doesn't need to detail return values. It adequately covers when and why to use the tool. Could be slightly more specific about the prompt's role, but context is complete enough.

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% (only attended_at documented). The description does not add meaning for event_id or clarify attended_at beyond the schema. It relies on defaults and lacks compensation for the undocumented parameter.

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 generates a prompt for post-event follow-up, specifying the condition (user previously picked/attended an event) and purpose (before recording feedback). It distinguishes from sibling record_event_feedback by indicating it's a preliminary step.

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 begins with 'Use this when...' providing explicit guidance for when to invoke the tool. It implies this is a step before record_event_feedback, but doesn't explicitly state when not to use it or list 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 declare readOnlyHint=true and destructiveHint=false. The description adds context about returning saved preferences and learned signals, which goes beyond annotations. No behavioral contradictions.

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 with no redundant information. Every word is purposeful.

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 simplicity (read-only getter), the presence of full annotations, complete schema coverage, and an output schema, the description is sufficient and complete for an AI agent to understand the tool's purpose and 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?

Schema coverage is 100% and both parameters are described in the schema. The description does not add any semantic information beyond what the schema provides.

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 'view' and the resource 'saved event preferences or learned recommendation signals'. It effectively distinguishes the tool from siblings like 'save_event_preferences' and 'delete_event_preferences'.

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 says 'Use this when a user...' setting clear usage context. It does not provide when-not-to-use or explicit alternatives, but the sibling tool list implies adequate differentiation.

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 adds value beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining that the tool asks only missing questions, implying it does not modify data and that it avoids redundant queries. This behavioral nuance is useful for the agent.

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 sentence that front-loads the trigger condition and the action. Every word is necessary; no redundancy or filler. Excellent conciseness.

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 simple interaction (output questions), the description adequately covers the context. It doesn't detail the output structure, but an output schema exists. It could mention that the tool returns questions to ask, but overall it is complete for a focused follow-up 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 description coverage is 45% (low), so the description should compensate but does not. It provides no explanation of the 20 parameters (e.g., city, vibe, free). The meaning of these parameters in the follow-up context is left to the schema, which itself has gaps. The description could clarify which parameters represent 'missing' fields to ask about.

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: to ask missing preference questions (event type, vibe, budget, area, avoid) when a user asks for events in specific timeframes (tonight, this week, weekend). It distinguishes from the many sibling search/recommendation tools by specifying the pre-search conversational step.

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 says when to use this tool ('when a user asks for events tonight, this week, or this weekend') and what to do ('ask only the missing ... questions before searching'). It provides clear context but does not explicitly list alternatives or state when not to use it; however, the intent is clear enough.

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 agent knows it is safe and non-destructive. The description adds context about 'consent-first questions', which is useful but does not provide deep behavioral details 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?

The description is a single sentence that is front-loaded with the use case. No unnecessary words or repetition.

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 tool with one optional parameter and an output schema, the description adequately sets context. It could mention that profile_id is optional and describe default behavior, but overall it is sufficient.

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 a clear description for profile_id. The tool description does not add any additional meaning about the parameter, so 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 the tool is for when a user wants personalized recommendations and consent questions are needed, distinguishing it from get_event_preferences (which retrieves saved preferences) and save_event_preferences. However, the exact return value (onboarding questions) is implicit, not explicit.

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 specifies a concrete scenario ('when a user wants personalized event recommendations and Dizko needs consent-first questions before saving event preferences'), implying when to use. It does not explicitly state when not to use or name alternative tools for other cases.

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 description adds only domain context ('ticket options') which is consistent. No contradictions.

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?

Single, front-loaded sentence with zero wasted words. Perfectly 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?

For a simple one-parameter tool with output schema, the description adequately covers purpose and usage. No gaps given the low 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?

Schema provides complete description for the single parameter (event_id). Description adds no further semantics, so baseline 3 is appropriate given high schema coverage.

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?

Clearly states verb (get), resource (ticket options for a specific Dizko event), and context (before quoting or buying). Distinguishes from sibling tools like search_events or purchase_ticket_order.

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 ('before quoting or buying'), implying it's the correct tool for pre-purchase ticket options. Does not list when not to use or suggest alternatives, but context is clear enough.

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. The description adds behavioral context by specifying the exact queries it handles (autonomous buying, purchase modes), which goes 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 a single sentence that is concise, front-loaded, and contains no superfluous information. Every part 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?

Given the tool has no parameters, a read-only annotation, and an output schema exists, the description is complete. It tells the agent exactly when to use it and what it retrieves.

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?

There are zero parameters, so the description does not need to add parameter information. The baseline for 0 params is 4, and the description provides adequate context for the tool's function.

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 purpose: to answer whether agents can buy tickets autonomously and which purchase modes providers support. It uses specific verbs ('use this when...') and distinguishes from sibling tools like purchase_ticket_order.

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 says when to use the tool ('when a user asks...'), providing clear context. It does not mention exclusions or alternatives, but the context is sufficient given the tool's specificity.

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 safety and idempotency are covered. The description adds behavioral context about the output format (primary + fallback options), which is useful 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?

The description is a single concise sentence that is front-loaded with the usage context. Every word is necessary, no fluff, and it communicates the core function efficiently.

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 complexity (22 parameters, output schema present) and moderate schema coverage, the description provides the high-level purpose but lacks details on how the plan is generated, fallback selection, or edge cases. It is adequate but not comprehensive.

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% (11 of 22 parameters have descriptions). The description does not address parameter semantics, relying on the schema. Since coverage is not low (<50%), a baseline of 3 is appropriate; the description adds no extra parameter 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 clearly states the tool's purpose: creating a compact night-out plan with a primary live event and fallback options. It uses a specific verb (plan) and resource (night), and implicitly distinguishes from sibling tools like recommend_events or search_events by focusing on a curated plan structure.

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 says 'Use this when a user wants a compact night-out plan,' providing clear context for when to invoke it. However, it does not mention when not to use it or explicitly compare to alternatives, leaving some ambiguity.

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 destructiveHint=true. The description adds that the tool may either execute a purchase (destructive) or return an external handoff (non-destructive). This clarifies the behavioral ambiguity between the two modes. It does not detail idempotency or retry behavior, but the annotations already show idempotentHint=false.

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 concise sentences with no filler. The first sentence clearly states the trigger condition and the two execution modes. Every word is necessary, and it is front-loaded with the key usage condition.

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 moderate complexity (two modes, external handoff). The description covers the core behavioral decision (integrated vs external). It does not discuss prerequisites (e.g., needing a locked quote token) because the schema already requires quote_token. Since an output schema exists, return values are not required in the description. A minor gap: it does not state what happens if the integrated provider fails.

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?

All parameters are described in the input schema with 100% coverage. The description does not add new meaning beyond the schema, but it reinforces the context (explicit written confirmation). Baseline is 3 due to full schema coverage; no additional semantic value is provided here.

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 specifies the verb (purchase) and the resource (locked ticket quote), and distinguishes between two execution paths (integrated provider purchase vs external checkout handoff). This clearly separates it from siblings like quote_ticket_order or get_ticket_offers.

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 (user gave explicit written confirmation for a locked quote) and the two possible outcomes. It does not explicitly state when not to use it, but the condition is clear enough. A slight improvement would be mentioning alternatives like re-quoting.

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, so the description bears less burden. The description adds that it provides a 'locked' quote, implying a reservation hold, but does not contradict the read-only annotation. It provides minimal behavioral context beyond what annotations convey, enough for a neutral score.

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 (25 words) that front-loads the core purpose and key constraints. Every word contributes meaning with no redundancy 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?

For a tool with 7 parameters, output schema present, and good annotations, the description covers the core action (quote), trigger (user chose event), and key terms (locked, stop conditions). It omits detailed return info, but the output schema can cover that. A small gap is the lack of explanation for 'locked' behavior, but overall it is adequately 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 coverage is high (86%), so the description's mention of quantity, max price, ticket type, and stop conditions adds limited new meaning. It does not explain parameter syntax or formats beyond the schema, meeting the baseline but not excelling.

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: 'locked ticket quote with quantity, max price, ticket type, and stop conditions before any purchase attempt.' It uses a specific verb ('quote') and resource ('ticket order'), and implies a distinct step from the sibling 'purchase_ticket_order' by noting 'before any purchase attempt.'

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 user has chosen an event and wants a locked ticket quote ... before any purchase attempt.' It does not explicitly list when not to use or name alternatives, but the context strongly differentiates it from purchase tools. More explicit exclusions would raise the score.

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 read-only, non-destructive, idempotent behavior. The description adds that suggestions are ranked and use live inventory, which is useful context but doesn't disclose rate limits or caching. No contradictions.

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 of about 20 words. It is concise but could be slightly more efficient by removing redundant terms like 'live Dizko inventory'.

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 complexity (20 parameters) and the presence of an output schema, the description is too brief to fully cover usage. It lacks integration of how parameters like genres or venue affect ranking.

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 only 45%, and the description does not add meaning beyond mentioning 'taste, vibe, price, and avoid signals'. Many parameters like genres, venue, and event_types are not explained in the description, leaving gaps.

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 provides ranked event suggestions based on taste, vibe, price, and avoid signals, using specific verb 'recommend' and resource 'events from live Dizko inventory', distinguishing it from siblings like search_events.

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 says when to use the tool ('when a user wants ranked event suggestions'), but does not mention alternatives or when not to use it, leaving some ambiguity.

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, fully covering behavioral safety. Description adds no additional behavioral context (e.g., no mention of rate limits or data freshness).

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?

Single sentence, no fluff, directly states purpose and usage context. Highly concise and 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?

Given 20 parameters and low schema coverage, the description is incomplete. It does not explain key parameters or the return value (output schema exists but not referenced). An agent would lack enough detail to use effectively without guessing.

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 only 5% (only profile_secret described). With 20 parameters, the description does not compensate—it only hints at 'when' parameter. Most parameters like city, free, vibe, avoid are unexplained, making selection and invocation ambiguous.

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 states the tool provides personalized event recommendations based on a user's Dizko preference profile, specifying time frames like tonight, this week, this weekend. This differentiates it from sibling tools like recommend_events (likely non-personalized) and get_event (single event).

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?

Description explicitly states when to use (user has profile and wants personalized recs), but does not mention when not to use or compare to alternatives like recommend_events. The context is clear but lacks exclusionary 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 indicate non-readonly (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the behavioral consequence ('recommendations learn from feedback') but does not clarify idempotency or conflict handling (e.g., overwriting previous feedback). Some value added but limited.

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 sentence that clearly conveys the action and purpose without extraneous details. It is well front-loaded but could benefit from a brief structured breakdown of parameters.

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 adequately covers the use case and outcome. It mentions the authentication requirement (profile_secret) indirectly through schema, but doesn't repeat it. For a simple feedback recording tool, it is sufficiently 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 low (29%), with only 'attended_at' and 'profile_secret' described. The description mentions 'liked or disliked', 'rating', and 'notes' but does not provide format constraints or clarify the 'anyOf' requirement. It partially compensates but insufficiently for the low coverage.

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 ('record'), resource ('event feedback'), and purpose ('so future recommendations can learn'). It distinguishes from siblings like 'get_event_feedback_prompt' which prompts for feedback, while this tool records it.

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 specifies when to use ('when a user says whether they liked or disliked...') and implies the context of recording feedback. It doesn't explicitly exclude alternatives but the context is sufficient for an agent to choose this over related tools like 'save_event_preferences'.

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 this is a write operation (readOnlyHint false). The description adds the consent requirement and mentions merge/replace behaviors, but does not detail side effects, return value, or error conditions 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?

Single, clear sentence with no wasted words. It front-loads the key condition (consenting user with profile) and actions (add, update, merge, replace).

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?

Despite the complex nested preferences schema, the tool description provides the essential context (profile requirement, consent, operation types). The output schema exists, so return value explanation is not needed. Missing minor guidance on partial updates or mode behavior, but schema fills the 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 descriptions cover 60% of parameters (consent, profile_id, profile_secret, plus nested day_filters). The tool description adds no further parameter semantics; it relies on the schema for details like mode enum or preferences structure. Baseline 3 is appropriate given coverage.

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 saves event preferences for a consenting user with an existing Dizko profile, using verbs like add, update, merge, or replace. It distinguishes from sibling tools like create_event_preference_profile by requiring an existing profile.

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 says to use when the user already has a profile and has consented, which sets a clear precondition. It implies alternatives (e.g., create profile) but does not name sibling tools or when not to use beyond the consent/profile requirement.

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 read-only, idempotent, non-destructive behavior. The description adds that it retrieves 'current events' from 'live inventory', reinforcing the temporal nature. No contradictions 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?

Single sentence that front-loads the usage condition and lists key filters. Efficient and to the point, but could benefit from structuring filter types more explicitly.

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?

Tool has 20 parameters and output schema. Description covers when to use and high-level filters but omits details like pagination, ranking order, or result behavior. Output schema covers return values, but the description should provide more operational context for a complex 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 45%, incomplete. Description lists general filter categories (city, date, genre, vibe, venue, artist, neighborhood, price) but does not cover all 20 parameters or add value beyond schema descriptions for those already documented. Some parameters like free, pride, offset, etc. are not mentioned in description.

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

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

The description clearly states the tool searches for current events from live Dizko inventory with various filters. It distinguishes from siblings like get_event and recommend_events, but does not explicitly differentiate from all related tools (e.g., get_artist_events).

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 says 'Use this when a user wants current events from live Dizko inventory using filters...', providing clear usage context. However, it lacks guidance on when not to use it or alternative tools for specific cases.

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