Ticketsauce MCP by usefulapi

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavior: replies are cached for an hour (an agent must know data may be stale) and counters are defined as tickets sold excluding refunded/voided. The endpoint path is also disclosed. Missing only error/not-found behavior, which is minor.

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 resource identity, then the payload delta, then the caching caveat. Nothing is redundant with the title and nothing is wasted.

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

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

With no output schema, the description does useful work by enumerating the extra fields returned relative to a list item. Combined with the caching note and fully documented params, an agent has enough to call it correctly; only the shape of nested photo/performer expansions is left implicit.

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 (event, photos, include_performers) are already documented. The description restates the id/slug duality but adds nothing about the optional photo/performer expansion flags, 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?

States a specific resource and retrieval mode ("One event by id or slug") and immediately clarifies the difference from the list siblings: "everything in the list plus summary and description... order_count and ticket_count." An agent can distinguish it from ticketsauce_list_events and ticketsauce_get_order 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?

The phrase "everything in the list plus..." gives clear context for when to pick single-event detail over listing, and the schema reference to ids "as returned by ticketsauce_list_events" reinforces the list-then-get flow. It does not explicitly state exclusions (e.g., that it is unnecessary if you already have the event from a list call), 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 cover readOnly, openWorld and non-destructive, so the bar is lower, yet the description adds real behavior: the response contains personal data, replies are cached for an hour (freshness caveat), and the underlying endpoint is GET /v2/order/{order_id}. It stops short of noting auth or rate-limit behavior, 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?

A single dense sentence front-loads the identity and payload, followed by two short high-value caveats (personal data, caching) and the endpoint. 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?

One-parameter read tool with no output schema; the description compensates by describing the returned fields, the personal-data sensitivity, and the one-hour cache, which is everything an agent needs to call and interpret 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% and the order_id property description already specifies UUID format and its source (ticketsauce_list_orders). The description merely restates 'by id' without adding format or provenance 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 and resource ('One order by id') and enumerates the payload (buyer details, totals, tickets with type, name, price, redeemed state, promo code). The singular 'one order by id' clearly contrasts with the sibling ticketsauce_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: an agent infers this is the single-record lookup versus list_orders, and the schema notes the id comes from ticketsauce_list_orders. The description itself offers no explicit when/when-not guidance or named alternatives.

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

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

Beyond the readOnly/openWorld annotations, it discloses two operationally important traits: the API documents no response fields so the reply is returned as-is, and replies are cached for 5 minutes (freshness matters for reconciliation). It stops short of describing reply ordering or cache invalidation, but adds real value over 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?

Three tight sentences front-loaded with the resource and use case, followed by paging, caching, and endpoint. Every clause carries information an agent would otherwise have to discover by trial.

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 explicitly warns that response fields are undocumented, and it covers pagination limits and cache lifetime — the three things an agent needs to call this correctly and interpret the reply.

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 page, per_page, and event_id are already documented. The description reinforces the pagination loop ('pass next_page' from the previous reply) but adds no syntax or 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?

Names the exact resource (ticket check-in ids of one event) and its purpose (door/scanning reconciliation), plus the underlying endpoint. It is unambiguous and cannot be confused with the sibling event/order tools, though it never explicitly contrasts itself with them.

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

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

The intent 'for door/scanning reconciliation' implies when this tool applies, and it gives a paging recipe (per_page up to 5000, then next_page). There is no explicit when-not guidance or mention of the sibling tools, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral fact the schema cannot express: 'The API has no paging for events,' which warns the agent that results arrive in one response. It also clarifies that dates are UTC, though it says nothing about auth or rate limits.

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 resource and the returned-field inventory, then filters, then a behavioral caveat and endpoint. Nothing is redundant and each sentence conveys 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 15 optional parameters and no output schema, the description usefully compensates by enumerating the response fields and flagging the absence of paging. It is close to complete; minor gaps are the interaction between active_only/inactive_only defaults and the sort parameters, which are left entirely to the schema.

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

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

Schema description coverage is 100% and each of the 15 params is documented in the schema itself, so the baseline is 3. The description mostly restates the filter categories rather than adding new meaning, with the one real addition being the UTC clarification for yyyy-mm-dd dates, which the schema pattern alone does not convey.

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 and resource ('List the events you own on Ticketsauce') and then enumerates the returned fields (id, name, slug, dates, venue, privacy, URLs), so the scope is unmistakable. It implicitly separates itself from ticketsauce_get_event by being the list operation and points to orders/check-ins as downstream consumers, but it never names the sibling tools outright.

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

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

It states concretely which filter dimensions exist (start/end/created dates, named phrases, organization, partner) and gives a workflow hint: 'Use the event id for orders and check-ins.' That tells the agent when to call this before list_orders or list_checkin_ids. There is no explicit when-not or named alternative such as get_event for a single record.

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 readOnly/destructive annotations, it discloses three things an agent would otherwise learn the hard way: the result set contains customers' PII, replies are cached for an hour (stale-data risk), and paging works by feeding next_page back with per_page capped at 500. Optional embeds (tickets, questionnaires, line-item fees) are also flagged as opt-in cost knobs.

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 a dense single paragraph, front-loaded with the resource and default sort, then filters, then paging and caching. The returned-field inventory is long but earns its place since there is no output schema; the only mild redundancy is restating the per_page 500 cap and next_page that the schema already defines.

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

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

For a 17-parameter, no-output-schema listing tool, the description supplies the return shape (ids, status, buyer contact data, totals, promo, ticket_count, paid date), pagination mechanics, caching behavior and a PII warning. An agent can call it correctly and knows what to expect back without opening 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 schema already documents every parameter including enums and ranges. The description adds some practical semantics (exact-match on email/last name, sort_dir desc for newest, next_page vs per_page) but mostly restates what the schema carries, so the baseline 3 applies; it could have clarified whether date filters combine conjunctively with q or the phrase filter.

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 opening phrase 'Orders of one event' gives a specific verb (list) and resource (orders scoped to a single event), and the field inventory plus the endpoint GET /v2/orders/{event_id} pin down exactly what is returned. It is clearly distinguishable from ticketsauce_get_order (one order) and ticketsauce_list_events (events, not 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?

It states the default ordering and the override ('pass sort_dir desc for newest first'), and enumerates the available filter axes, which tells the agent what queries are supported. What is missing is an explicit routing statement (e.g., use ticketsauce_get_order when you already have an order id), so usage is clear but not fully exclusive.

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