events

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

Annotations already declare write (readOnlyHint=false), non-destructive, idempotent, and closed-world behavior. The description adds the confirmation precondition, but does not explain what happens on re-add, what the idempotency_key guards, or whether the plan is per-user persistent state beyond the name.

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?

It is one sentence, so it is short, but the sentence is awkwardly nested with two conditionals ('when a user confirms' and 'only after explicit confirmation'), front-loading redundancy rather than the action.

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 3-required-parameter mutation tool with no output schema and no parameter descriptions, the description leaves too much unstated. It should at least define event_id's role and how idempotency_key is used for retry safety.

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 0%, so the description must compensate and it does not: event_id, confirmed, and idempotency_key are never mentioned. Constraints like the 16-char minimum on idempotency_key and the meaning of 'confirmed' versus the caller's assertion are left undocumented.

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

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

The description states a specific action (add one Dizko event to the connected user's persistent plan), which is clearer than the bare tool name. However, it is buried in a conditional clause and 'persistent plan' is vaguely defined relative to siblings like save_event or plan_night.

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

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

It implies usage requires explicit user confirmation, but does not contrast with save_event or plan_night, which appear to be overlapping siblings. The agent cannot tell from this text alone which tool to pick when a user wants to save an event.

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 destructiveHint=true, idempotentHint=true and readOnly=false, so the safety profile is largely covered. The description does add genuine non-annotation context (the side effect on the Dizko taste model, plus the user-confirmation prerequisite), but it never says what 'hides' concretely means, whether it is reversible, or how to undo it.

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

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

Two short sentences with zero filler; the restrictive usage gate is front-loaded before the behavioral explanation, which is the correct priority for a conditional mutation.

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?

This is a destructive, non-read-only tool with three required parameters, one of which (idempotency_key) is a 16-128 character client-supplied token that is never explained, and no output schema exists. The description omits permanence/reversibility, failure behavior, and retry semantics, leaving real gaps for an agent to guess at.

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 0% for all three required parameters, and the description never mentions event_id, confirmed, or idempotency_key. The phrase 'user confirms' faintly gestures at the confirmed boolean, but nothing explains the idempotency key's role or the accepted identifier format, so the description fails to compensate for the coverage gap.

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

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

The description names a concrete action and two effects: it 'hides the event' and 'teaches their Dizko taste model.' That is enough for an agent to tell it apart from save_event or record_event_feedback, though the word 'bin' itself is never reconciled with 'hide' in the description text.

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?

'Use this only when the user confirms an event is not for them' supplies an explicit gating condition and implies the negative case (do not call without confirmation). It stops short of naming a sibling alternative, e.g. whether softer negative signals should go to record_event_feedback instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds real value beyond that by disclosing what the generated artifact contains (local time, venue address, lineup, set times, links), which is exactly the kind of behavior the annotations cannot express.

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

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

Two dense sentences, both front-loaded: the usage trigger first, then the artifact description and alternative. No filler, no repetition of the title.

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?

There is no output schema, so the description carries the burden of explaining the return, yet it never says how the .ics is delivered (file contents, URL, attachment). Combined with the undocumented required event_id, the definition is workable for routing but incomplete 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 0%: neither event_id (required) nor status (enum CONFIRMED/TENTATIVE) is documented in the schema, and the description never mentions either parameter. The description therefore fails to compensate for the coverage gap, leaving the agent to guess what event_id should contain and what status controls.

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

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

The description names a specific verb and artifact: it "Builds an importable .ics entry" for one event, scoped to Apple Calendar, Google Calendar or Outlook. It also contrasts itself with the alternative path (the per-event calendar_url), so an agent can place it precisely relative to other event 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?

"Use this when the user wants one event ... as a file" gives a clear trigger condition, and the closing clause names the one-click alternative. It implies (via "one event") but never states the when-not case for bulk/whole-calendar exports, so it stops short of explicit exclusions.

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 say this is a non-idempotent write with no destructive effect; the description goes well beyond that by disclosing the returned values (profile_id and a one-time profile_secret that must be kept for later personalized calls), the privacy property, and the consent precondition. The 'one-time' secret also warns the agent that repeat calls are not interchangeable, which the non-idempotent hint alone does not convey.

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 sentences, no filler, with the consent precondition front-loaded before the mechanics and the prerequisite call. Every sentence carries distinct information.

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?

There is no output schema, so the description usefully names the return values and the onboarding prerequisite. It does not state what happens if consent is false or if the one-time secret is lost, minor omissions for an otherwise well-specified mutation 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 100% and the nested preferences object is fully documented, so the schema carries the parameter burden. The description only reinforces the consent gate and gestures at 'initial taste', adding little syntax or meaning beyond what the schema already states; baseline 3 applies.

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

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

States a specific verb and resource ('Creates a private preference profile') and immediately distinguishes it from sibling writes like save_event_preferences by describing the artifact it produces (profile_id plus a one-time profile_secret). An agent can tell what this tool creates without opening the schema.

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

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

Gives an explicit precondition ('only when the user has explicitly agreed'), an ordering rule ('Ask the onboarding questions (get_preference_onboarding) first'), and a hard gate ('consent must be true'), naming the sibling to call beforehand. This is a textbook when-to-use instruction.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds the confirmation requirement, the exact data destroyed (preferences and feedback history), and the Dizko-only scope. It stops short of stating irreversibility or what happens to the profile record itself, so it is good but not exhaustive.

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 short sentences with the precondition and the confirmation requirement front-loaded, followed by scope. No filler, though the imperative and the 'must be true' clause overlap slightly with the schema's own 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?

For a destructive, non-idempotent-looking mutation with no output schema, the description covers the essentials an agent needs before calling: user confirmation, what gets removed, and scope. The main remaining gaps are the semantics of profile_secret and whether the deletion is reversible.

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 33% (confirm_delete is the sole documented parameter), so the description carries extra burden. It does reinforce the confirm_delete=true gate, but profile_id and profile_secret are left without any description-level meaning, so it only partly compensates for the gap.

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?

Uses a specific verb (deletes) plus the exact resource (a profile's saved preferences and feedback history), which clearly separates it from the sibling read/write pair get_event_preferences and save_event_preferences. The scope qualifier ('Scoped to Dizko only') further pins down what this tool touches.

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

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

It gives an explicit gating condition: use it only when the user confirms they want their Dizko data deleted. That is real when-to-use guidance, though it never names the alternative tools (e.g., save_event_preferences for modification) that an agent might confuse it with.

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, openWorldHint=false, and destructiveHint=false, so the safety and world-scope profile is fully covered. The description adds no behavioral context of its own — no return shape, no result limits, no indication of how id vs query resolution behaves.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is part of the under-specification problem rather than a virtue achieved through careful editing.

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 an 8-parameter search tool with 0% schema description coverage, no output schema, and only safety-oriented annotations, the description is far too thin. An agent cannot tell how the id/query alternation works, what the filters do, or how results are bounded.

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 0% across 8 parameters, so the description must compensate and does not. It loosely maps to the 'kind' enum by naming entity types, but says nothing about id vs query (the anyOf disjunction), city/genre/date filters, or the limit cap of 20.

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

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

The description names the entity kinds (DJ, venue, collective, promoter) and implies a lookup via the user-intent phrasing, but never states what the tool actually returns or does beyond the tool name. It also fails to distinguish itself from sibling tools get_artist and get_venue, which appear to cover overlapping entity lookups.

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

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

It gives a when-to-use trigger ('when a user asks who a DJ is or about a venue...'), which is real guidance. However, there are no when-not conditions and no mention of alternatives, despite get_artist and get_venue existing as obvious overlapping siblings — the agent gets no help choosing between them.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description usefully adds what content is returned and that catalog enumeration is out of scope, but says nothing about pagination, the limit cap, or how date ranges affect the returned events.

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

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

Two sentences, zero filler, and the use-condition and scope caveat are front-loaded ahead of the argument syntax. Nothing is redundant or buried.

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 six parameters split across two invocation modes, no output schema, and a 'limit' that caps at 20, the description leaves the filter behavior (city, date_from, date_to, limit) unexplained. Annotations cover safety, but an agent still lacks enough to know how the optional filters shape the response.

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 33%: id and query are documented, while city, limit, date_from, and date_to are documented nowhere. The description repeats the id/query duality already encoded by the schema's anyOf but adds no meaning for the four undocumented filters, which are exactly the parameters tied to its advertised 'upcoming events' payload.

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

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

The description names a specific verb+resource and enumerates the payload (profile, graph context, published links, upcoming events), which is more than a restatement of the name. However, it never distinguishes itself from near-identical siblings like get_artist_page and get_artist_events, and 'upcoming events' actively overlaps with the latter, so an agent may struggle to route between them.

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

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

It opens with an explicit when-to-use condition ('Use this when a user wants...') and adds invocation guidance ('Pass an id or a name query') plus a negative scope statement ('does not enumerate the artist catalog'). It stops short of naming any alternative sibling for the overlapping lookups, so it is clear context without full exclusion routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context: results are grouped by artist, deduplicated across sources, date-ordered, and the profile_id path silently falls back to the saved featuring list. It omits anything about profile_secret auth or result-size/limit behavior.

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 sentences, no filler, with the triggering user question front-loaded before the return-shape and profile-fallback details. Every clause carries distinct information.

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

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

With no output schema, the description usefully describes the return shape (grouped, deduplicated, date-ordered). Gaps remain on the `fields` selector and `limit_per_artist` default/cap, but the 8-parameter surface is otherwise well covered.

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 63%, so the schema documents city, artists (max 8), date_from/date_to and the profile fallback; the description reinforces the 8-name cap and city scoping. It says nothing about `fields` (which controls returned payload sections) or `limit_per_artist`, leaving two output-shaping parameters undocumented in both places, so no credit above the baseline.

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

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

States a specific retrieval verb and resource ('Returns upcoming shows grouped by artist'), plus the trigger intent (when a DJ, performer or comedian plays next). The artist-centric scope plus grouping, dedup and date-ordering clearly separates it from the generic search_events/get_event 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?

Gives explicit user-intent triggers for invoking it, including the city-this-month case, and explains the profile-without-artists branch. It does not name competing siblings or state when NOT to use it, 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 declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond them by disclosing what comes back (page embeds with stable block ids suitable for deep links), which matters because there is no output schema.

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

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

Two tight sentences: the trigger condition is front-loaded and the return behavior follows. No filler, no repetition of the title or annotations.

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 one-parameter read-only tool with annotations covering the safety profile and no output schema, the description covers purpose and return shape adequately. The unresolved meaning of `handle` (artist vs. mix) is the main completeness gap an agent would hit before calling 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?

Schema description coverage is 0% and the single parameter `handle` is never explained in the description. Worse, the description's phrasing (artist page vs. a specific mix or set) creates ambiguity about whether handle identifies an artist or a mix, so it does not compensate for the schema gap.

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

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

The description names a specific resource (an artist's Dizko page, a published mix/set) and implies a read of page embeds, so the agent can tell what it returns. It does not explicitly distinguish itself from the sibling get_artist tool, which is the most likely confusion point, so it falls short of a 5.

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

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

"Use this when a user wants an artist's Dizko page or a specific published mix or set" gives a trigger condition, but it restates the purpose rather than offering when-not-to-use guidance or naming alternatives such as get_artist. The mention of a "specific published mix or set" is also not reconcilable with the single required handle parameter, leaving usage partly implied.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real context beyond that: results are aggregate, stats carry evidence counts, city-local dates are used, and scope is public inventory only.

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 sentences, front-loaded with the usage trigger before the return summary. The output enumeration is dense but each item is informative; nothing is redundant.

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

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

For a read-only aggregate tool with full schema coverage and no output schema, the description supplies the missing return-shape detail (the stats it returns and that they include evidence counts) plus scope and date semantics. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents city, days, date_from, and event_types with defaults and bounds. The description only loosely implies the days window ("coming days") without adding syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: an aggregate read over a city's coming days. It names concrete outputs (busiest nights, top venues, genre mix, headline events, free-event count) that clearly separate it from siblings like get_daily_roundup and 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?

Gives explicit trigger phrases ("what's hot," "how busy a city is this week," "scene trends") and a scope constraint ("Public inventory only"). It does not name an alternative or exclusion (e.g., when to prefer get_daily_roundup), so it stops short of full when/when-not guidance.

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

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

Annotations already declare the safe read-only/idempotent profile, so the description is free to add ranking behavior: picks are ordered by saved, learned and per-weekday taste when a profile is present, and compact=true yields a short push-style digest. It doesn't describe return volume or section behavior beyond compact, so it isn't exhaustive.

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 sentences, front-loaded with the trigger condition, then output shape, then personalization and the compact flag. No filler; every clause carries information.

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 17-param tool with no output schema, the description usefully sketches the return shape (top picks plus themed sections) and the personalization/compact modes. It leaves many filter parameters and their interactions unexplained, so it is strong but not fully complete.

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

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

With 17 params at 59% schema coverage, the description only illuminates two of them – compact and the profile-based personalization. Filter params like free, price_max, top_limit, section_limit, neighborhoods and fields get no explanation in either place, so the coverage gap is only partly compensated.

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

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

States a specific verb and resource – returns a one-day digest for a city with named sections (parties, live music, art, etc.). It does not explicitly differentiate itself from near siblings like get_city_pulse or search_events, so it stops short of a 5.

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

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

Opens with an explicit trigger: 'Use this when a user asks what's happening today or tomorrow, or for a morning briefing or scheduled check-in.' That gives clear when-to-use context, but no when-not or named alternative (e.g. use search_events for ranges).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by warning that search results are usually sufficient — discouraging redundant calls — and by enumerating the fields returned, which matters because there is no output schema. It stops short of auth or rate-limit 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?

Front-loads the usage condition in the first clause, then details the return payload in a second sentence. Efficient overall, though the trailing field enumeration reads as a long list rather than structured prose — justified only because no output schema exists.

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

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

With no output schema, the description fully compensates by enumerating the returned detail; with annotations covering safety, and a single well-documented parameter, an agent has everything needed to call this correctly.

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

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

Only one parameter and schema coverage is 100%, with the schema itself explaining it is a UUID from any Dizko result. The description's mention of 'an event id' adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns full detail for one event') and enumerates the payload (times, venue, price, lineup, set times, socials, image, coordinates, links). It also distinguishes itself from the search tools by noting search results already contain what the template needs.

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 scopes invocation: 'only when the user gives an event id, or wants extra detail on an event not in the current results.' That is both a when-to-use and a when-not-to-use rule, with the alternative (search results) named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeatability are covered structurally. The description adds nothing beyond that: it does not say whether the prompt is static or personalized by attended_at, nor whether a missing event_id fails or degrades gracefully.

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?

A single sentence with no filler or redundancy. It is front-loaded with a usage trigger, though leading with what the tool returns rather than 'Use this when...' would be marginally stronger. Nothing in the sentence is wasted.

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

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

For a two-parameter read tool with no output schema, the description should at least indicate what the returned prompt looks like and how the required event_id and optional attended_at influence it. Neither is addressed, so an agent knows roughly when to call it but not what to expect back or how the parameters shape the result.

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 50%: attended_at is documented in the schema, but required event_id is undocumented in both the schema and the description. The description compensates for none of this gap and never references either parameter, leaving the required identifier's expected format and role unspecified.

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 an action phrase ('Use this when a user needs...') and names the resource ('post-event feedback prompt'), so the general purpose is inferable. However, it never states what is actually returned — a templated prompt string, a set of questions, or a personalized message — and it does not distinguish itself from siblings like record_event_feedback or get_event_preferences. Adequate but vague on the actual output.

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

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

It gives one conditional trigger ('when a user needs a short post-event feedback prompt'), which is a real usage context. It offers no when-not conditions, no prerequisites (e.g. the event must exist), and never routes to an alternative such as record_event_feedback, which is the natural counterpart for capturing the feedback this prompt solicits.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the shape of what comes back (saved preferences, learned taste with scores, feedback count), which matters because no output schema exists.

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

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

Two sentences, zero waste, with the usage trigger front-loaded before the return summary. Nothing is padded or repeated from the name.

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

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

For a two-parameter read tool with full schema coverage and annotations, the description covers purpose, trigger, and return contents adequately. Minor gap: no mention that profile_secret must be kept private or what happens on an invalid/expired profile.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including where profile_id and profile_secret originate. The description adds no syntax, format, or sensitivity guidance, so the 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?

States a specific verb and resource: returns a profile's saved preferences, learned taste scores, and feedback count. However, it never distinguishes itself from sibling tools like get_taste_profile or get_preference_onboarding, which plausibly overlap, so an agent cannot route between them from the description alone.

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

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

"Use this when the user asks what Dizko remembers about them" gives a clear, actionable trigger condition. It stops short of exclusions or naming alternatives (e.g., get_taste_profile) for the cases where this tool is not the right choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered without the description. The description adds nothing about return shape, whether the 13 input params are echoed back as a refined query, or what the followups look like — a real gap for a tool whose entire purpose is ambiguous.

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?

It is short, but it is under-specified rather than concise — the single clause carries no actionable content. Brevity here reflects a lack of information, not efficiency.

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?

A 13-parameter tool with no output schema, no enum guidance, no required fields, and zero schema descriptions needs the description to explain inputs and expected output. It provides neither, leaving the agent unable to call the tool meaningfully.

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 0% across 13 parameters, and the description mentions none of them (city, vibe, when, avoid, genres, price fields, etc.). The description does not compensate at all for the complete absence of parameter documentation.

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?

"Use this when an event search needs follow-up questions" essentially restates the tool name without stating what the tool actually returns or does — does it fetch pre-computed follow-up questions, generate them, or accept search criteria and return suggestions? With 29 sibling tools including search_events and recommend_events, an agent has no basis to pick this one.

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

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

It gestures at a trigger condition (an event search needing follow-up questions) but names no alternatives, no prerequisites, and no relationship to search_events or recommend_events. An agent cannot tell whether this precedes or follows a search call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — no indication of what is returned, whether it is a static questionnaire, or any auth/consent prerequisites, despite 'consent-first' being the tool's distinguishing trait.

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?

A single front-loaded sentence with no padding, and the usage trigger comes first. It is efficient, though the phrasing 'wants consent-first questions' is slightly awkward and could have spent the same words stating what the tool actually returns.

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

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

With no output schema and a read-only, optional-parameter design, the description should at minimum say what comes back (the onboarding questions) and whether they depend on profile_id. It gestures at the scenario but leaves the return contract implicit, which is a meaningful gap for a 'get' 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 100% and profile_id is already documented as 'Stable user/profile id if already known', so the schema carries parameter meaning. The description adds nothing about how profile_id affects the onboarding output (e.g. personalized vs generic questions), so baseline 3 applies.

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

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

The description implies the tool surfaces consent-first onboarding questions tied to event preferences, but it never states plainly that it returns onboarding questions or what that payload is. The verb+resource from the name ('get preference onboarding') is never restated in operational terms, and sibling routing (e.g. vs get_event_preferences, save_event_preferences) is only hinted at via 'before saving 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?

'Use this when a user wants consent-first questions before saving event preferences' gives a trigger scenario, which is real usage guidance. However it names no alternative tool and gives no exclusion conditions, so an agent still has to guess how this differs from get_event_preferences or create_event_preference_profile.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about what data is read (learned taste, saved/binned events) and implies a precondition ('connected user'), which goes beyond the annotations and is valuable for correct invocation.

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 usage condition ('when personalizing for a connected user') and then states the action. Every word earns its place; there is no redundancy or 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?

For a tool with no parameters and no output schema, the description explains what data is returned (learned taste, saved/binned events) and when to use it. It lacks details on output format or error conditions, but given the low complexity, it is sufficiently complete for an agent to 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?

The tool has zero parameters, so the schema coverage is 100% by definition. The baseline for 0 parameters is 4, and the description adds no parameter information (none needed). It does not detract from the score.

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

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

The description clearly states the tool's function: reading a connected user's learned Dizko taste plus saved and binned events. The verb 'read' and resource 'taste profile' are specific, and it distinguishes itself from siblings like get_event_preferences by focusing on the taste profile and saved/binned 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 gives a clear usage context: 'when personalizing for a connected user.' It indicates when to use the tool but does not explicitly mention alternatives or exclusions. However, the context is specific enough to guide an agent without needing to compare with 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding real behavior: it does not buy tickets and next_step is hand_off_to_checkout. That is essential context an agent cannot infer from annotations, though auth or rate-limit details are absent.

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 sentences, front-loaded with the trigger condition, and the returns list is compact. The enumeration of return fields is slightly dense but each item is informative and none is filler.

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

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

With no output schema, the description usefully enumerates the return fields and flags the key behavioral outcome (no autonomous purchase, handoff to checkout), which is what an agent needs to plan the next call. Permission or error behavior is the only notable 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 single event_id parameter is fully documented in the schema (100% coverage), and the description only implies 'one event' without adding format, source, or validity guidance. Baseline 3 is appropriate when the schema carries the parameter detail.

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

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

States a specific verb and resource ('tickets for one event') and names the exact return payload, which distinguishes it from quote_ticket_order and purchase_ticket_order by placing it 'before quoting.' An agent can select it without opening the schema.

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

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

'Use this when the user wants tickets for one event, before quoting' gives a clear trigger and an implied ordering relative to the quoting/purchase siblings. It does not explicitly name those siblings or state exclusions, so it falls short of a full when/when-not rubric.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the bar is lower. The description earns credit by disclosing the actual content of the policy being retrieved — the quote/confirmation/checkout sequence and the provider-integration exception — which is behaviorally relevant context not present in any structured field.

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?

A single sentence, front-loaded with the usage condition and then the payload summary. No filler, no restatement of the title.

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

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

With no parameters, no output schema, and annotations covering safety, the only open question is what the policy actually says — and the description answers that at a summary level. It doesn't state the response format (plain text vs. structured policy), a minor gap for such a simple read-only 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?

The tool takes zero parameters, so the schema has nothing to explain and the baseline is 4. The description correctly avoids inventing parameter talk and instead spends its words on what the caller receives.

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 resource (the ticket purchase policy for Dizko agents) and summarizes what that policy covers: signed quote, written confirmation, checkout handoff, provider integration. It is clearly distinguishable from action siblings like quote_ticket_order and purchase_ticket_order, though the verb is implied by 'Use this when...' rather than stated outright.

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

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

It gives an explicit trigger condition: 'Use this when a user asks how Dizko agents can buy tickets.' That routes the agent correctly away from the transactional siblings, but no when-not condition or direct sibling reference is provided for the cases where the user actually wants to buy rather than understand the process.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description usefully adds what the caller receives (profile, graph context, upcoming events). However it says nothing about limit/pagination behavior or what happens with an ambiguous name query, so it is only adequate.

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

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

Two tight sentences, front-loaded with the trigger condition and followed by the input requirement and scope boundary. Nothing is wasted.

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

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

With no output schema, the description correctly covers the return contents, but the four undocumented parameters (limit, dates, city) leave real gaps for a 6-parameter lookup tool. Adequate but not thorough.

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 33%, so the description must compensate. It does explain the critical id-or-query disjunction, but leaves city, limit, date_from, and date_to entirely unaddressed in both schema and 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?

States a specific verb and resource ('canonical venue profile, graph context, and upcoming events') plus a scope boundary ('does not enumerate the venue catalog'). It is distinguishable from catalog-listing siblings like find_scene_entities, though it never names a specific alternative.

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

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

Gives a clear triggering condition ('when a user wants a canonical venue profile, graph context, and upcoming events') and an explicit exclusion ('does not enumerate the venue catalog'). No sibling is named as the alternative, so it falls short of a full 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 declare this a safe, idempotent, closed-world read, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the meaning of the status values and the caveat that 'unlocking and early cities are searchable but thin,' which tells the agent how to interpret thin results.

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

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

Three tight sentences with no filler, front-loaded with the usage trigger and immediately followed by the return shape. Every sentence carries distinct information.

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

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

With no output schema and no parameters, the description carries the burden of describing the return payload, and it does: status enum values, event count, timezone, freshness, plus the data-thinness caveat. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax for the description to clarify or omit.

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

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

States a specific verb+resource and scope: 'Returns every city with status (live, unlocking, early), event count, timezone and freshness.' The scope word 'every' plus the coverage framing clearly separates it from per-city siblings like get_city_pulse.

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

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

Gives explicit triggering conditions ('when a user asks where Dizko works, whether a city is covered, or how fresh the data is'), which is strong when-to-use guidance. It stops short of naming alternatives or stating when not to use it, 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 declare readOnly, idempotent, non-destructive, so safety is covered. The description adds real behavioral context beyond that: the composed output (primary, 6 km nearby fallback, later-starting fallback, alternates) and the empty-plan no_results behavior. It stops short of describing ordering or ranking beyond taste fit.

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

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

Four tight sentences, front-loaded with the usage condition, then return shape, then parameter parity, then the empty case. No filler and no repetition of schema details.

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

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

With 22 parameters and no output schema, the description fills the important gaps: it sketches the return structure and the empty-result path, and points to search_events for filter semantics. It is close to sufficient, though it leaves result_limit semantics and some filter specifics to the schema.

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

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

Schema coverage is 59%, close to the baseline where the schema carries most weight. The description adds useful framing by saying filters match search_events and that profile_secret/profile_id are a paired optional profile, but it does not explain result_limit's role as plan size or any field not already documented in the schema.

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

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

The description states a specific verb+resource ('night plan with backups') and explicitly contrasts it with the sibling pattern of a flat list, and it names search_events as the tool whose filters it shares. An agent can distinguish this from search_events or recommend_events without opening the schema.

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

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

It gives a clear triggering condition ('when the user wants a night plan with backups rather than a list') and implies search_events as the alternative for plain lists. It never states an explicit when-not, but the framing is strong enough to route correctly.

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

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

Excellent disclosure beyond annotations: it names the requires_external_checkout status and checkout_url handoff, the terminal 'purchased' status the agent must wait for before claiming success, and the single-use nature of quote_token producing quote_already_used with no retry. This is exactly the non-idempotent, destructive, open-world behavior the annotations hint at, made concrete.

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

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

Four tight sentences that each carry load, front-loaded with the gating condition. Dense but not padded; a minor readability cost from packing the status contract into the first paragraph.

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 destructive, non-idempotent purchase tool with no output schema, the description supplies the status contract, the retry prohibition, and the confirmation requirement — the critical missing structured data. Leftover gap is the undocumented delivery_email and add_to_calendar parameters.

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

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

Schema coverage is 60%, and the description compensates by explaining that confirmation_text must contain buy/purchase plus quantity and max total, and that quote_token comes unchanged from quote_ticket_order. The two undescribed params (delivery_email, add_to_calendar) get no help here, but the semantically risky ones are covered.

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?

Specific verb+resource ('purchase ticket order') with clear scope: it consumes a signed quote_token, not raw selection. It distinguishes itself from quote_ticket_order, which it explicitly references as the source of the token, so an agent can tell the two apart without opening schemas.

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

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

It states the exact precondition for calling ('only when the user has confirmed a quote in writing', with the required wording) and the behavioral fork when no integrated provider exists. It does not explicitly say 'call quote_ticket_order first to get a token', but that step is strongly implied by the parameter origin.

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

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

Beyond the annotations (readOnly, non-destructive, non-idempotent), the description discloses that the quote is signed and time-limited, that it returns a quote_token to forward unchanged, that it returns exact confirmation text, and that without an integrated provider it only prepares a checkout hand-off. These are exactly the behavioral traits an agent needs and they are consistent with 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?

Two sentences, front-loaded with the trigger condition before the behavior and return semantics. The parenthetical field list is somewhat dense but every clause carries information an agent needs.

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?

No output schema exists, so the description correctly carries the return-value burden by naming quote_token and the confirmation text. It covers the degraded no-provider mode and the purchase hand-off, leaving only minor gaps around the undocumented boolean/event_id parameters.

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

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

Schema description coverage is 67% and the description mainly restates parameter names (quantity, ticket type, max total, currency, refund terms, delivery email) without adding format or constraint meaning. 'stop conditions' is mentioned but not mapped to a parameter, and event_id/offer_id/add_to_calendar are not clarified further.

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

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

States a specific verb and resource ('Creates a signed, time-limited quote') and enumerates the quote contents. It clearly positions itself relative to siblings by naming purchase_ticket_order as the downstream consumer and get_ticket_offers as the upstream source of offer_id.

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 trigger condition ('Use this when the user has chosen a ticket offer, quantity and constraints') and an explicit next step ('pass unchanged to purchase_ticket_order'). It does not spell out when NOT to use it or what to do if no offer has been chosen, but the workflow context is unambiguous.

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 establish that this is a safe, idempotent, read-only operation, so the safety bar is covered. The description adds two substantive traits beyond that: every result carries recommendation_reasons (return-shape info useful in the absence of an output schema) and the critical behavioral split that some filters are hard and others merely rank.

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 short sentences, no filler, and the trigger condition, output guarantee, and filter semantics are ordered by importance. Every sentence carries information an agent needs before calling.

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 26-parameter, zero-required tool with full schema coverage and no output schema, the description is adequate: it defines the paradigm, promises recommendation_reasons, and clarifies hard-vs-soft filtering. It omits the profile_id/profile_secret pairing and the limit/result_limit precedence, though those are documented in the schema itself.

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 earns a bit more by consolidating which parameters act as hard filters (genres, vibe, event_types, price_max, venue, featuring) versus ranking-only ones (avoid, max_price) across a 26-parameter surface, where that summary is genuinely useful even though individual param descriptions repeat it.

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

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

States a specific verb+resource ('live events ranked by taste, vibe, price, and exclusions') and implies a recommendation-oriented ranking task. It does not, however, name or distinguish itself from the sibling search_events or recommend_events_for_user, so an agent must infer the split from the word 'ranked' alone.

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

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

'Use this when a user wants live events ranked by taste, vibe, price, and exclusions' gives a trigger condition but no explicit when-not and no named alternative. With search_events and recommend_events_for_user both present, the description leaves the agent to guess which ranking tool applies.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description focuses elsewhere and delivers a genuinely useful trait: saved/learned taste only re-ranks results and never removes them. It omits the credential nature of profile_secret and what happens when no profile is supplied, but the ranking-vs-filtering disclosure is real added value.

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 sentences, front-loaded with the trigger condition and followed by the one behavioral caveat. Zero filler; every clause earns its place.

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

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

For a 20-parameter tool with no output schema and near-zero schema coverage, this is far too thin. It says nothing about how the many filter parameters combine, the default/max result limit, or what the tool returns, so an agent cannot call it correctly without opening the full schema.

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

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

With 20 parameters and only 15% schema description coverage, the description must carry the parameter burden and does not. Beyond implicitly referencing the saved profile, it explains none of the rich filter surface (city, vibe, when, genres, price, result_limit), leaving 18 parameters undocumented in prose and schema alike.

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

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

The description states the resource (recommendations) and its distinguishing scope (personalized via a saved Dizko profile), which separates it in spirit from the sibling recommend_events. However, it is phrased as a usage trigger rather than a function statement and never explicitly says it returns events, so an agent must infer the verb+resource from the name.

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?

'Use this when a user wants recommendations personalized with a saved Dizko profile' gives a clear activation condition, and the personalization qualifier implies the unpersonalized recommend_events alternative. It stops short of naming that sibling or any when-not condition, so the routing guidance is implied rather than explicit.

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 declare it is a non-destructive write. The description goes well beyond that, disclosing the actual side effects: a like promotes genres/vibe/venue while a dislike marks venue and promoter and penalizes genres only when notes blame the music. This is exactly the learned-signal behavior an agent needs to reason about consequences.

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 dense sentences, front-loaded with the usage condition before the behavioral detail. Every clause is load-bearing, though the second sentence is heavy enough to be slightly hard to parse on first read.

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 mutation tool with annotations covering safety and no output schema, the description supplies strong when-to-use and effect information. It omits what a repeat call does (idempotentHint=false implies re-learning) and any return/confirmation behavior, which are minor gaps.

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

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

Schema coverage is only 43%, so the description must carry weight. It explains the semantics of the three feedback fields (liked/rating/notes) via their taste effects, but does nothing for profile_id, profile_secret, event_id, or attended_at, leaving authentication and event-sourcing unexplained.

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

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

States a specific verb (record/stores) and resource (event feedback) and names what is stored (liked, 1-5 rating, notes) plus the downstream effect on learned taste. It is clearly distinguishable from the sibling get_event_feedback_prompt, which only surfaces the questions.

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

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

Opens with an explicit precondition: 'Use this only when the user has answered post-event questions.' It even points to the sibling that supplies those questions, so the agent knows exactly when to invoke it and what must precede it.

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 disclose the write/idempotent/non-destructive profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so safety is covered structurally. The description adds the confirmation precondition, which is genuine behavioral context. It omits, however, any explanation of what the idempotency_key guarantees or what happens on a repeated call.

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?

A single front-loaded sentence with the trigger condition first and no filler. It is terse to the point of under-specification, but not padded.

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

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

For a mutation tool with annotations but no output schema and three undocumented parameters, the description should at least explain the idempotency key and confirm flag semantics. It covers the confirmation requirement, which is the most important behavioral gate, but leaves real gaps.

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

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

Schema description coverage is 0% across three required parameters, so the schema provides only types and lengths. The description touches the confirm concept indirectly via 'explicit confirmation' but never explains event_id, the confirmed flag, or the idempotency_key's purpose or constraints.

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

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

States a specific verb (save) and resource (one Dizko event) and scopes it to the connected user's account. It does not, however, distinguish itself from close siblings like add_to_dizko_plan or save_event_preferences, which an agent could easily confuse with this one.

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

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

It supplies one real usage condition — only after explicit user confirmation — which is useful trigger guidance. But it names no alternatives and gives no when-not guidance, so an agent still has to infer how save_event differs from add_to_dizko_plan or 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 flag destructiveHint=true and non-idempotent, but the description adds genuinely new operational context: profile_secret authentication and a consent=true gate that must be set only after the user agreed. The merge-vs-replace explanation of mode partially duplicates the schema's own enum description, keeping this just short of a 5.

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

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

Three tight sentences: trigger first, semantics second, hard prerequisites last. No filler, and the most decision-relevant information is front-loaded.

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

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

For a destructive write with no output schema, the description supplies the essentials an agent needs: when to call, credentials, the consent requirement, and the effect of each mode. Return behavior is unspecified but there is no output schema to explain, so the omission is minor.

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

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

At only 40% schema coverage the description has to carry weight, and it maps the unlabeled top-level params well: profile_id and profile_secret as credentials, consent as a gate, and mode as merge/replace. It covers representative preference fields (genres, featuring, venues, budget, day_filters) but leaves vibe, avoid, cities, promoters, event_types and neighborhoods to 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?

States a specific verb and resource (save preferences) and enumerates the kinds of taste being saved (genres, featuring artists, venues, budget, day_filters). The phrase 'for an existing profile' implicitly distinguishes it from create_event_preference_profile, but it never names that sibling, so the differentiation is inferred rather than 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?

'Use this when the user shares new taste for an existing profile' gives a clear triggering condition. It does not name the alternative siblings (create_event_preference_profile for new profiles, delete_event_preferences, get_event_preferences), so the agent must infer which tool handles a new profile.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real substance: taste from profile_id ranks but never filters, hard vs soft filters, and a no_results payload with ordered suggested_relaxations that can be retried. That is genuine behavioral context 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?

A single dense paragraph, front-loaded with the usage trigger, then return shape, then filter semantics, then the no-results path. Every sentence carries information that affects an invocation; nothing is filler.

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

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

With 28 parameters and no output schema, the description helpfully characterizes the returned fields, count semantics, and empty-result behavior. It leaves some structured behavior (pagination via next_cursor, fields selection) to the schema, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the crucial distinction that genres/vibe/event_types/price_max/venue/featuring are hard filters while avoid/max_price are ranking hints, and clarifies the profile_id+profile_secret pairing. This meaningfully supplements 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?

States a specific verb and resource (search live events) plus the trigger condition (user asks what's on and names a city, venue, artist, or timeframe), and enumerates the return payload. This is distinct from siblings like recommend_events, get_event, and 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?

Gives a clear when-to-use trigger and explains the hard-filter vs ranking-hint split, which governs how to pick parameters. It does not explicitly name alternative tools (e.g. recommend_events) or state when this tool should not be used, so it stops short of a 5.

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