TicketSpice MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description still earns credit by explaining the real-world consequence — the coupon goes live and is immediately redeemable — and by spelling out the duplicate-creation risk rather than merely restating the flag, plus citing POST /coupons.

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

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

Three tight sentences, front-loaded with the write marker and the highest-risk fact (live, immediately redeemable). Every clause carries information: scope, side effect, option summary, and idempotence caveat.

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

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

For a 9-parameter mutating tool with full schema coverage and annotations, the description covers creation semantics, constraints and side effects well. The one gap is the return value: with no output schema, an agent gets no hint that a coupon/ID comes back, which matters for chaining a follow-up get_coupon.

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; the description adds value by grouping the optional axes ("limited to one form, to a number of uses, and to an expiry date") and by tying discount_type to discount_value as a single "fixed amount or percent" decision. It does not add format details for expires or the -1/unlimited convention, but the schema handles those.

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 an explicit verb+resource ("create a discount coupon") bounded to the live TicketSpice account, and the "WRITE:" prefix plus the effect ("can be redeemed by ticket buyers right away") distinguishes it instantly from the get_/list_/delete_coupon siblings.

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

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

The "WRITE:" marker and the non-idempotence warning ("calling it twice creates two coupons") give an agent clear operational context for when this applies versus the read-only coupon siblings. It stops short of explicitly naming an alternative or a verification step (e.g., list_coupons after creation), so it is strong but not complete.

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, but the description adds concrete consequences the agent can't get from structured fields: codes stop working immediately, operation is irreversible, and user approval is a hard prerequisite. It also discloses the underlying GET-then-DELETE sequence, which explains latency/validation behavior.

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

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

Two dense sentences with the destructive warning front-loaded and the approval workflow immediately after. The trailing 'GET /coupons/{id}, then DELETE /coupons/{id}' is implementation-level noise that doesn't help the agent decide or invoke, slightly diluting 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?

For a destructive two-parameter mutation with no output schema, the description covers everything needed: what is destroyed, irreversibility, the approval gate, the required confirm flag, and the read-before-write sibling. 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% and the schema already documents confirm as a const-true approval flag and coupon_id as a positive integer. The description reinforces confirm: true but adds no new format or semantic detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource ('permanently delete a coupon'), names the target system scope ('live TicketSpice account'), and flags it as WRITE. Clearly distinguishable from its read-only siblings like ticketspice_get_coupon and ticketspice_list_coupons.

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 prescribes the precondition sequence: fetch with ticketspice_get_coupon, obtain user approval, then call with confirm: true. This names the sibling to use first and the gate that selects invocation, leaving nothing 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing the returned content (discounts, codes, availability, redeemed counts) despite there being no output schema, though it omits any auth or error semantics.

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, zero filler, with the resource scope front-loaded and the endpoint tacked on at the end. Every clause carries information.

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

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

For a single-param read tool with no output schema, the description supplies enough: what entity is fetched and which fields it carries. Annotations cover safety, and the schema covers the parameter, 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% and the single coupon_id parameter is fully documented in the schema, including its provenance from ticketspice_list_coupons. The description adds nothing beyond 'by id', 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?

The description states a specific verb and resource ('One coupon by id') and enumerates the payload it returns (discounts, codes, availability, redeemed counts), which separates it from ticketspice_list_coupons. It never names the sibling explicitly, so differentiation is implied by 'one/by id' rather than stated.

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

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

Usage is only implied: fetching a single coupon by id, with the schema noting the id comes from ticketspice_list_coupons. There is no explicit when-to-use-vs-list guidance or note about behavior when the id does not exist.

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=true, so the safety profile is covered. The description contributes the underlying endpoint and the returned field set, but says nothing about not-found behavior, auth, or pagination (not applicable here).

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

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

Two short sentences, front-loaded with what the tool returns, then the endpoint. The raw path is marginal value but does help agents map to the API; nothing is bloated.

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

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

