Checkout Page

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description repeats 'Read-only' and adds that output comes as HTML and a React component, which is useful formatting context. It does not add behavioral details beyond the annotations, such as permission requirements or error behavior, so a baseline 3 is appropriate.

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

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

Two sentences with zero waste: the first sentence front-loads what the tool returns, and the second provides precise usage context. Every sentence earns its place and the structure is easy to scan.

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 read-only code-generation tool with 100% schema coverage, full annotations, and an output schema, the description covers purpose and usage adequately. Return values are handled by the output schema, so the description does not need to explain them.

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

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

Schema description coverage is 100%, so all three parameters, including the mode and pageType enums, are fully documented in the schema. The description adds no additional parameter meaning or usage constraints. Baseline 3 is correct when the schema does the heavy lifting.

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 ready-to-paste code that puts a checkout page, form, or event on a website.' It explicitly distinguishes the tool from sibling creation tools by naming create_checkout_page, create_form, and create_event as preceding actions. An agent can tell this is a code-generation/embed tool, not a creator or updater.

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 triggering conditions: 'Use it right after create_checkout_page, create_form, or create_event when the user is building or editing a website, or when the user asks to add a checkout, buy button, ticket form, or signup form to their site.' This covers when to use it well. However, it does not name alternatives or explicitly state when not to use it, so it falls short of the top score.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, and the description meaningfully extends them: the operation is reversible-in-spirit ('archived, not deleted'), data and sold tickets are retained, get_event still lists it with status archived, and dependent ticket types lose their trigger. That is exactly the kind of consequence disclosure an agent needs before mutating.

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 action, then consequences, then ID sourcing. No filler and no repetition of the 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?

For a single-resource mutation with full schema coverage and an output schema, nothing needed to invoke it correctly is missing: what it does, what it does not do, side effects on dependent types, and where the IDs come from.

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

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

Schema coverage is 100% and each parameter already documents its source in get_event, so the schema does the heavy lifting. The description only restates the sourcing hint and adds no format or constraint detail beyond it.

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

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

States a specific verb and resource ('Archive one ticket type on an event') plus the observable effect ('no longer on sale'). It is clearly distinguishable from update_ticket_type and from any delete-style sibling.

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 explains the archive-vs-delete distinction and where to obtain the three required IDs ('Get the event, group and ticket type IDs from get_event'). It does not explicitly contrast with update_ticket_type for near-identical outcomes (e.g. simply hiding a type), so it falls short of full when/when-not routing.

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

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

Annotations only flag destructive/write; the description goes far beyond, disclosing the concrete side effects that make it destructive (tickets issued, PDF confirmation email sent, capacity decremented in live mode, booking.paid webhook fires, invoice may be generated), the absence of undo through this API, and the non-idempotency warning against blind retries. These are exactly the traits annotations cannot convey.

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

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

Bold front-loaded warnings and bulleted strategy/error blocks make it scannable despite being long. It is dense but almost every line earns its place; the nine-point error list is arguably more than strictly needed, slightly diluting structure.

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

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

A destructive, non-idempotent mutation tool with 8 params and an output schema present; the description covers side effects, no-undo path, exclusivity rules, capacity/sold-out guards with specific status codes, and worked examples. An agent has everything needed to call it safely and interpret failures.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic value the schema does not: it explains the exclusivity constraint between paymentOption and complimentary, the meaning of each manualType ('unpaid with full amount as balance due, settled outside checkout'), and that complimentary records paid with isComplimentary true. It omits notes on couponId incompatibility with comp (covered in errors) and fields/ticketPwywAmounts semantics, keeping it from a 5.

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

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

States a specific verb+resource ('Create a real event booking on an existing event') and crucially distinguishes scope from siblings by declaring it does NOT collect card payment, which separates it from create_checkout_page. An agent can route between this and checkout instantly.

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

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

Explicitly enumerates when to use each of two mutually exclusive strategies (paymentOption.manualType vs complimentary: true) with named scenarios (box-office, phone, invoiced corporate, migrations vs comped guests, speakers, staff, press). It also routes recovery: 'If the outcome of a call is uncertain, check list_bookings before trying again.'

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, openWorld=true), it discloses non-obvious behavior: the page is "always created published and immediately available at its hosted URL," tax defaults to Stripe mode, omitting `fields` yields specific defaults, and omitting the required email element causes the request to fail.

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

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

It is long, but for a 55-parameter tool the length is mostly justified and well-structured with bold section headers, front-loaded purpose, and worked examples. A few of the usage examples partially restate schema facts, but nothing is egregiously wasteful.

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 highly complex creation tool, the description supplies guidance on defaults, failure conditions, tax/payment constraints, and the recommended follow-up call. It even restates the return fields (data.id, hostedUrl, dashboardUrl) despite an output schema existing, which is redundant but harmless and helps the agent chain the next step.

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 55 parameters at 71% schema coverage, the description meaningfully supplements the schema for the highest-stakes fields: `fields` (email requirement, address grouping), `tax.mode`, the exact supported `paymentOptions` combinations, and `themeOverrides`/`hostedLayoutType`. Many lower-salience params (fees, funnelSteps, abandonment settings) are left to the schema, but the critical ones are covered.

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

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

The first sentence states a specific verb+resource+scope: "Create a new checkout page with an attached product and pricing." It is immediately distinguishable from siblings like create_event, create_form, and create_booking, which build other page types.

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

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

The description explicitly says when to use it ("whenever a merchant wants to start accepting payments") and how to behave under ambiguity ("when the request is vague, create a minimal checkout page... do not overcomplicate"). It also names the follow-up sibling (add_to_website) with the condition that triggers it.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-open-world mutation, so the safety profile is covered. The description adds genuine behavioral rules beyond that: the pageIds/ticketTypeIds dependency and the hard failure ("or the request fails") when ticket types are passed without their parent page. It omits error behavior for duplicate codes and permission/auth requirements, keeping it out of the top band.

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 purpose and trigger are front-loaded, then two bolded sections group closely related constraints. For a 13-parameter tool every sentence carries distinct operational information with no repetition of schema text.

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

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

