Dolby Cinema Tracker

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

Annotations already declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real value on top by disclosing eligibility rules and the state-dependent failure modes. The "at its current revision" phrasing hints at optimistic concurrency — a failed retry with a stale revision is implied but not spelled out.

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, zero filler, with the positive scope stated first and the exclusions second. Nothing is redundant with 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?

An output schema covers return values and annotations cover the safety profile, so the description needn't repeat those. However, for a two-required-parameter mutation with no schema descriptions, leaving "id" undefined and the revision-mismatch behavior unstated is a meaningful gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and largely does not. "At its current revision" faintly implies the revision parameter must match current state, but the required "id" parameter is never explained (request id? ticket id?), and no format or failure behavior per parameter is given.

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 resource ("Cancel ... request") and narrows the scope to a "still-queued request" — an agent can tell this apart from operational siblings like request_booking. It stops short of explicitly naming the counterpart tool, so sibling differentiation is implied rather than stated.

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 negative conditions are given: cannot cancel a claimed request, a booked ticket, or a protected ticket. This is strong when-not guidance, but no positive preconditions or alternative route (e.g. what to do instead once a request is claimed) are offered.

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, the description discloses important behavior: creation is gated by alerts:write and a paid plan, email requires explicit human consent, and payment is not treated as delivery consent. It also notes that the website's validation and limits apply. It does not explain duplicate-create or non-idempotent behavior, which keeps it from 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?

The description is front-loaded with the action and its main inputs, followed by authorization and consent constraints. It is compact and mostly free of waste, though "using the website's validation and limits" is somewhat vague and could be sharper.

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

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

The purpose, authorization requirements, plan requirement, and email-consent constraint are covered, and an output schema exists so return values need not be explained. Still, for a 9-parameter tool with 0% schema description coverage, the description leaves meaningful gaps around browser, timezone, and the exact semantics of several fields.

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 9 parameters, so the description must carry parameter meaning. It mentions theatres, formats, triggers, cadence, and email consent, but omits movie, browser, and timezone, and does not explain enum values such as on-sale-near or the default cadence. Partial compensation is present, but substantial gaps remain.

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 and resource: "Create a movie follow." It also lists the main configurable dimensions (theatre IDs, formats, triggers, cadence), making the operation clear. It does not explicitly contrast itself with sibling alert-management tools such as update_alert, list_alerts, or delete_alert, so it falls short of the top score.

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 supplies useful prerequisites: alerts:write, a paid plan, and explicit email consent. However, it gives no explicit guidance on when to choose create_alert versus update_alert, set_reminder, or other sibling tools, and it does not state when this tool should not be used.

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 openWorldHint=true, destructiveHint=false, and readOnlyHint=false, and the description reinforces this by stating 'This tool never cancels or charges', clarifying that any cancellation happens in Stripe's UI rather than through this call. It could add more, such as whether a new session/link is minted each invocation given idempotentHint=false, but the core safety behavior is well disclosed.

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, front-loaded with what is returned, then who consumes it, then the safety guarantee. Every sentence earns its place with no 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?

The tool is simple (no parameters, output schema present), and the description covers what is produced, its intended consumer, and its non-destructive guarantee. Nothing an agent needs in order 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 description carries no parameter burden and the baseline applies. Nothing in the schema requires additional explanation.

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

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