With no output schema, the description usefully lists the returned fields so the agent knows what it gets back. For a one-parameter read tool with full annotation coverage, this is close to sufficient; only error/not-found semantics are 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 parameter already documents its provenance (from list_customers or an order's customerId). The description only restates "by id", adding no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (fetch one customer record by id) and enumerates what comes back: email, billing details, transaction total. This distinguishes it implicitly from ticketspice_list_customers, though it never names that 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?

"by id" implies single-record lookup and hence a different use case than the list tool, but there is no explicit when-to-use / when-not guidance. The useful provenance hint (id from list_customers or an order's customerId) lives only in the schema, not the description.

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=true, so the safety profile is covered. The description usefully discloses the return payload shape, but says nothing about auth requirements, 404 behavior for unknown ids, or rate limits. With annotations carrying safety, a 3 fits.

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 fragments, both front-loaded with the most decision-relevant information: identity/scope first, returned fields second, endpoint last. Nothing is wasted and nothing needs re-reading.

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

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

With no output schema, the description correctly compensates by listing the returned attributes, which is exactly what an agent needs to decide whether to call it. It falls short of complete only in omitting error/permission expectations for a public open-world API read.

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 form_id property already states 'from ticketspice_list_forms', so the single parameter is fully documented in structured data. The description adds only the 'by id' framing, which repeats the schema. Baseline 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 resource ('One form by id') and enumerates what comes back (name, status, accounting reference, time zone, field layout), plus the underlying endpoint. The singular scope implicitly separates it from ticketspice_list_forms, though no sibling is named outright.

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

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

There is no explicit when-to-use or when-not-to-use language. An agent must infer that this is the single-record counterpart to ticketspice_list_forms and has no guidance on how it differs from ticketspice_get_form_inventory, even though that sibling is the closest ambiguity.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds value beyond that by enumerating the returned fields (path, name, sold, remaining) despite there being no output schema, and by pinning the underlying endpoint GET /forms/{id}/inventory. It does not mention pagination, permissions, or behavior when a form has no limited-quantity items.

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

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

Two compact sentences with the payload description front-loaded and the endpoint as supporting detail. Nearly every token earns its place, though the phrasing is telegraphic and lacks an explicit action verb.

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

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

For a one-parameter read tool with no output schema, the description does the important remaining work: it lists the fields the caller receives and the endpoint shape. Only edge-case behavior (empty inventory, paging) is absent, which is minor here.

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% for the single parameter (form_id, with a positive-integer bound), so the schema carries the semantics. The description only reinforces that the id is a form id via the endpoint path '/forms/{id}/inventory'; it adds no format or validity detail beyond that.

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

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

The description names a specific resource (a form's inventory items) and narrows it with a clarifying gloss, 'limited-quantity items', plus the exact fields returned. No sibling tool deals with inventory, so disambiguation is implicit rather than stated, and the verb is carried by the name/title rather than the description itself.

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

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

Usage is implied: call this to check sold/remaining counts for limited-quantity ticket types on a given form. There is no explicit when-to-use statement, no exclusions, and no reference to alternatives such as ticketspice_get_form or ticketspice_list_tickets for quantity data.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds real context: the exact response contents, the opt-in embedding semantics of the two flags, and the underlying endpoint GET /search/orders/{id}. It does not cover error behavior for an unknown id, but the expansion semantics are the more valuable 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?

Two tight sentences: what you get first, optional expansions second, endpoint last. No filler and nothing that could be cut without losing 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 read-only fetch with full schema coverage and no output schema, the description covers resource, payload shape and expansion behavior adequately. The only minor omission is what happens when the id does not exist, which is secondary for this tool class.

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 meaning beyond the schema: it explains that include_transactions pulls payments including charges and refunds, which the schema does not state, and frames both flags as 'embed' expansions of the parent order.

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

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

The description names a specific verb and resource ('one order by id') and enumerates what the response contains: billing details, event, totals and status. It is clearly distinguishable from get_customer, get_ticket and get_transaction by resource, though it never explicitly contrasts with list_orders.

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

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

Usage is only implied: fetch a single order when you already have an id (the schema notes ids come from ticketspice_list_orders). There is no explicit statement of when to prefer this over ticketspice_list_orders or the per-entity getters, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered and the bar is lower. The description adds useful scope by listing exactly which record fields come back, but says nothing about failure behavior (e.g. invalid or unknown id) or access constraints.

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 clauses: the field inventory first, then the underlying endpoint. Every token carries information and 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?

With no output schema, the enumerated field list is essential and it is provided, covering what the agent will receive. Only error/empty-result behavior is left unstated, which is a minor gap for a single read-by-id tool.

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

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

Schema coverage is 100% and the single ticket_id parameter is already documented with its source tool. The description adds no format, range, or retrieval details beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('One ticket by id') and enumerates the returned attributes, so an agent knows exactly what this retrieves. It doesn't differentiate from siblings like ticketspice_list_tickets or ticketspice_get_order, leaving the single-vs-list distinction implicit.

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

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

Usage is only implied: 'by id' suggests fetching a known ticket, and the schema hints at obtaining ids from ticketspice_list_tickets. The description itself never says when to use this versus listing or when an id is unavailable.

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, openWorldHint=true, so the safety profile is covered. The description usefully enumerates what comes back (amounts, masked card, gateway message, status), which substitutes for the absent output schema, but says nothing about behavior on a missing/invalid id or any auth/rate-limit constraints.

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 fragments, front-loaded with the returned field set and ending with the endpoint for agents that reason about the API surface. No wasted words.

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

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

For a one-parameter read with no output schema, the description carries the return-value burden adequately by listing returned fields. Only the error/not-found behavior is unaddressed, a minor gap.

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

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

Schema coverage is 100% and the single parameter already documents its provenance and positivity constraint. The description adds only 'by id', so it neither needs to nor does add much beyond the schema — baseline 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 ('one transaction by id') plus the fields returned and the underlying endpoint, so it is clearly distinct from ticketspice_list_transactions. It does not name the sibling explicitly, but 'by id' plus the schema's cross-reference makes the distinction obvious.

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

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

Usage is only implied: fetch a single transaction when an id is known. The when-not condition (use the list tool to search/browse) is left to the reader, though the schema's 'from ticketspice_list_transactions' hints at the workflow.

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, open-world, so the safety bar is low. The description earns credit by naming the returned attributes (discounts, codes, availability, redeemed count, expiry) and the underlying endpoints — valuable since no output schema exists. Pagination behavior is left to 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?

Three short sentences with zero filler; scope comes first, then return contents, then endpoint detail. Nothing repeats the name or title verbatim.

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 five fully documented optional params, read-only annotations, and no output schema, the description covers scope and returns adequately. It omits any mention of pagination or result limits, though starting_after and limit in the schema largely compensate.

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 every parameter including the form_id scope rule and the code/form_id interaction is already documented. The description restates the form_id scoping but adds no syntax, defaults, or limits beyond the schema; baseline 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?

Specific verb plus resource ('List TicketSpice coupons') with an explicit two-mode scope: account-wide, or form-scoped when form_id is given. The endpoint paths reinforce the distinction from get_coupon and the other coupon 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?

Clearly states the condition that selects each mode ('only those of one form when form_id is given', omit for global). No explicit exclusion or pointer to a sibling for single-coupon retrieval, but the list-vs-get split is unambiguous.

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

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

Annotations already cover read-only/non-destructive/open-world, and the description adds genuinely non-obvious behavior: newly created customers may take up to 5 minutes to appear in results. It also exposes the underlying endpoint (GET /search/customers). It stops short of describing pagination mechanics, which reduces 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?

Two tightly packed sentences: identity and payload first, then filtering, then the freshness caveat, then the endpoint. No filler and nothing buried.

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

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

With no output schema, the enumeration of returned fields does real work, and the freshness caveat covers the main surprise an agent would hit. The only gap is that pagination flow is left entirely to the schema's cursor field rather than being explained in the description.

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 one of the eight parameters is already documented, including the pagination cursor. The description only restates that filtering is by email or dates, adding no format or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List customer records (buyers)') and even enumerates the returned fields, so the agent knows exactly what comes back. It does not distinguish itself from the sibling ticketspice_get_customer for single-record lookups, which keeps it from 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?

'Filter by email or dates' implies when the tool is useful, but there is no explicit statement of when to prefer ticketspice_get_customer (or another sibling) over this listing call, and no exclusions are given.

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=true, so safety is covered; the description adds value by enumerating the returned fields and the possible status values (open, closed, scheduled, archived), which is the kind of read-shape detail annotations cannot convey. It does not discuss the cursor pagination contract or rate limits, but the schema documents the cursor.

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 compact, front-loaded clauses: what it lists and returns, how the output is used, and the endpoint. No filler and no restatement of the title.

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

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

With 7 optional params and no output schema, the description compensates by naming the fields returned and the status enum, and it points to the endpoint. The only gaps are that pagination and the filter parameters are left entirely to the schema; nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, including enum values for sort, limit bounds and the starting_after cursor contract, so the description has little left to explain. Its mention of created and updated dates loosely gestures at the date-range filters but adds no syntax or timezone guidance beyond the schema. Baseline 3 is appropriate here.

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

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

States a specific verb (List) and resource (the account's TicketSpice forms), and immediately disambiguates the vendor's jargon by equating 'forms' with 'ticketed events / order pages'. It also names the returned fields and the underlying endpoint (GET /forms), so an agent can separate it from the singular ticketspice_get_form 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 a concrete downstream reason to call it: 'Use the form ids to filter orders, tickets and transactions,' which tells the agent this is the discovery step before order/ticket listing. It stops short of explicitly naming alternatives (get_form for a single form) or stating when-not to use it, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's contribution beyond that is the returned field list and the existence of the GET /search/orders endpoint; it says nothing about pagination behavior, default result volume, or what happens when filters conflict — though the schema covers limit and the starting_after cursor.

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

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

Two sentences, front-loaded with the resource and its return shape, then the filters — no repetition of the title and nothing redundant. The trailing 'GET /search/orders' is the only low-value token, since the agent cannot use endpoint paths directly.

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 12-parameter read-only list tool with no output schema, the description usefully compensates by naming the returned fields (order number, billing name/address, form, total, currency, status), which the agent otherwise could not know. What remains thin is pagination guidance and default page size in prose, though both are fully documented in the schema.

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

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

Schema description coverage is 100% across all 12 parameters, and each parameter carries a precise description (including the cursor explanation and enum for sort), so the baseline of 3 applies. The description's parameter prose restates the schema's filter set ('event (form), status, buyer email, customer id, order number or dates') without adding format or edge-case semantics such as date string format.

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

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

The description uses a specific verb+resource ('List orders') and adds real definitional detail: one order per checkout, plus the exact fields returned and the filters available. It does not explicitly name a sibling like ticketspice_get_order as the alternative for a single order, so differentiation is implied by the 'list' framing rather than stated.

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

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

Enumerating the filterable dimensions (form, status, email, customer id, order number, dates) implicitly tells the agent when this tool is the right one, and 'newest or oldest first' hints at sort intent. However, there is no explicit when-to-use/when-not, and no pointer to ticketspice_get_order for single-record lookups, which is the most likely confusion given the sibling set.

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 safety profile is covered. The description adds real value by disclosing the full record shape (including fee/total breakdown, status, scan count and last scan time) and citing the underlying endpoint GET /search/tickets. It does not mention pagination behavior despite a cursor parameter, which is why it is 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?

Three sentences, front-loaded with the return shape, then filters, then use case and endpoint. The field enumeration is long but justified because there is no output schema. Nothing is wasted, though the sentence is dense.

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

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

With no output schema, the description correctly compensates by listing returned fields; with 14 optional parameters fully documented in the schema, it need not repeat them. The only missing element an agent might want is pagination guidance (limit + starting_after cursor), which appears only in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above baseline by grouping the filters into a coherent set and clarifying the vendor's 'event (form)' terminology linkage, which helps an agent map a user's event request onto form_id. It does not add format details or syntax for date parameters.

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

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

States a specific verb and resource ('List sold tickets') plus the crucial scope qualifier 'one record per ticket', which distinguishes it from the order-level sibling ticketspice_list_orders and from the single-record ticketspice_get_ticket. It then enumerates the returned fields, so an agent knows exactly what shape the result takes.

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 it for attendee lists and check-in status' gives concrete usage contexts, and the filter list implies the retrieval scenarios it covers. It stops short of naming exclusions or pointing to alternatives such as get_ticket for a single ticket or list_orders for order-level data.

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=true, so the safety profile is covered. The description adds only the endpoint path and the returned field set, with no note on pagination behavior, result caps, or default ordering beyond what the schema documents.

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

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

Two sentences, front-loaded with the resource, then the payload fields, then the filters, with zero filler. Slightly dense but every clause maps to a real capability.

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 16 optional parameters and no output schema, the description usefully enumerates what comes back (amount, currency, masked card, status, buyer email), which the schema cannot convey. It stops short of explaining pagination or default page size, both of which live only in the schema.

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

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

Schema description coverage is 100%, so every one of the 16 parameters is already documented, making 3 the baseline. The description's filter recap adds enum examples for type but also drifts slightly by naming 'donor', which does not match any parameter name (customer_id/email).

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 payment transactions (money movements)') and enumerates the returned fields and filterable dimensions, so the agent knows exactly what data this tool surfaces. It does not explicitly distinguish itself from the singular sibling ticketspice_get_transaction, which keeps it off 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?

Usage is implied rather than stated: 'Filter by type, method, form, order, donor or dates' tells the agent it is the search tool, but there is no explicit when-to-use versus ticketspice_get_transaction or when-to-prefer listing orders instead.

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