An output schema exists, so return values need not be described, and annotations cover mutation safety. The description supplies the conditional logic needed to build a valid request, though it says nothing about duplicate-code handling or what the created coupon response contains.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real cross-parameter meaning: the hierarchical constraint that ticketTypeIds must be narrowed from pageIds, the event-page prerequisite, and the mutual exclusion of amountOff/percentOff. These are relational rules the schema only partially implies.

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 first line states a specific verb and resource ("Create a coupon for Checkout Page"), which is unambiguous and clearly distinct from update_coupon/list_coupons. It does not, however, explicitly name or rule out any sibling tool, so it falls short of the top band that requires active 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?

"Use this when a merchant wants a discount code that customers can enter on eligible pages" gives a clear trigger condition for invoking the tool. There is no explicit when-not or alternative-tool guidance (e.g., when to update an existing coupon instead), so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds real behavioral context beyond that: the structure (event details + ticket groups + ticket types), the pricing unit convention, and the exact return fields (id, name, hostedUrl, dashboardUrl). It doesn't discuss auth, limits, or side effects of failure, so not 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?

Front-loaded purpose, then usage, then examples, then field/return guidance. The three short examples are efficient illustrations. A bit verbose in the design-labels paragraph, but every sentence carries guidance.

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?

Covers the core flow of creating an event, naming key inputs, and enumerating return fields, so an agent can act end-to-end. Given the enormous 58-param surface, some advanced options (funnels, payment options, tax) are left to the schema, which is acceptable since output schema also exists.

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 52%, and the description targets the most important pieces anyway: prices as integers in smallest currency unit, ISO 8601 dates, themeOverrides/hostedLayoutType usage, and themeId via list_themes. But for a 58-parameter tool with 52% coverage, the description leaves many parameters (fees, funnelSteps, paymentOptions, etc.) undocumented in prose.

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

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

States a specific verb+resource ('Create a new event for selling tickets') and scopes it precisely. It distinguishes itself from siblings like create_checkout_page by emphasizing ticket-selling events and even names related tools (list_themes, add_to_website) for follow-up work.

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 when-to-use ('when a merchant wants to publish an event that sells tickets') with concrete examples (single free RSVP, paid tiers, capacity). It also prescribes a next action ('call add_to_website next... Do not wait for the user to ask'), which is unusually actionable 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=false and destructiveHint=false, so safety is covered; the description adds genuine behavior beyond that: fields are appended by default, order overrides placement, and visibility rules must reference existing field/option IDs from the page detail response. The word 'Mutating' is redundant with the annotations, keeping 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?

Four dense clauses, front-loaded with the action and scope, then ordering behavior, a prerequisite, and sibling routing. No filler and nothing repeated from the 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?

With an output schema present, 100% schema coverage, and annotations covering the safety profile, the description only needs to add scope, ordering, prerequisites, and routing — all of which it does. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the `order` parameter ('Appended after the current fields unless order is given') that the schema's array-position phrasing does not convey for a single-field call. It also surfaces the ID-reference constraint that governs showHideLogic values.

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 ('Add one custom field') and constrains scope to an existing checkout page, form, or event. That scope constraint cleanly separates it from create_checkout_page/create_form/create_event and from update_field/delete_field siblings.

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

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

Explicitly routes one case to an alternative ('to add fields on a new page, pass fields to the create tool instead'), which is real when-to-use guidance. It does not, however, mention update_field or delete_field as alternatives for modifying/removing an existing field, so it falls short of full when/when-not coverage.

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, and openWorldHint=true, so the safety profile is covered. The description adds useful operational context — the post-creation workflow and the mandate to call add_to_website next — but says nothing about auth requirements, rate limits, or side effects of creation beyond what annotations imply.

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

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

Front-loaded with purpose and conditional usage, then workflow. The bulleted list of return fields (data.id, data.name, data.hostedUrl, data.dashboardUrl) is partially redundant with the output schema, which is the only real slack in an otherwise tight description.

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

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

Given a create tool with 38 params, 1 required, a rich schema, and an output schema, the description supplies what the structured fields cannot: the minimal-vs-rich request heuristic and the mandatory next-step routing to add_to_website. Nothing essential 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?

Schema coverage is 92%, so the baseline is 3. The description goes beyond the schema by telling the agent to use themeOverrides/hostedLayoutType for design and labels and to consult list_theme_properties and list_themes, which is real navigational value for the most complicated optional 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?

The description opens with a specific verb+resource+domain: 'Create a new form page for lead capture or submissions.' That cleanly distinguishes it from sibling tools like create_checkout_page, create_event, and create_booking, and an agent can pick it without opening the schema.

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

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

It gives strong positive guidance ('use this tool when a merchant wants to publish a form...', 'Prefer a minimal request when the user is vague, and only add optional fields...when requested') and calls out related tools (list_theme_properties, list_themes, add_to_website). It does not explicitly state when NOT to use it versus create_checkout_page/create_event, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=false and readOnlyHint=false. The description adds real behavioral context beyond that: the default-replacement side effect ('Only one tax rate can be the default at a time. Setting a new default replaces the previous one'), which explains WHY a create tool is flagged destructive. It does not discuss response shape, but the output schema covers that.

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

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

Front-loaded one-line purpose immediately followed by routing guidance, then bolded sub-sections for inclusive/exclusive, default, and the Stripe Tax distinction. Every section earns its place with no redundancy.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers usage, the inclusive/exclusive semantics, and the default-replacement side effect, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema with a worked example ($100 with 20% inclusive tax = $83.33 + $16.67) and the default-rate selection behavior, extending the terse schema descriptions.

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

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