The description uses a specific verb ('Return') with a precise resource ('connected owner's Stripe-hosted portal URL'), so the agent knows exactly what it produces. It does not explicitly name or differentiate itself from siblings like create_checkout_link or get_subscription_status, leaving that distinction to inference.

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 clear usage context: the URL is for a human to view invoices, change payment details, or cancel, which signals when this tool is the right choice (self-serve billing handoff). It names no alternatives or exclusions, so the agent must infer that create_checkout_link is for payments rather than portal management.

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 is a non-read-only, non-idempotent, open-world operation, so the safety baseline is covered. The description adds genuinely new behavioral information beyond that: the tool returns a URL rather than completing anything, a human must open and confirm, and the agent must never claim payment is complete. It omits link expiry and what happens if a subscription is already active, which keeps it below 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 short sentences: purpose first, then the return-handling instruction, then the hard constraint. No sentence is redundant and the most failure-prone instruction (never claim payment complete) is placed last for emphasis.

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?

An output schema exists, so the description needn't document return fields, and it still usefully notes the payload is a Stripe-hosted URL. For a zero-parameter, human-in-the-loop billing tool the coverage is strong; only edge cases (expired or reused links, active-subscription behavior) are unaddressed.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies the subscription context is derived from the connected owner rather than passed in.

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 outcome: it produces a Stripe-hosted URL so the connected owner can subscribe or renew. That is a clear verb+resource pairing an agent can act on. It does not, however, distinguish itself from near siblings such as create_billing_portal_link or start_subscription, so the agent must infer which link to mint.

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?

"Help the connected owner subscribe or renew" implies the triggering situation (new subscription or renewal), which is useful context. But there is no explicit when-not guidance and no naming of alternatives like create_billing_portal_link for managing an existing subscription, leaving the choice between sibling tools to inference.

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

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

The annotations already flag destructiveHint=true and idempotentHint=false, and the description adds information the annotations cannot express: the deletion is permanent, it is restricted to the caller's own alert, it does not cancel the underlying subscription, and it requires a specific scope plus a paid plan. That is exactly the extra context that prevents a costly misinvocation on a mutation tool.

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, none wasted, with the destructive/permanent nature and the ownership restriction front-loaded before the prerequisites. The final sentence packs auth scope and plan gate without repetition.

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

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

With annotations covering the safety profile and an output schema covering return values, the description only needs to supply scope, permanence, side effects, and preconditions — and it does all four. The remaining gap is the meaning and constraints of the lone id parameter, which nothing else documents.

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

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

There is a single parameter with 0% schema description coverage, so the schema supplies only a pattern and length bounds, not meaning. The phrase 'the connected owner's alert' implicitly characterizes the id as an alert identifier owned by the caller, but the description never explicitly maps the parameter to an alert ID or explains the failure behavior for a foreign/unknown ID.

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 pairs a specific verb ('Permanently delete') with a specific resource ('the connected owner's alert'), and adds a scoping qualifier that separates it from administrative deletion or subscription cancellation. It does not name the adjacent siblings (pause_alert, update_alert, list_alerts), so differentiation is implied 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?

It states two concrete prerequisites for calling it — the alerts:write scope and a paid plan — and clarifies that it is not a subscription-cancel operation, which rules out a common misuse. It stops short of telling the agent when to prefer pause_alert or update_alert over deletion.

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 destructive=true and idempotent=false, but the description adds real context beyond them: deletion also expires any still-pending delivery, and it explicitly bounds the blast radius by not touching tickets or follows. It does not say what happens when the reminder is already deleted or already delivered, which matters given the non-idempotent hint.

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, zero filler, with the action and its scope stated first and the exclusion boundary second. Nothing is redundant with the annotations or schema.

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?

An output schema exists, so return values need not be described, and the destructive side effects and non-effects are covered. The remaining gap is identifying which id to pass and what an already-expired or nonexistent reminder produces, which a caller of a non-idempotent delete would want to know.

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% on the single required parameter, so the description was the only place to explain that 'id' is the reminder UUID (presumably from list_reminders) rather than a ticket, follow, or user id. It says nothing about the parameter at all, leaving the agent to infer the identifier type from the name alone.

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

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

States a specific verb and resource ('Delete ... your reminder') and immediately delimits scope ('only your reminder ... Does not alter tickets or follows'), so an agent knows this removes a reminder and nothing else. It is clear without opening the schema, though it never distinguishes itself from the sibling delete_alert.

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

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

Usage is only implied: the word 'your' and the single id parameter suggest deleting a reminder the caller owns, presumably one obtained from list_reminders. There is no explicit when-to-use versus list_reminders or delete_alert, and no stated precondition such as owning the reminder.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful caveats that estimates (travel, runtime, trailer) are non-binding and that no tickets are booked, but it says nothing about how the optional filters constrain results or whether an empty result is possible.

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 operation and scope, followed by the caveats. No redundant restatement of the tool name and no 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?

An output schema exists, so return values need not be described. However, for a six-parameter tool where four optional filters are undocumented in both schema and description, the definition leaves an agent unable to use the narrowing parameters confidently.

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 six parameters, so the description carries the full burden and largely fails. It names only the required theatre and date; movie, format, minGap and maxGap receive no explanation, and the 0-240 integer range for the gap parameters is never identified as minutes or otherwise defined.

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: pairs of movies at the same theatre for a single theatre and date, computed by a 'pairing engine'. This distinguishes it from search_showtimes and get_best_showings, which return individual showings, though the description never names those siblings explicitly.

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 scope ('one theatre and date') implicitly tells the agent this is a per-theatre query, but there is no explicit when-to-use guidance or routing versus search_showtimes, get_best_showings, or find_theatres. An agent must infer that this is the double-feature-specific path.

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 still adds real context beyond them: results are limited to "active collected" theatres (not the entire AMC estate) and theatre capabilities must not be read as showing-level format data — a genuine misuse guard.

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 with the core capability front-loaded and the caveat second. "Active collected" is slightly jargon-heavy but every clause earns its place; nothing is 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?

An output schema exists and annotations cover safety, so return-shape explanation is rightly omitted. The gap is behavioral: with no required parameters, an agent cannot tell from the description whether an empty call is valid or what it returns, nor how zip, query and radius combine.

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

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

With 0% schema description coverage, the description carries the burden and does partially compensate: it identifies the query as name/city, the zip as a ZIP filter, and states the radius unit is miles (the schema gives only min/max/default without a unit). It omits the default radius behavior and what happens when no parameters are supplied, which matters for a tool with zero required parameters.

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 ("Find") with a precise resource and scope: "active collected AMC theatres" searchable by name/city, ZIP and radius. It is clearly distinguishable from showtime-oriented siblings like search_showtimes or get_best_showings, though it never names those siblings explicitly.

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 clause "Theatre capabilities do not establish an individual showing's format" implicitly warns the agent not to use this tool for format/showing questions, which is useful implied routing. However, it never states when to prefer this over search_showtimes or find_double_features, nor any prerequisites for calling 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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses that the full ranking is returned, capped at 600 with a truncated flag, and never paged — non-obvious output behavior an agent needs. It also clarifies the side-effect boundary ('does not queue or book'), though it says nothing about auth or plan prerequisites.

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 compact sentences with the core action front-loaded and the output/scope caveats following. The middle clause ('the same planner eligibility, protected ticket conflicts and format preferences') is dense and slightly jargon-heavy, but 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?

An output schema exists, so return values need not be spelled out, and truncation behavior is covered. However, for a 3-parameter tool with zero schema descriptions, the definition leaves the date range and film identifier unexplained, which is a real gap 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%, so the description must carry the parameter meaning and does not: filmId, from and to are never mentioned, and there is no guidance on date-range formats or defaults. Only the implied 'owner's home theatres' scoping relates loosely to the parameters.

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 ('Rank existing showings') plus the scope ('at the owner's home theatres'), which separates it from a generic showtime search. It stops short of naming the obvious sibling (search_showtimes), so an agent must infer the boundary itself.

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?

'Does not queue or book' rules out a booking path and implicitly contrasts with request_booking, and 'planner eligibility' hints at a plan dependency. There is still no explicit when-to-use statement or a named alternative for plain showtime lookup.

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 two things annotations cannot: the data reflects as-planned rather than live state (a staleness/semantics caveat), and the tool is gated to private-beta owners (an authorization constraint). It stops short of rate limits or failure behavior, but for a zero-parameter read with an output schema that is a modest gap.

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 most important disambiguation ('not live AMC eligibility') placed before the access caveat. Nothing could be removed without losing meaning.

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 input parameters, full annotation coverage and an output schema that describes the return shape, the description carries only the burden of scope, semantics and access. It covers all three: as-planned data, the live-eligibility contrast, and the private-beta restriction.

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 there is nothing for the description to disambiguate; the baseline for a parameterless schema applies. No misleading parameter claims are made.

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 ('Read planner capacity') and immediately contrasts it with the confusingly similar 'live AMC eligibility'. However, 'planner capacity' and 'AMC' are unexplained domain jargon, so an agent unfamiliar with the domain gets a precise-sounding but only partly decoded purpose. It does not need sibling differentiation since no sibling among the listed tools covers capacity or eligibility.

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

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

Provides a genuine exclusion ('not live AMC eligibility') plus an access precondition ('Private-beta owners only'), which is more than most definitions offer. The gap is that no alternative tool is named for the live-eligibility case, so the agent knows what this is not but not where to go 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds little behavioral context beyond that - nothing about what happens with an unknown ID/slug, whether partial records are possible, or any auth requirement. It neither contradicts nor meaningfully extends 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?

Two short sentences, zero filler, with the primary action stated first and the sibling routing second. 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?

This is a simple one-parameter read tool with an output schema, so return values need no explanation and the annotations cover safety. The description supplies the identifier semantics and the sibling routing, leaving nothing an agent needs in order 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 0%, so the description must carry the parameter meaning, and it does: it tells the agent the single 'movie' argument accepts either a numeric ID or a slug. That is genuinely useful information absent from the schema, which only shows a string pattern with length bounds.

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 and resource ('Get the collected movie record') and names the identifier type, so an agent knows exactly what is returned. It also points to search_showtimes for showings, which separates it from the nearest sibling. Minor ambiguity remains in the word 'collected', but the core purpose is unambiguous.

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

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

It explicitly routes showings lookups to search_showtimes, giving a clear when-to-use-elsewhere condition. It does not cover other plausible neighbours such as find_theatres or get_best_showings, but for a single-record lookup the guidance given is sufficient context.

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 covered. The description adds genuinely new context beyond them: the 'Requires read scope' authorization requirement and the fact that it targets only the connected owner's settings, not arbitrary users.

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, and the resource being read is front-loaded ahead of the authorization note. 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?

With full annotation coverage, an output schema that already defines the returned preference fields, and no parameters, the description needs only to state the resource and the auth requirement, which it does. It stops just short of completeness by not mentioning behavior when no owner is connected or the read scope 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 there is no parameter semantics to explain and the baseline is 4. The description correctly avoids inventing parameters and simply characterizes the fixed scope of the read.

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 ('Read') and a concrete resource ('the connected owner's email/push preferences, timezone, quiet hours and digest schedule'), and the field list makes the scope unambiguous. It does not explicitly name the sibling it pairs with (update_notification_settings), but 'read' versus 'update' makes the distinction self-evident.

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

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

Usage is only implied: an agent infers this is the read counterpart when it needs current preferences before a write. There is no explicit when-to-use or when-not-to-use guidance, and the sibling update_notification_settings is never named as the alternative for mutations.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is largely covered. The description still adds domain-level behavior: the response covers an access-gated 'private-beta' plan plus 'protected booked tickets' and 'as-planned capacity', and it explicitly rules out side effects on bookings. It does not discuss pagination or freshness of capacity figures.

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 what is read, followed by the disambiguating side-effect disclaimer. Every clause carries information; nothing is padding.

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

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

With an output schema present, return-value documentation is unnecessary, and rich annotations plus zero parameters keep the burden low. The description adequately scopes content, though a note on access requirements for the private beta or on how 'capacity' differs from the get_capacity sibling would close the remaining 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 tool takes zero parameters, so the baseline is 4; there is no parameter meaning for the description to add 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 ('Read') and an enumerated resource set: private-beta plan, protected booked tickets, requests, and as-planned capacity. It is clearly distinguishable from the mutation siblings, though it never names an overlapping read sibling such as get_capacity or get_subscription_status.

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 line 'Never creates booking intent' is a negative constraint, not when-to-use guidance, and the description names no alternatives despite several sibling reads (get_capacity, get_subscription_status, get_pricing) that could plausibly be confused with this one. An agent is left to infer the routing decision.

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 genuinely new behavior: public pricing facts are free to read, while payment always requires a human to open and confirm a Stripe-hosted Checkout URL — important context that no annotation conveys.

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 core action, with no filler. The second sentence is slightly tangential to a read tool but earns its place by pre-empting an attempt to pay through this call.

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?

Annotations cover safety and an output schema exists, so return values need not be explained. However, the description leaves ambiguity about what "alerts price" actually comprises versus a plan, which matters given siblings get_plan and get_subscription_status.

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 is 4. The description correctly implies a parameterless, context-free read and does not mislead about any inputs.

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?

"Read the current configured alerts price" gives a verb and a resource, but the resource is fuzzy: it is unclear whether this returns a plan price, tier list, or a single configured amount. It also does not distinguish itself from close siblings like get_plan and get_subscription_status, which an agent could easily confuse with a pricing read.

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?

"Public facts are free" implies this call needs no authentication and is safe to invoke liberally, and the Stripe sentence implies payment is out of scope for this tool. But the actual alternative (create_checkout_link) is never named, and there is no explicit statement of when to prefer get_plan or get_subscription_status 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, so the safety profile is covered. The description still adds value by scoping the lookup to 'the connected owner's' subscription and explicitly denying any charge or billing modification, which are behavioral facts not encoded in 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?

Two short sentences, zero filler. The core purpose is front-loaded and the caveat about not touching billing follows immediately after.

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

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

With an output schema, a zero-parameter input, and full annotation coverage, the description needs only to state what is checked and that it is side-effect free. It does both, so an agent has everything required 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?

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly implies the owner is derived from connection context rather than supplied as an argument.

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 ('Check') and a specific resource ('the connected owner's alerts subscription is active'), plus the states covered (pre-payment, post-expiry). An agent can distinguish it from start_subscription or get_plan by the 'status check' framing, though no sibling is named explicitly.

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 clear usage context — check before payment or after expiry — which tells the agent when this is the right call. It also implicitly excludes billing-mutation tools via 'does not charge or modify billing', but it never names an alternative such as get_plan or start_subscription.

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, but the description adds genuinely new behavioral context: token secrets are never returned, and a read scope is required. Those are the two facts an agent most needs before calling, though it says nothing about result volume or pagination.

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

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

Three short sentences, front-loaded with what the call returns, followed by the auth requirement and the ownership caveat. No filler, and every sentence contributes information the agent cannot get from the schema 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?

With an output schema present, return values need no explanation, and the description still summarizes them plus the scope requirement. For a zero-parameter read tool the only minor omission is any note about result size or ordering.

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 there is nothing for the description to clarify beyond the schema; baseline 4 applies. It correctly implies the owner is inferred from the caller's credentials rather than passed in.

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 ("List connection IDs, names and scopes") plus the scoping constraint "for this owner", so the agent knows exactly what comes back. It does not explicitly name the sibling it differs from (revoke_this_token), only alluding to creation/revocation, so it falls short of full sibling differentiation.

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?

"Requires read scope" gives a clear precondition, and the closing sentence signals that create/revoke operations are outside this tool and reserved for the human owner key, implicitly routing the agent to a different tool. It stops short of naming that alternative explicitly, so it is clear context rather than 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely new behavioral context by stating "Requires read scope", telling the agent an auth precondition exists before calling. It stops short of saying what happens when that scope is missing, but with an output schema present no return-value explanation is needed.

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, no filler, and the scope constraint is placed before the auth prerequisite. Every clause carries information an agent needs: what is returned, whose data, and what permission is required.

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 zero parameters, full schema coverage, an output schema, and rich annotations, the definition covers nearly everything required to invoke the tool. The only meaningful omission is routing guidance relative to the sibling list_reminders and list_drops tools.

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 contributes nothing beyond confirming an empty argument object; the baseline of 4 applies. The description correctly adds the implicit scope constraint (connected owner only) that an agent would otherwise have to guess.

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 resource ("List ... saved follows") and scopes it to the connected owner, which distinguishes it from create_alert/update_alert/delete_alert. The one blemish is terminology drift: the tool is called list_alerts but the description calls them "saved follows", leaving a small ambiguity about whether alerts and follows are the same object.

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?

"List only the connected owner's" implies that no filtering by other users is possible, which is useful usage framing, but it never states when to pick this over the adjacent list tools (list_reminders, list_drops) or that the paired create/update/delete/pause/resume alert tools are the mutating counterparts. Usage is implied rather than directed.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond that: results are historical collected evidence rather than a live feed, on-sale aggregates keep nested evidence, and top-level theatre/format displays can be null when firstBookableEvidence is unknown.

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 dense sentences with the core purpose front-loaded and no filler. The middle sentence about nested evidence and nullable fields is somewhat compressed and leans toward describing return shape that the output schema already covers, but it is not wasteful enough to penalize heavily.

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

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

With an output schema present, the description need not explain return values, yet it spends a sentence on them anyway while omitting higher-value information such as pagination behavior and geospatial filtering semantics. The freshness caveat and nullability note make it adequate, but not complete for an 11-parameter filtered-list 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 0% across 11 parameters, so the description must carry the load and it largely does not. It clarifies only that 'since' is an absolute ISO time; it says nothing about the zip/radius coupling, page/pageSize paging, dateFrom/dateTo windowing relative to 'since', or how movie/format/theatre narrow results.

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 and resource: find newly observed premium showings or new on-sale evidence since an absolute ISO time, and enumerates the returned fields. This clearly distinguishes it from search_showtimes and get_best_showings, which retrieve current showtimes rather than deltas, even though those siblings are not named explicitly.

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

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

Usage is implied by the delta framing ('since an absolute ISO time') and the caveat that this is collected evidence rather than a real-time feed, which hints at when results may be incomplete. However, there is no explicit guidance on choosing this over search_showtimes, how to combine zip and radius, or whether to fall back to another tool when the evidence is sparse.

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 genuinely non-obvious context: the call is scoped to the caller's own reminders and, unexpectedly for a read operation, requires the alerts:write scope — a detail an agent could otherwise get wrong.

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, zero filler, with the scoping constraint and return content front-loaded before the prerequisite. Nothing is repeated from 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?

With an output schema covering return values, rich annotations, and no parameters, the description supplies the remaining critical facts: personal scope and the required alerts:write scope. Only ordering/volume expectations are left unstated, which is minor for a list 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 and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline for a parameterless tool would be higher, but the description also volunteers no argument or scoping options, so it neither adds nor subtracts meaning here.

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

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

The description uses a specific verb and resource ('List ... your reminders') and adds scope ('only your'), which separates it from list_alerts and the mutation siblings set_reminder/delete_reminder. It stops short of naming a sibling explicitly, so it is clear but not maximally differentiated.

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

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

Usage is implied rather than stated: an agent can infer this is the read path for reminders versus set_reminder/delete_reminder. There is no explicit when-not guidance, no mention of list_alerts as the alternative for alert objects, and no note on whether filtering or pagination 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 declare non-read-only, non-destructive, non-idempotent behaviour, and the description adds genuinely new operational context: the required OAuth scope, the paid-plan gate, and the fact that only your own alerts can be paused. It leaves unaddressed what happens on an already-paused alert, which matters given idempotentHint=false, and whether pausing is indefinite.

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 action and scope, then the gating requirements. Every clause carries information an agent needs; 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. Still missing for a mutation tool: the duration/semantics of the pause (indefinite until resume_alert?), behaviour when already paused, and error conditions beyond the plan gate.

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 'id' parameter has 0% schema description coverage, so the description must carry the load. 'The connected owner's alert' partially constrains what id qualifies, but it never says the id is an alert identifier, its format, or how to obtain it (e.g. via list_alerts). Adequate but incomplete for a zero-coverage 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 (pause) and resource (alert) plus a scoping constraint: only the connected owner's alert. An agent can distinguish it from resume_alert, delete_alert, and update_alert by name alone. It stops short of explicitly naming the inverse sibling, but the purpose is unambiguous.

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

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

The description supplies prerequisites (alerts:write scope and a paid plan) and an ownership restriction, which tells the agent when the call will fail. However, it never states when to prefer this over resume_alert/update_alert, nor what condition should trigger pausing rather than deleting or updating an alert.

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

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

Annotations declare non-read-only, idempotent, non-destructive, closed-world, and the description adds genuinely new behavior: it creates intent only, never a booking, charge or AMC call, and that BRIDGE alone executes. The 'stable clientKey for retries' line ties the idempotency hint to a concrete practice. It loses a point because 'enforces zero-only' is unexplained jargon an agent cannot act on.

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 calling gate, then the input shape, then the safety boundary. Minimal waste, though the closing 'BRIDGE alone executes and enforces zero-only' is dense internal jargon that could be plainer.

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

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

With an output schema present, return values need not be explained, so the description is appropriately scoped. For a nested, four-parameter mutation-style tool it covers the gate, the intent-only semantics, retry keying and the either/or input shape, leaving only the flexibility sub-field requirements and duplicate-clientKey behavior unstated.

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 carry parameter meaning. It adds two useful facts — 'a selected showing OR complete flexibility' establishes mutual exclusivity that the schema does not encode, and clientKey is tied to retries — but it says nothing about filmId or the six required flexibility sub-fields (dateWindow, allowedFormats, allow3d, time bounds, theatres).

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 ('queue a booking', 'Creates intent only') on a specific resource, and the clarification that it never creates an actual booking or charge sharpens what kind of request this is. It is distinguishable from cancel_booking_request by name and from search_showtimes/get_best_showings by function, though it never names those siblings explicitly.

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?

'Only call when the human explicitly asks to queue a booking' is an explicit gating condition that most sibling tools lack, giving a clear when-to-use rule. However, it does not name the alternative tools to use when the user has not explicitly asked (e.g. search_showtimes for browsing), leaving the negative case implicit.

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 (which only declare non-readonly, non-idempotent, non-destructive), the description adds two substantive facts: the alerts:write scope and paid-plan prerequisite, and the key behavioral caveat that no paused-period backlog is delivered on resume. That caveat is exactly the kind of side effect an agent cannot infer from structured fields. It stops short of saying what a repeat resume on an already-active alert returns, which matters given 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 tight sentences with the ownership constraint front-loaded and the prerequisites and caveat following in priority order. Every clause carries distinct information; nothing is redundant with 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?

For a one-parameter state-changing tool with annotations and an output schema, the description covers the permissions model, plan gating, and the most important behavioral surprise. The remaining gap is the unexplained id parameter and the result of resuming an already-active alert.

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 sole parameter, id, is never mentioned in the description, so nothing is added about its meaning or accepted format (the schema only supplies a pattern and length bounds). The identifier is guessable from context, which prevents a 1, but the description does not 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 gives a specific verb and resource ("Resume ... paused alert") plus a scope qualifier ("only the connected owner's"), which clearly separates it from unrelated siblings. It never names the obvious counterpart pause_alert, so the reverse-operation relationship is left implicit rather than stated.

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?

"Resume only the connected owner's paused alert" implies the precondition (the alert must be paused and owned by the caller) and implicitly routes agents away from pause_alert. However, there is no explicit when-not guidance, no named alternative for unpausing another user's alert, and no statement of what happens when the alert isn't paused.

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

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

The description adds meaningful behavioral context beyond the destructive annotation: revocation is immediate and permanent, future calls fail, only a human can issue a replacement, and billing is not cancelled. These consequences are exactly what an agent needs before invoking a destructive self-revocation.

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

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

The description is three short sentences with no wasted wording. Critical information, including permanence and replacement constraints, 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 simple parameterless destructive tool with annotations and an output schema, the description covers the essential missing context: permanence, future authentication failure, human-only replacement, and billing scope. Nothing material appears to be omitted.

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 there is no parameter semantics for the description to clarify. The baseline for a parameterless tool is 4, and no additional explanation is needed.

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 and resource: 'revoke the current agent token.' It is clearly scoped to the calling token itself, which distinguishes it from sibling inventory tools such as list_agent_tokens.

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 makes the use case clear: disconnect the current agent by permanently revoking its token. It also clarifies the downstream consequence, but it does not explicitly state when this should be preferred over simply stopping use of the token, though no direct sibling alternative exists.

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 behavior, so the description is not carrying the safety burden. It does add real value beyond them: rows preserve IDs, unknown display facts are returned as null rather than omitted, and prices/coverage are explicitly flagged as observations rather than guarantees. The "confirm with AMC" caveat tells the agent how to frame results to a user.

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, both front-loaded with the highest-value information: filters first, then row shape and caveats. Dense but every clause carries signal; the only mild redundancy is enumerating return fields when an output schema already 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?

For a 9-parameter read tool with an output schema and full annotation coverage, the definition covers the filtering model, null semantics, and a data-freshness caveat. The remaining gap is pagination behavior (page/pageSize defaults and limits), which the agent must read out of 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 description coverage is 0%, so the description has to compensate, and it partly does: it names movie, theatre, ZIP, radius, format and date range, and crucially adds the unit "(miles)" for radius, which the schema does not state. However, page and pageSize are never mentioned, and nothing explains the theatre slug pattern or the ZIP five-digit constraint, leaving 3 of 9 parameters 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?

The description opens with a specific verb+resource ("Find collected showtimes") and enumerates the filterable dimensions: movie, theatre, ZIP, radius, format, date range. An agent can immediately tell this is a filtered read over collected showtime data. It stops short of naming how it differs from siblings like find_theatres or get_best_showings.

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

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

Usage is implied by the facet list — you come here to narrow showtimes by location, film, or date. There is no explicit when-to-use/when-not guidance and no reference to the plausible alternatives (find_theatres, get_best_showings, find_double_features), so an agent must infer the routing decision.

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=false, destructiveHint=false, idempotentHint=false, so the safety profile is known; the description usefully adds that the write is confined to a preference and touches no protected tickets. It does not say whether the call replaces the entire existing preference (overwrite semantics), and idempotentHint=false is left unexplained even though re-sending identical values is a natural agent concern.

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 the positive action front-loaded and the scope guard second; nothing is filler. 'Explicit 3D permission' is compressed to the point of being slightly ambiguous, which keeps it from a 5.

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?

An output schema exists, so return values need no explanation, and with only two required parameters the tool is simple. Still, for a non-idempotent mutation the description should state whether the preference is fully replaced and whether allow3d must be consistent with formatOrder, which it does not.

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 carries more burden than baseline, and it does loosely map both parameters ('format order' → formatOrder, '3D permission' → allow3d). It never explains that formatOrder is an ordered priority list (minItems 1, maxItems 7) or how the separate allow3d flag relates to '3d' appearing inside formatOrder, which is the main ambiguity an agent will hit.

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 gives a specific verb (Set) and two concrete resources (default format order, explicit 3D permission), and no sibling tool covers format preferences, so an agent can place it immediately. It stops short of saying what a 'format order' governs (showtime ranking?), leaving the resource slightly under-defined.

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 clause 'Never books or modifies protected tickets' acts as a useful when-not boundary, steering agents away from using it as a booking tool. However, it names no alternative (e.g. request_booking) and gives no precondition such as an existing plan/subscription.

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 (non-read-only, non-destructive, non-idempotent, closed-world), the description adds genuinely useful behavior: quiet hours are respected even for on-sale reminders, delivery rides on an existing alert's confirmed channel, and movie dates are supplied facts rather than predictions. It does not say whether repeating calls create duplicate reminders (relevant since idempotentHint=false) or what happens when the target time has already passed.

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 dense sentences, front-loaded with the two modes and followed by preconditions and limits; no filler or restatement of the tool name. Slightly compressed phrasing ("an already booked planner ticket") costs a little readability but 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 an output schema and annotations present, the description needn't explain return values, and it covers prerequisites and behavioral constraints well. However, for a 7-parameter non-idempotent mutation it omits how parameters combine per kind and what happens on duplicate or past-dated reminders, which an agent needs 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 0% across 7 parameters, so the description must carry the semantics, and it explains only the deliverySubscriptionId concept loosely and that "at" is a human-selected date/time. It says nothing about minutesBefore (offset semantics and 1–10080 bounds), the event enum, or that ticketId is needed for kind=ticket while movieId plus event are needed for kind=movie, leaving the conditional requirements 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 names a specific verb/resource (set a reminder) and splits it into two clearly different modes: pre-show reminders for an already booked ticket, and explicit on-sale/first-showing dates for a known movie. It also explicitly separates itself from booking, though it never names the sibling tools (create_alert, list_reminders) it should be distinguished from.

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?

Preconditions are stated (must reference an existing owned Following alert with confirmed email/registered push) and an exclusion is given ("Does not book or create notification consent"), which tells the agent when NOT to use it. It stops short of naming alternatives such as create_alert for consent creation, so routing is only partially covered.

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 non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds genuinely new behavior: 'Top protects booked tickets' and 'lowering a tier never removes protection' explain side effects the annotations cannot express. It stops short of disclosing whether a change notifies the user, whether notes overwrite existing notes, or why the operation is not idempotent.

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, front-loaded with the action and the enum, followed by the protection caveat and the negative scoping statement. Nothing is padded, though enumerating all six tier values duplicates the schema enum and spends words that could have described 'notes'.

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?

An output schema exists, so return values need not be explained, and the mutation's safety profile is in annotations. Still, for a three-parameter write tool the description leaves the 'notes' parameter and the meaning of 'existing rules' entirely opaque, which is a meaningful gap 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%, so the description carries the full burden, yet it only restates the tier enum values that the schema already lists explicitly. The 'notes' parameter (maxLength 4000) is never mentioned — an agent has no idea what notes are for or whether they replace or append. 'filmId' is likewise unexplained beyond its regex pattern.

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 verb 'Set' plus the enumerated tier values make the operation recognizable, and the title supplies the missing object ('a movie's planner tier') that the description itself leaves implicit. It also differentiates from request_booking by stating 'Does not create a booking request', so an agent can separate it from the booking siblings. The only weakness is that the description alone never names the resource being modified.

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?

There is one explicit exclusion ('Does not create a booking request') and a rule about protection semantics, which implies usage context. However, 'using existing rules' is undefined, and there is no guidance on when to choose this versus set_reminder, request_booking, or set_format_preference among the many siblings. Usage is implied rather than stated.

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 cover the safety profile (non-read-only, non-idempotent, open-world), so the bar is lower, yet the description still adds real context: the connection is left 'pending', payment confirmation happens only on Stripe by the human, and the returned token must be kept private. It also warns against repeated invocation. It does not say what happens if it is called repeatedly or how long the pending state lasts.

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 short sentences, front-loaded with the target audience and the effect, followed by operational constraints. No filler. Slightly list-like but each sentence carries a distinct instruction.

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?

An output schema exists, so return-value documentation is not required, and the description covers the side effects and the human-in-the-loop step that a mutating, non-idempotent tool needs. The remaining gap is the undocumented optional name parameter, which is the one thing an agent could get wrong.

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

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

There is one optional parameter ('name', default 'My AI agent') with 0% schema description coverage, and the description says nothing about it - no hint that it names the agent, that it is optional, or what the default produces. An agent must infer the parameter entirely from the property name.

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 and resource: create a pending agent connection plus a Stripe-hosted Checkout link, scoped to 'a person without an account'. It implicitly separates itself from the existing-subscriber path, though it never names the sibling tools (get_subscription_status, create_checkout_link) that an agent would need to rule out.

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?

Clear exclusions are given: not for an existing subscriber, and not to be called repeatedly. The preconditions ('person without an account') and the human hand-off step are stated. What is missing is the positive routing - no sibling is named as the thing to call instead when the user already subscribes.

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 is a non-read-only, non-destructive, non-open-world mutation, so the safety profile is covered. The description adds real value by disclosing patch semantics ("without changing omitted preferences") and the authorization prerequisites. However, it does not say what happens when a field is set to null or an empty array, and the merge-style partial update sits slightly awkwardly against 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?

Three tight sentences with no filler: the mutation scope and partial-update contract come first, followed by ownership and permission constraints. Every clause conveys a distinct constraint 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?

An output schema exists, so return values need not be described, and the auth/ownership requirements are well covered for a mutation. The gap is the nine-parameter payload with zero schema descriptions, five of which are unexplained and include consent-related fields (email, emailConsent, browser) where mis-setting could have side effects.

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 carry the load, and it names only four of nine parameters (theatres, formats, triggers, cadence). The meanings of id, email, browser, timezone, and emailConsent are not explained anywhere, and no guidance is given on enum values or the maxItems limits beyond the schema itself. Partial credit is earned for signaling that unspecified fields are left untouched.

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 ("Update a saved follow") and enumerates the mutable facets: theatres, formats, triggers, cadence. An agent can distinguish it from create_alert/delete_alert, though the naming drift between "alert" (tool) and "follow" (description) and the absence of any mention of pause_alert/resume_alert leaves some ambiguity about the full alert lifecycle.

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 clear when-to-use conditions: only for the connected owner's own alert, only for an entitled owner with alerts:write. It also implies when-not-to-use via the ownership restriction. It stops short of explicitly routing the agent to siblings such as pause_alert, resume_alert, or delete_alert for lifecycle changes.

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=false, destructive=false) it discloses the partial-patch mutation model, the required authorization scope, and a meaningful side-effect caveat that toggling email on does not bypass opt-in/confirmation or browser permission. It does not describe error behavior or whether unsetting a value is possible, which keeps it 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, front-loaded with the mutation model, then schema, then prerequisites and the email caveat. No filler or restatement of the tool 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?

Output schema exists so return values need no explanation, and the description covers patch semantics, permissions and the email-opt-in trap for an 8-parameter mutation. Remaining gaps are the undocumented timezone/onSaleOverride fields and any note on validation of the HH:MM patterns.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It groups most fields into recognizable concepts (channel toggles = emailEnabled/browserEnabled, quiet hours = quietStart/quietEnd, digest schedule = digestTime/weeklyDay) but never mentions timezone or onSaleOverride, leaving two of eight parameters unexplained anywhere.

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 ('Partially update the connected owner's channel toggles, quiet hours or digest schedule') and scopes it to the connected owner, which implicitly separates it from the read counterpart get_notification_settings. It stops short of naming any sibling explicitly, so differentiation relies on inference from the verb.

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 clear preconditions: alerts:write scope, an entitled owner, and the note that only supplied fields change so callers can patch a subset. It does not state when to prefer this over get_notification_settings or what to do on failure paths, but the usage context is unambiguous.

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