States a specific verb+resource ('Create a fixed tax rate for use on checkout pages') and the effect on the account. An agent can immediately tell this apart from read-only siblings like list_tax_rates.

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

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

Explicitly states when to use it (merchant wants a fixed percentage VAT/GST/Sales Tax on fixed-mode pages) and when NOT to, routing the agent to `tax.mode: "stripe"` for dynamic/address-based tax instead. Clear positive and negative 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 only declare the basic safety profile (non-readonly, non-destructive, closed-world). The description goes well beyond that: the baseThemeId copy includes order bump styling that only the dashboard can change, a copy of a built-in theme does not inherit the store's brand color unless tokens.colorPrimary is set, and omitted variable keys retain their values while null resets them. These are non-obvious side effects an agent could not infer from any structured field.

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

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

Three sentences, zero filler, front-loaded with the core action and then building outward to prerequisites and application. Every sentence carries distinct, actionable information.

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

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

For a 3-parameter create tool with an output schema and full annotation coverage, the description supplies the creation workflow, dependency calls, and override semantics. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so name, variables and baseThemeId are already well documented in the schema. The description mostly restates that documentation (the list_theme_properties pointer appears verbatim in both places) rather than adding new parameter syntax or constraints. Baseline 3 is appropriate when the schema carries the detail.

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

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

States a specific verb and resource ("Create a reusable theme") and immediately situates it in a workflow with named siblings (list_themes, list_theme_properties, create/update_checkout_page). An agent can distinguish this from update_theme or get_theme without opening any schema.

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

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

Gives concrete when-and-how: use baseThemeId from list_themes to inherit a design, then set deltas in variables, and call list_theme_properties for supported keys. It also explains where the result gets applied. It stops short of distinguishing this tool from the sibling update_theme, so the alternative routing is incomplete.

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 and openWorldHint=true, so safety is covered. The description restates 'Mutating' and adds that it targets an *existing* event/group (via get_event), but says nothing about permissions, duplicate-name behavior, or what happens to the parent group. Reasonable added context against a low annotation bar, but not rich.

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 resource, then ID sourcing, then the alternative. 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?

For a 26-parameter mutation tool the description is thin: the availability/trigger-ticket relationship and the many display-option flags are never summarized. An output schema exists, so return values needn't be described, but the parameter surface is under-explained relative to its complexity.

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

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

Schema description coverage is only 15% across 26 parameters, so the schema left most fields undocumented. The description's enumeration 'name, price, capacity, sale window and display options' partially compensates by grouping parameters, but pricing, feeAmount, reference, availabilityBehavior, triggerTicketTypeId, quantity limits and the hide* flags get no explanation from either source.

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

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

States a specific verb+resource with scope: 'Add one ticket type to a ticket group on an existing event.' It explicitly distinguishes itself from create_event ('to create a new event with its tickets in one call, use create_event instead'), so an agent can separate it from the sibling without opening either schema.

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

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

Gives an explicit alternative (create_event) with the condition that selects it, and tells the agent to source the event and group IDs from get_event. It doesn't address modifying an existing type (update_ticket_type) or the archive/update siblings, so it falls just short of fully exhaustive routing.

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

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

Annotations only flag readOnly=false/openWorld=true/destructive=false; the description adds substantial non-obvious behavior: the signing secret is generated externally and never returned, custom headers cannot be set here, the receiving endpoint can't verify until the user copies the secret, and hard failure limits (10 webhooks, duplicate URL).

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

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

Front-loaded with purpose and the critical URL constraint, then operational caveats. All paragraphs carry real content, though the 'at the `dashboardUrl` in the response' clause is repeated near-verbatim, which is mild redundancy in an otherwise tight definition.

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 detail is unnecessary. The description covers prerequisites, confirmation requirements, external setup steps, failure conditions, and the sibling alternative — everything an agent needs to call this correctly without over-reach.

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

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

Schema description coverage is 100%, so the schema already documents url, name, and events thoroughly (including the full event enum and http-rejection rule). The description reinforces the URL requirement but adds little syntax or format detail beyond what the schema already provides; baseline 3 applies.

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

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

States a specific verb and resource ('Register an HTTPS endpoint that receives Checkout Page event notifications') and enumerates the event domains covered. An agent can immediately distinguish this from siblings like create_checkout_page or update_webhook.

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

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

Explicitly routes the agent: 'To point an existing webhook at a new URL, use `update_webhook` rather than registering a duplicate.' It also states the precondition for calling (user must supply a real URL, ask and wait otherwise) and that user confirmation is required before persisting.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description still adds real context: permanence/irreversibility and the non-obvious fact that existing submissions retain their answers. It does not cover permission requirements or error behavior, so it falls just short of fully rich behavioral disclosure.

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 zero filler: the destructive scope leads, then the data-retention nuance, then the safer alternative. Every sentence carries distinct information.

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

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

With an output schema present, return values need not be explained, and the description covers the remaining agent-facing needs: irreversibility, user confirmation, and the safer alternative path. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters (pageId, fieldId, pageType) are already documented in the schema, including how to obtain fieldId and which pageType to use. The description adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (one custom field) plus the exact scope of page types it applies to (checkout page, form, event). The contrast with update_field makes it easy to distinguish from the adjacent mutation sibling without opening either schema.

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

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

Explicitly says when to use this (permanent removal) versus when to use an alternative (update_field with hidden: true when the field should just stop showing). It also instructs the agent to confirm with the user first, which is actionable routing 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 destructiveHint=true and readOnlyHint=false, yet the description goes further by disclosing two concrete server-side failure modes (theme in use by pages, theme is store default), stating irreversibility, and requiring user confirmation. This is exactly the extra behavioral context annotations cannot carry.

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, then the failure conditions, then the safety instruction. No filler and no repetition of the title or annotations.

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

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

An output schema exists, so return values need no explanation; the description instead covers the things the schema cannot: preconditions, irreversibility, and the confirmation requirement. Complete for a single-parameter destructive 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?

Only one parameter (themeId) and schema description coverage is 100%, with the pattern and sourcing ('as returned by list or create') documented in the schema itself. The description adds no format or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Delete a theme') and adds scope ('you created'), which cleanly distinguishes it from create_theme, update_theme, and get_theme in the sibling list. An agent can identify the operation without opening the schema.

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

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

Gives explicit preconditions for when the call succeeds or fails (pages in use, default theme) and prescribes the remedy (move pages first) plus a user-confirmation step. It does not name a sibling alternative, but for a delete there is effectively none, so this is strong context without formal exclusions.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations by disclosing concrete consequences: deliveries stop immediately, the endpoint vanishes from list_webhooks, and delivery history is retained. It also flags irreversibility and a confirmation requirement, which is exactly the behavioral context an agent needs for a destructive mutation.

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 consequences, then the caution and the prerequisite. Every clause carries information; 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 so return values need no explanation, and the single required parameter is fully covered. The description supplies the destructive consequence model and the pre-call workflow, leaving no 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 100%, so the webhookId parameter, its 24-hex-char pattern, and its provenance ('as returned by create or list') are already documented. The description only reinforces 'by id' and points to list_webhooks, adding no format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb (Delete) and resource (webhook endpoint) scoped 'by id', clearly separating it from list_webhooks, get_webhook, create_webhook and update_webhook. An agent can identify the operation without opening the schema.

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

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

Gives explicit workflow guidance: confirm with the user before invoking, and use list_webhooks to resolve the id first. It names the alternative tool for id lookup, though it does not spell out explicit when-not conditions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, but the description goes well beyond them: it documents 404 error text, warns that capacity values are historical snapshots and must not be used for inventory math, explains the isComplimentary flag's status/amount semantics, and states that mutations (transfers, cancellations, refunds) are dashboard-only. That is exactly the extra context an agent needs.

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

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

Front-loaded with the core action, then layered constraints, edge cases, and example utterances. Despite its length, every block carries distinct decision-relevant content (routing, error behavior, snapshot caveat, complimentary semantics, read-only boundary) 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?

A read-only single-record fetch with full schema coverage, an output schema, and no nested objects needs little more; the description still covers error behavior and non-obvious field semantics. Nothing an agent needs to call this 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?

Schema description coverage is 100%, so both parameters are already documented, and the description's livemode and bookingId guidance largely restates the schema. It adds only marginal framing (e.g., that payment IDs are not retrievable here), so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Retrieve a single event booking by ID') and immediately scopes it to the seller's own Checkout Page account. It explicitly distinguishes itself from the two most confusable siblings, list_bookings and list_payments, so an agent can select it without opening a schema.

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

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

Gives explicit when-to-use routing: use list_bookings to discover an ID by email, name, event title, or order ID, and use list_payments for checkout payments. It also states the when-not case (this tool cannot read payments) and the failure condition (404 if the ID isn't owned by the authenticated seller).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: the exact 404 failure mode and message, and the fact that the returned configuration includes status (draft/published/archived), product, files, images, and redirect settings.

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

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

Front-loaded with the core action and usage condition in the first two sentences, then alternatives, then examples. The four example utterances are somewhat repetitive but each exercises a distinct intent (fetch, inspect settings, check status, inspect sub-resources), so they earn most of their space.

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-shape detail is unnecessary, and the description still covers the one thing the schema can't: the 404 error path. Nothing an agent needs to invoke this 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?

Schema description coverage is 100% and the single pageId parameter is already documented with its 24-char hex pattern and sourcing guidance, so the description's 'by ID' adds little. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Retrieve a single checkout page by ID') and immediately scopes it to an existing-resource lookup, which cleanly separates it from list_checkout_pages, create_checkout_page, and update_checkout_page in the sibling set.

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

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

Explicitly states when to use it ('when you already know the checkout page ID') and routes the agent elsewhere for the adjacent flow ('For create flows, use `create_checkout_page`'). It even covers the chained workflow of passing the id returned by creation into this tool.

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

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

Annotations already cover the read-only/non-destructive profile, and the description adds substantial context beyond them: the 404 error text for missing IDs, no pagination, the identity-only scope (no purchase history), the non-overlapping transaction tools, and that deletion requires human intervention in the dashboard.

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?

Well front-loaded with purpose and routing, but bloated and repetitive: the dashboard/portal edit path and the GDPR deletion requirement each appear twice (once in the body, once under 'Example customer support uses'). Multiple example sections restate the same guidance.

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

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

Given an output schema exists, return values needn't be explained, yet the description still covers the billing vs. shipping address distinction, identity-only scope, and routing to transaction tools. Nothing an agent needs 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?

Schema coverage is 100% with a documented pattern and the 'use list_customers first' hint already in the schema, so the description largely repeats the schema's ID semantics. Baseline 3 is appropriate since the schema does the heavy lifting for the single parameter.

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

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

States a specific verb and resource ('Retrieve a single customer by ID') and immediately scopes it ('without pagination', 'one customer record directly by ID'). It explicitly distinguishes itself from the sibling list_customers by clarifying that it is for when you already have the ID.

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

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

Names the alternative (list_customers) and the exact condition that selects it (discovering an ID by email/name), and adds cross-tool routing to list_payments/list_bookings/list_subscriptions with the customerId filter. It also states when-not behavior (ID not found returns 404).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the response includes the 'full configuration' and positions the call in a create/update workflow, but discloses no auth needs, rate limits, or freshness behavior beyond that.

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 purpose front-loaded, followed by the workflow context. No filler or redundancy.

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

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

For a single-entity getter with an output schema that carries the return shape, the description supplies the purpose, the id source, and the surrounding workflow. Nothing an agent needs to invoke 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?

Schema coverage is 100% and the single pageId parameter already documents its role, ID format, and example. The description adds no format or constraint detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (retrieve), resource (a single event page and its full configuration), and lookup key (by ID). This cleanly distinguishes it from list_events (plural) and create_event without needing the schema.

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

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

Explicitly ties usage to the workflow: pass an id returned by create_event for a direct lookup, or call it before a partial update with update_event. It names the related tools but never states the exclusion case (e.g. use list_events when you don't have an id), so it falls just short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds genuine behavioral context beyond that: the not-found error message and the kinds of state (draft/published/archived) and settings it exposes.

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

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

Front-loads the core purpose in one sentence, then usage, then error behavior. The four example uses are somewhat repetitive with the guidance above, costing a little efficiency, but each sentence still 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?

Output schema exists, so return values needn't be described. For a single-parameter read tool with full annotation coverage, the purpose, routing, error behavior, and ID sourcing are all covered.

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

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

Schema description coverage is 100% and the pageId pattern/description already document format and provenance. The description's only addition is naming `create_form` as a source of the ID, which is marginal beyond the schema.

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

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

States a specific verb (Retrieve) and resource (a single form by ID), and the phrase 'single form by ID' distinguishes it from list_forms and from the many other get_* siblings that target different resources.

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

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

Explicitly names the condition ('when you already know the form ID and want to inspect the current configuration'), routes create flows to `create_form`, and explains the post-creation lookup path. The 404 case is also 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 declare readOnlyHint=true and destructiveHint=false. The description goes beyond them by disclosing that each response signs a new invoiceUrl, that the link expires 1 hour after the response, and that it is safe to share with the buyer, plus livemode test-record behavior. It does not cover error modes or rate limits, but the added behavioral context is substantial.

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

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

Front-loads the core action, then layers usage routing and behavioral detail in short, purposeful sentences. Slightly dense with the URL-expiry tangent, but no sentence is wasted.

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

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

For a two-parameter read tool with a full output schema, the description covers routing, mode selection, and the key return field's behavior. An agent has everything needed to call it correctly; output-schema details need not be restated.

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

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

Schema description coverage is 100%, so the schema already documents both id and livemode. The description's mention of livemode: false for test-mode records largely duplicates the schema, so it sits at the baseline of 3.

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 ('Retrieve a single invoice by id') and clearly scopes it as a single-record fetch, distinguishing it from list_invoices and regenerate_invoice by name. An agent can route to it without opening any schema.

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

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

Explicitly tells the agent to use list_invoices first to discover an id (by customer, invoice number, PO number, or chargeId), and names regenerate_invoice as the alternative for rebuilding the PDF. Both the when-to-use and the when-to-use-something-else conditions are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description goes further by disclosing the seller-scoped authorization ('for the authenticated seller'), the exact 404 behavior on a missing ID, and the test-mode-vs-live record distinction, all genuine behavioral context beyond the annotations.

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

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

Front-loaded with the core operation, then routing guidance, then failure/behavior notes, then concrete examples. The read-only statement is partly redundant with readOnlyHint but is a short, high-value reinforcement for a retrieval tool rather than 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?

An output schema exists, so return-value explanation is rightly omitted. For a single-record getter, the description covers purpose, routing to siblings, auth scoping, error behavior, and mode switching — nothing an agent needs 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?

Schema description coverage is 100%, so both parameters (paymentId, livemode) are already fully documented in the schema, which sets the baseline at 3. The description restates the livemode:false test-mode behavior and the ID-discovery hint, adding reinforcement but no syntax or format details the schema lacks.

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 ('Retrieve a single payment by ID') and immediately scopes it to the Checkout Page account. It explicitly distinguishes itself from the record types an agent might confuse it with (bookings vs. payments), which is exactly the differentiation needed among 50+ siblings.

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

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

It names the alternatives and the conditions selecting them: use `list_payments` first to discover an ID by email/name/product/order, and use `list_bookings` for event bookings. It even states the failure mode (404 'Payment not found') and where mutations must happen instead (the dashboard).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description's 'Read-only' simply restates that. The list of included sub-resources (prices, variants, stock, tax, file settings) adds some scope context, but nothing about permissions, error behavior, or data staleness is disclosed, which is acceptable given the lower bar set by 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 compact sentences, front-loaded with the action and scope, followed by the one piece of operational guidance an agent needs (where to get the ID). No filler or redundant 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?

With a fully covered single-parameter schema, an output schema covering return values, and annotations covering the safety profile, the description supplies everything essential for correct invocation. Only auth/permission context and any error semantics are absent, which are minor gaps for a simple read tool.

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

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

Schema description coverage is 100% and the single parameter already documents both the format pattern and the provenance of the ID. The description merely echoes the same ID-source guidance, adding no syntax or filtering detail beyond the schema, so the baseline of 3 applies.

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

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

Specific verb (Retrieve) plus resource (a single product by ID) with an explicit enumeration of the returned sub-resources (prices, variants, stock, tax, file settings). The 'single product by ID' + 'Read-only' framing clearly separates it from update_product and the get_* siblings that target other entities.

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 tells the agent where the required productId comes from (data.product.id on get_checkout_page), which is practical usage guidance. However, it never states when to reach for this tool versus other getters/updaters or what prerequisites exist, so usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint/destructiveHint, but the description adds behavior the annotations cannot: no pagination on the response, a specific 404 'Submission not found' failure mode, and the livemode toggle for test-mode records. The read-only constraint is restated with an actionable fallback for write requests, which is genuinely useful context.

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

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

Front-loaded with the core purpose, then layered with usage, error behavior, examples, and the read-only caveat. Well-structured, though the four example queries and the bolded read-only paragraph push it slightly beyond the minimum 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?

For a single-record getter with an output schema, an agent needs purpose, discovery path, test-mode handling, and failure semantics — all present. Return-value structure is properly delegated to the output schema, so nothing essential 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?

Schema coverage is 100%, so both parameters are already documented, making 3 the baseline. The description adds modest value by restating the livemode test-mode behavior and by tying the ID parameter to the discovery workflow, but it introduces no format or syntax detail the schema lacks.

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 — 'Retrieve a single form submission by ID from your Checkout Page account' — and immediately establishes scope (one record, by ID, no pagination). It is clearly distinguishable from the sibling `list_submissions`, which it names 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?

Tells the agent exactly when to use this versus the alternative: 'Use `list_submissions` first if you need to discover a submission ID by customer email, customer name, page, customer ID, or date range.' It also routes modification intents away from MCP toward the dashboard, so both the when and the when-not are 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, but the description adds real value: the 404 error behavior for unknown IDs, the livemode test-vs-live distinction, and the explicit statement that cancellation/refunds must happen elsewhere. It stops short of describing pagination or caching, though neither is relevant for a by-ID fetch.

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

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

Front-loaded with the core action, followed by routing guidance, error semantics and examples. The four example utterances are slightly more than needed but each illustrates a distinct use, so the cost is low.

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

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

A read-only lookup with an output schema needs little beyond routing and error behavior, both of which are present. An agent has everything required to select and invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description's 'Pass livemode: false to read test-mode records' largely repeats the schema text, though the example uses add mild illustrative value. Baseline 3 applies.

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

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

States a specific verb and resource: 'Retrieve a single subscription by ID from your Checkout Page account.' The singular 'single' paired with the ID requirement clearly distinguishes it from list_subscriptions and get_subscription_payment.

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

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

Explicitly routes the agent: use list_subscriptions to discover an ID, use prepare_subscription_cancellation for cancellation context, and perform cancellation/refunds in the dashboard. Both when-to-use and when-not-to-use are 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 declare readOnlyHint=true and destructiveHint=false, so the description isn't carrying the safety burden — yet it still adds real behavior: a 404 with the exact message when the ID doesn't exist for the authenticated seller, test-mode access via livemode:false, and the constraint that refunds cannot be done here (dashboard only). It doesn't discuss rate limits or auth requirements beyond the seller scoping, keeping it just short of a 5.

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

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

Front-loaded with purpose and scope, then grouped under clear bold headers for error behavior, status fields, and examples. It is on the long side and the three example utterances plus the restated read-only line are marginal, but nearly every sentence carries distinct information.

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

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

An output schema exists, so return values need no explanation, yet the description still flags the two independent status fields (paymentStatus vs. invoiceStatus) and that both must be checked when answering 'did this payment go through?' — exactly the kind of domain trap an agent would otherwise 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?

Schema description coverage is 100%, so both parameters are already documented in the schema, including the exact livemode test-mode semantics and the 'not the subscription it belongs to' warning on subscriptionPaymentId. The description largely repeats this, so the baseline 3 applies; it adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Retrieve a single subscription payment by ID') and immediately carves out scope: 'one charge within a subscription's billing cycle, not the subscription itself.' An agent can distinguish it from get_subscription and get_payment without opening any schema.

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

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

Explicitly routes to alternatives by name and condition: use `list_subscription_payments` first to discover an ID (filtered by `subscriptionId`), and use `get_subscription` for subscription-level status/schedule/next-billing-date. Both the when-to-use and the when-not-to-use cases are 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description's 'Read-only' merely restates that. It does add that the returned theme includes its design settings via `variables`, but says nothing about auth needs, error behavior, or whether a missing id returns empty vs. an error.

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, resource and payload front-loaded, no filler. Minor waste in the trailing 'Read-only.' which duplicates the readOnlyHint annotation.

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 single-param read tool with an output schema, the description covers what an agent needs to invoke it: what is fetched and what it contains. The absence of sibling differentiation and error/id-origin context keeps it from a 5.

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

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

Only one parameter and schema coverage is 100% (themeId documented in the schema, including the 24-hex-char pattern and origin 'as returned by list or create'). The description adds no meaning beyond the schema, so the baseline 3 for schema-carried params is correct.

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 (Fetch) and resource (one theme by id) and names the key payload field (`variables` = design settings). It implicitly separates itself from list_themes and list_theme_properties, but never explicitly contrasts with those siblings, so it falls just short of a 5.

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

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

There is no when-to-use guidance: nothing tells the agent to prefer this over list_themes or list_theme_properties, nor that a theme id must come from list_themes/create_theme (that hint lives in the schema, not the description). Usage is only inferable from the phrase 'by id'.

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?

Goes well beyond the readOnlyHint annotation by disclosing the redaction contract: the signing secret is never returned, custom header values appear as `[hidden]`, and headers must be managed via the returned dashboardUrl. This is exactly the behavioral context an agent needs before calling.

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 what is returned, then the redaction behavior, then the prerequisite and safety note. 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 no elaboration, yet the description still covers the non-obvious output aspects (redaction, dashboardUrl) and the id prerequisite. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single webhookId parameter is fully documented with its pattern and origin. The description adds no format or syntax detail beyond what the schema already provides, so the baseline 3 applies.

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

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

Specific verb+resource ('Fetch one webhook by id') with the returned fields enumerated (URL, subscribed events, status, delivery counters). It is clearly distinguishable from the sibling list_webhooks and from create/update/delete_webhook.

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

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

Explicitly routes the agent to list_webhooks to obtain the id, and states the operation is read-only. It gives clear context but does not state any condition under which 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 read-only/non-destructive, and the description richly extends them: the tool cannot transfer tickets, cancel, or refund; refund metadata limitations; a historical cutoff after which refund data may be incomplete; instrument-capacity snapshots that do not reflect live inventory; and explicit 'unanswerable from this tool' surfaces. This is well beyond what the annotations convey.

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

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

Front-loaded and organized under bold section headers, with each block (money units, status fields, name fields, dates, limits, limitations, routing) earning its place. It is nonetheless very long, and the support examples repeat the 'orderId lookup' pattern several times, so it is not fully free of redundancy.

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

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

For a 15-parameter filtered list tool this is thorough: it covers money units, dual status semantics, name field precedence, pagination limits, known data gaps, and cross-tool routing. Nothing an agent needs to call it correctly or interpret the response is missing, even though an output schema already exists.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantic value the schema lacks: the independence of status vs orderStatus (with worked combined-state examples), the meaning of isComplimentary vs amountPaid=0, UTC-only date filter rules, and task-appropriate limit guidance. This materially reduces misuse of the filters.

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?

Opens with a specific verb+resource+scope: 'Retrieve a paginated list of event bookings processed through your Checkout Page account.' It immediately distinguishes itself from list_payments and list_subscriptions by naming those siblings in the cross-tool routing section ('Payments, bookings, and subscriptions are separate record sets').

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 when-to-use guidance via concrete support scenarios (registration check, order lookup, refund chase, failed booking) and explicit routing alternatives: try list_payments/list_subscriptions when an order lookup here returns 0 results, list_customers/get_customer for profile data, and all three for full history. Exclusions are stated, not inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful behavioral details beyond annotations: archived pages are excluded by default, results are newest-first, full configuration/product/fields are returned, and forms/events are separate. It does not mention pagination or rate limits, but with annotations carrying the safety profile this is solid.

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

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

Front-loaded with the core verb and resource, then scoping, defaults, and sibling routing. Four sentences, each carrying distinct operational value, with no redundant filler.

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

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

For a list tool with a rich input schema and an output schema, the description covers the key agent needs: what is listed, ordering, default filtering, safety profile, and how to route to sibling tools for IDs or other page types. Return-value details are appropriately left to the output 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 100%, so the schema already documents limit, search, status, testmode, ending_before and starting_after in detail. The description adds only one parameter-related semantic: archived pages are left out unless you filter by status. That is helpful but does not materially extend the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the checkout pages'), the scope ('on the Checkout Page account'), ordering ('newest first'), and returned fields ('full configuration, product and fields'). It also distinguishes itself from get_checkout_page/update_checkout_page and from list_forms/list_events, so an agent can select it without opening schemas.

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

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

Explicitly says how to find a page id for get_checkout_page and update_checkout_page, clarifies that forms and events are separate page types served by list_forms and list_events, and explains the archived-pages default unless status is filtered. When-to-use and alternatives are both 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?

Goes well beyond the readOnlyHint annotation: soft-deleted coupons are returned and not filtered out, there is no single 'active' flag (deleted/redeemBy/timesRedeemed+maxRedemptions must be checked together), sorting is newest-first, pageIds/ticketTypeIds are IDs not resolved names, and discount fields are immutable after creation. This is exactly the operating context an agent needs.

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?

Bold mini-headers (Reading a coupon, Scoping, No filters, etc.) keep a long description scannable, and the most important constraint (only ID-discovery path) is front-loaded. Some pagination and limit details are restated from the schema, which is the only minor redundancy.

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

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

An output schema exists, so return mechanics need not be explained, yet the description still decodes coupon field semantics (percentOff vs amountOff+currency, duration variants, redemption counters) and liveness rules — everything an agent needs to interpret results and act correctly.

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

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

Schema description coverage is 100%, so limit, search, starting_after, and ending_before are already fully documented in the schema, including the max-100/default-10 and mutual-exclusion rules the description repeats. The description adds only a small increment: framing search as a duplicate-check and reiterating the lack of other filters. Baseline 3 applies.

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

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

Opens with a specific verb+resource ('Retrieve a paginated list of discount coupons on your Checkout Page account') and immediately distinguishes itself from siblings by noting it is 'the only way to discover a coupon ID' and naming create_coupon/update_coupon as the alternatives. An agent can route without opening any schema.

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

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

Explicit when-to-use: it is the sole ID-discovery path, it feeds update_coupon, and its search answers 'is there already a coupon for X?' before calling create_coupon. It also states when-not: no server-side filtering by deleted/expiry/redemption/scope, so page through instead. Nothing is left 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?

Annotations already establish readOnly/destructive/openWorld, so the bar is lower, yet the description adds substantially more: newest-first ordering, cursor pagination semantics with mutual exclusivity, no server-side aggregation, companyName not being searchable, UTC-only date handling, and human intervention for GDPR/deletion. This is rich behavioral context beyond the annotation set.

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

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

Front-loaded well and broken into labelled sections, but it is substantially padded: the email-delivery disclaimer is repeated three times, GDPR/human-intervention twice, and the 'customer records contain no purchase data' point recurs throughout. The two example blocks partially duplicate the routing section already stated above them.

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 everything else an agent needs is present: routing to sibling tools, pagination behavior, search limitations, date format, and escalation paths for deletion requests. Nothing material 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?

Schema coverage is 100%, so the baseline is 3 and the schema already documents limit bounds, cursor exclusivity, and the Z-suffixed date pattern. The description still adds value the schema doesn't carry — the hard rule that dates must be UTC with Z and never local offsets, and the caveat that `search` matches name/email but will return 0 for companyName.

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

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

States a specific verb+resource with scope ('paginated list of customers') and immediately delimits what a customer record is NOT (no purchase history, no transaction amounts, no subscription status). This cleanly separates it from get_customer and from the transaction list tools.

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

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

Explicit when-to-use (profile data, obtaining an id for filtering), when-not-to-use (order number given → go to transaction tools), and a named cross-tool routing block pointing at list_payments/list_bookings/list_subscriptions. The two-step search→id→filter pattern is spelled out with the conditions that motivate it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, the fact that archived events are excluded by default, and that each record carries nested configuration (ticketGroups, ticketTypes, fields). It stops short of saying anything about result caps or cursor mechanics for the list as a whole.

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 tightly packed sentences, front-loaded with the verb, resource and ordering before the routing guidance. No filler and no repetition of schema-level parameter documentation.

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 explanation is unnecessary, and the description still summarizes what each record contains. Combined with complete schema coverage and explicit sibling routing, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100%, with limit, search, status, testmode and both cursors fully documented in the schema itself. The description's only added parameter-relevant content is the archived-by-default behavior, which the status schema description already states verbatim. Baseline 3 is appropriate when the schema does the heavy lifting.

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 the event pages on the Checkout Page account') plus scope details (newest first, full configuration including ticket groups/types/fields). It explicitly disambiguates from the similarly-named siblings by noting that checkout pages and forms are separate page types.

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 the downstream use case clearly: 'this is how to find an event id for get_event, update_event, list_bookings and list_tickets'. It also names the two alternative tools for other page types and explains the archived-status default, so when-to-use and when-not-to-use are both 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 declare readOnlyHint/destructiveHint=false, and the description reinforces read-only. It adds genuinely useful behavior beyond annotations: newest-first ordering, inclusion of full configuration/fields/files, and that archived forms are silently excluded unless explicitly requested.

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

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

Four tight sentences, front-loaded with what is returned, followed by the archived caveat, the ID-discovery purpose, and the sibling disambiguation. Every sentence carries actionable information with no 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 the description still covers payload contents, ordering, default filtering, the primary downstream use (finding a form id) and sibling routing. Nothing an agent needs to call this 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?

Schema description coverage is 100% and already documents limit, search, status, testmode and both cursors in detail, so the baseline is 3. The description's param-relevant claims (archived default exclusion, no field/file/slug filtering) largely restate what the schema already says, adding little beyond the schema text.

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 the form pages on the Checkout Page account') and even describes the payload shape ('full configuration, fields and files') and ordering ('newest first'). It explicitly distinguishes itself from sibling page types by naming list_checkout_pages and list_events.

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

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

Gives explicit routing: 'this is how to find a form id for get_form, update_form and list_submissions', plus clear when-not guidance ('Checkout pages and events are separate page types: use list_checkout_pages and list_events'). The archived-default behavior tells the agent when it must pass a status filter.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds genuinely new behavior: the invoiceUrl is a signed, shareable link that expires 1 hour after the response, and it reiterates the read-only nature. That expiry/shareability detail is not derivable from annotations or schema.

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

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

Four sentences, front-loaded with purpose and scope, followed by the livemode hint, the invoiceUrl caveat, and sibling routing. Every sentence carries information, though it is slightly denser than strictly necessary.

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 11 optional parameters fully documented in the schema, an output schema present, and annotations covering safety, the description supplies the remaining operational context an agent needs: test-mode switching, link expiry, and where to look for broader purchase history. Nothing material 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?

Schema description coverage is 100%, so every parameter is already documented in the schema, including the search routing rules and UTC date-time constraints. The description only restates the livemode usage hint and references invoiceUrl (a response field, not a parameter), adding little beyond the structured data. Baseline 3 applies.

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

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

The first sentence states a precise verb and resource with scope: invoices generated from payments (Charges) on the Checkout Page account. It also names the sibling list tools that cover adjacent purchase-history data, so an agent can distinguish it without opening a schema.

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

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

It gives concrete routing guidance: use livemode:false for test-mode records, and query list_payments/list_subscriptions/list_subscription_payments/list_bookings for full purchase history. It stops short of an explicit 'when not to use this' (e.g., use get_invoice for a single known invoice), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond them: money returned in smallest currency unit, refund metadata overwritten to only the latest action, the pre-2026-01-22 refund-metadata gap, paymentError persisting after a successful retry, and no email-delivery or download-URL visibility. These are non-obvious behavioral traits an agent could not infer from the schema.

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

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

The high-value material is front-loaded, but the text is very long and repeats itself: order lookup fallback to list_bookings/list_subscriptions appears twice, full-customer-history guidance appears twice, and receipt/refund advice is duplicated across the scenario list and the data-limitations list. Useful, but several paragraphs do not earn their place a second time.

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, yet the description still covers the field semantics an agent must interpret (customerName vs billing.name vs shipping.name vs fields, invoiceId, refund fields). Given the 15-parameter surface and the operational limitations, this is complete enough to call the tool correctly and interpret results honestly.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description genuinely adds meaning: UTC-only timestamps with a Z suffix, sorting (newest-first), pagination cursor semantics and the starting_after/ending_before mutual exclusion, plus guidance to read total for counts and to filter before counting. It stops short of documenting every filter's semantics, but adds real value over the schema.

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

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

Opens with a specific verb and resource ('Retrieve a paginated list of payments') and immediately scopes it to the Checkout Page account. It explicitly distinguishes itself from sibling transaction tools ('For questions about a customer's full purchase history query the other transaction tools') and from get_payment, so an agent can route without opening a schema.

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

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

Provides explicit when-to-use guidance via worked support scenarios, names concrete alternatives (list_bookings, list_subscriptions, list_customers, get_customer, get_invoice), and states the key exclusion: it is read-only and cannot process refunds, resend receipts, or update details. The cross-tool routing section clarifies that records do not overlap between tools, removing ambiguity about double-counting.

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