pretix MCP by usefulapi

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description goes further: it states the effect 'cannot be undone from here', that pretix applies its own refusal rules and returns the reason, that it never forces a check-in, and that unanswered required questions come back as incomplete with a question list. These are exactly the failure modes an agent needs to anticipate for a destructive write.

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?

Tight, front-loaded prose: capability, irreversibility, identification, then edge cases. The trailing raw endpoint is the only sentence of marginal utility for an agent, but it does confirm the exact scope of the operation.

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 carries the burden of describing responses and does so for the error paths (refusal reason, incomplete + question list) but not the success payload. Given a destructive, rule-heavy write operation, this is well covered short of the success shape.

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 semantics: it explains the position_id vs ticket_secret trade-off, that one ticket per call, and that `answers` is used to resolve the incomplete response. The `type` (entry/exit) parameter is only hinted at via 'in (or out)', leaving one minor gap.

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

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

Opens with an explicit verb and resource ('check one ticket in (or out) on a check-in list') and marks it as a WRITE operation, which cleanly separates it from all the pretix_list_* and pretix_get_* siblings. An agent can tell immediately that this is the only mutation tool in this family.

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 where position_id comes from (pretix_list_checkin_list_positions) and offers ticket_secret as the alternative identification path, plus concrete refusal conditions (unpaid, canceled, blocked, already-used, wrong-product). What it lacks is an explicit statement of when NOT to call it (e.g. when a list is not in redemption mode), but the implied context is clear.

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 that the figures are 'live' (a point-in-time snapshot rather than historical totals) and outlines the response breakdown, but says nothing about freshness/latency, whether cancelled orders are excluded, or how 'inside now' differs from 'checked in'.

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

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

Two tight sentences; the payload description is front-loaded and the return content is enumerated compactly. The trailing raw endpoint path is slightly redundant for an agent but does no real harm.

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?

Reasonable for a read-only metrics endpoint with no output schema, since the description sketches the return shape. It still leaves ambiguity about semantics of the counters (e.g. does 'inside now' account for un-checks, are canceled tickets counted) that an agent reporting numbers would want.

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 each of the three parameters documented including the organizer-optional rule. The description adds no parameter-level 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?

Clear verb+resource: fetches live check-in counts for a specific check-in list, and enumerates exactly which numbers are returned (tickets existing, checked in, currently inside), broken down per product/variation. It is distinguishable from pretix_list_checkin_list_positions, which lists individual scans, though it does not name that sibling explicitly.

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

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

Usage is implied by the word 'live' and by the aggregate nature of the response, suggesting this is the dashboard-style summary rather than a scan log. However, it never states when to prefer this over listing positions or checking a single ticket, and gives no preconditions.

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 the underlying REST path and the field inventory, which tells the agent what a call returns, but says nothing about error behavior for missing events or permission requirements.

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

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

A single front-loaded field list followed by the endpoint path — no filler. The raw GET path is marginally redundant with the tool's function but is compact and useful for agents mapping to the REST API.

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 compensates by listing the returned fields, which is the main gap it needed to fill for a simple read tool. Annotations handle the safety profile, and the only unaddressed area is failure/permission behavior, a minor omission for a read-only getter.

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 the note that organizer is optional for a single-organizer token, so the schema carries the parameter burden. The description adds no parameter-level syntax or hints beyond that, making 3 the appropriate baseline.

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

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

States a specific verb+resource ('One event in full') and enumerates exactly which fields come back, so it is clearly a single-resource fetch rather than a listing. It doesn't explicitly name pretix_list_events as the contrasting sibling, though the singular framing strongly implies it.

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 singular 'one event' implies you use this when you already have an event slug rather than to browse, and the schema's cross-reference to pretix_list_events supports that. However, the description itself states no when-to-use, no prerequisite, and no alternative for the list case.

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 openWorld=true, so safety is covered. The description adds genuinely useful context that the response nests variations, add-ons, and bundles, but says nothing about auth scope, 404 behavior, or whether add-ons/bundles are expanded vs. referenced.

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

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

Two short sentences, front-loaded with the payload description. The literal REST path is mostly redundant with the schema but is compact and does no harm.

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 getter with full schema coverage and no output schema, the description discloses the one thing the schema cannot: that the returned product is aggregated with variations, add-ons, and bundles. Remaining gaps (error cases) are minor.

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

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

Schema description coverage is 100%, including the note that organizer is optional when the token sees one organizer. The path template in the description merely restates the three parameters already documented in the schema, adding no new semantics.

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: fetches a single product including its variations, add-ons, and bundles. This distinguishes it functionally from pretix_list_items, though the sibling is not named explicitly.

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

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

Usage is only implied: 'One product' versus the plural list tool signals that this is the single-record fetch. There is no explicit statement of when to prefer this over pretix_list_items or what happens if the item id is unknown.

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=true and destructive=false, but the description adds real behavioral context beyond them: it warns the payload contains customer personal data and that secrets, the order link, and payment details are stripped. This redaction/PII disclosure is genuinely useful and not derivable from 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?

Dense and front-loaded: the code example comes first, then the returned fields, then the PII/redaction caveats, then the endpoint. No filler; slight density is offset by the clear ordering.

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 responsibly enumerates the return fields and the safety caveats (PII present, secrets removed). Complete for a read-by-id tool; a minor gap is not clarifying the include_canceled_positions behavior.

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 four parameters are already documented in the schema. The description adds no meaning beyond the schema and in fact omits mention of the include_canceled_positions toggle, 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 (get) and resource (one order by code) and enumerates exactly what is returned: status, customer contact, totals, positions, fees, payments, refunds, invoice address, check-in flags. The singular 'One order by its code' clearly distinguishes it from the sibling pretix_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 implied by the singular fetch-by-code framing, but the description never explicitly says when to prefer this over pretix_list_orders or pretix_list_order_positions, nor that you need a code (which you'd obtain elsewhere). The required code parameter nudges inference but no alternative is named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the HTTP endpoint and the field set as context, but says nothing about behavior when the slug is unknown or omitted (error vs default), which is the main open question for a lookup by optional key.

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 fragments, front-loaded with the return contents and followed by the endpoint. Nothing is wasted, though the telegraphic style leaves the sentences thin rather than fully informative.

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 full schema coverage and safety annotations, the description is nearly sufficient, and listing the returned fields compensates for the absent output schema. The only gap is undocumented not-found / omitted-parameter behavior.

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 the slug pattern and the single-organizer fallback. The description only echoes the path placeholder '{organizer}' and adds no format or resolution semantics 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?

Names a specific verb+resource ('One organizer account') and enumerates the fields returned (slug, name, public URL), plus the underlying endpoint. It implicitly contrasts with pretix_list_organizers through the singular framing, but never names the sibling explicitly.

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

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

Usage is only implied by the singular 'one organizer account' framing. The genuinely useful guidance — the organizer parameter being optional when the token sees exactly one organizer — lives in the schema, not the description, so no when-to-use vs pretix_list_organizers routing is stated in the description itself.

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=true), so the bar is lower. The description adds a genuinely useful caveat not available elsewhere: 'Values can lag slightly', telling the agent the numbers may be stale. It also discloses the composition of the usage breakdown, though it says nothing about error behavior for invalid quota ids.

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?

One front-loaded sentence names the core values, a second adds the staleness caveat, and the API path follows. Dense and mostly waste-free, though the raw endpoint path adds little for an agent that already has structured parameters.

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 carries the burden of describing return values, and it does so by naming available, available_number, total_size and the usage breakdown. Combined with the lag caveat, an agent has enough to call and interpret the result; only error/empty-quota handling is unaddressed.

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

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

Schema description coverage is 100%, so event, quota_id, and the optional organizer are already documented in the schema. The description contributes only the endpoint template, which restates the path parameters rather than adding semantics like slug format or organizer-token behavior. 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 resource and question ('How much of a quota is left') and enumerates the key return fields, so an agent knows exactly what it retrieves. It is distinguishable from pretix_list_quotas in practice (availability vs. quota definitions) but never names that sibling to make the distinction explicit.

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

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

Usage is implied rather than stated: the endpoint path and field list make it clear this is the availability lookup for a specific quota id. There is no explicit guidance on when to prefer this over pretix_list_quotas or how to obtain the quota_id first, so the agent must infer 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 readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the raw REST path, which restates the resource hierarchy already present in the parameter names; it says nothing about 404 behavior for a missing sub-event, returned data shape, or how organizer scoping affects resolution.

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, front-loaded fragments with no filler; the resource identity comes first. The trailing endpoint path is marginally redundant with the schema but is compact and does hint at GET semantics.

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

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

This is a simple single-resource read with 100% schema coverage and annotations covering the safety profile, so the description carries little burden. The main residual gap is that no output schema exists and the description does not characterize what a sub-event record contains (dates, prices, quotas), though the tool name makes the return obvious enough.

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, organizer, subevent_id) are already documented in the schema, including that organizer is optional for single-organizer tokens. The REST path in the description loosely mirrors the parameters but adds no syntax or format meaning beyond them, 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?

The description identifies the resource as "one date (sub-event) of an event series," which distinguishes it from siblings like pretix_get_event and pretix_list_subevents. However, it is a bare noun phrase with no verb (retrieve/fetch), so the action must be inferred from the title 'Get event series date'.

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 statement of when to use this tool versus pretix_list_subevents or pretix_get_event, and no mention of prerequisites or the case where the sub-event id is unknown. The only routing signal is implied by the resource being singular.

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=true, destructive=false, so the safety profile is covered; the description adds value beyond that by disclosing that responses contain attendee personal data and that ticket secrets are stripped. It does not describe pagination behavior or result-size expectations, which keep it short of a 5.

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

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

Three tight sentences, front-loaded with what the payload contains, followed by the privacy note and the endpoint. Minor awkwardness in the 'check in by position id' fragment, but nothing 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 12-parameter read-only list tool with no output schema, the description usefully enumerates the key returned fields and flags PII and secret-stripping. Pagination and the interplay of ignore_status with order__status are left to the schema, which is a reasonable division but not fully complete.

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

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

Schema description coverage is 100%, including enum meanings and page/next_page guidance, so the baseline is 3. The description contributes only the indirect note that positions carry ids usable for check-in, not any filter semantics 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?

The description opens by naming the resource and its scope ('The attendee list of a check-in list') and enumerates the returned fields (attendee name, product, order code, check-in history, attention flag), so an agent can tell what this returns. It also hints at the boundary with the check-in tool ('check in by position id'), though the sibling is not named explicitly.

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

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

The line 'check in by position id' implies this list is a precursor to pretix_checkin_position, which is useful routing. However, there is no explicit guidance on when to prefer this over pretix_list_order_positions, pretix_get_checkin_list_status, or when ignore_status / order__status should be used, leaving selection mostly 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 and destructiveHint=false, and the description adds genuine context: the exact REST path and the shape of each returned list entry. It stops short of discussing pagination behavior or the permission/scope needed to see lists.

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

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

Two sentences, zero waste: the resource and its returned fields come first, followed by the actionable 'what to do with the id' guidance. The parenthetical field list is dense but informative.

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 carries the burden of describing return values and does so at a useful level (id, name, products, date, rules); pagination is delegated to the fully described page/page_size schema. Minor gap: no note on empty results or the ordering of lists.

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 (event, organizer, subevent, page, page_size) is already documented in the schema, including the organizer single-token nuance. The description only echoes 'event' and 'event series date' without adding format or filtering semantics 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 ('List the check-in lists of an event') and enumerates the salient returned fields (id, name, admitted products, series date, rule settings), which distinguishes it from siblings like pretix_get_checkin_list_status and pretix_list_checkin_list_positions.

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 forward: 'Use the list id for check-in status, attendee lists and check-in,' which clarifies this is the discovery step preceding those tools. It does not name an alternative tool or state when not to use it, keeping it 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and returned fields, but does not describe pagination behavior, authentication requirements, or rate limits. With annotations carrying the safety burden, this is adequate 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?

Two sentences with no wasted words, front-loading the resource, scope, returned fields, and filtering capability. The parenthetical field list is dense but informative, and the endpoint is appended without disrupting flow.

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 13 optional parameters, full schema coverage, and no output schema, the description does well to name the organizer scope, returned fields, and main filter categories. It leaves pagination and several filter semantics to the schema, which is acceptable given the schema quality, but it could do a bit more to route between sibling list tools.

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

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

Schema description coverage is 100%, so all 13 parameters are fully documented in the schema. The description mentions search, live, and date filtering but does not add syntax or behavioral meaning beyond what the schema already provides. 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 clear verb and resource with scope: lists events belonging to an organizer. It also enumerates the returned fields (name, slug, dates, live/test mode, currency, location, series flag), which helps an agent know what it gets. It does not explicitly distinguish itself from pretix_list_subevents or pretix_get_event, so it falls short of a 5.

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

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

The description gives some usage context (filter by search text, live state, or date) but omits when to prefer this over pretix_list_subevents or pretix_get_event. Many available filters (is_past, is_future, testmode, is_public, has_subevents, ordering) are not mentioned, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description's marginal contribution is the list of returned fields plus the REST endpoint, but it says nothing about pagination behavior, token scoping for the optional organizer, or result ordering.

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 purpose and returned fields, with the endpoint trailing as supporting detail. Slightly dense field enumeration but 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?

With eight parameters, no output schema, and a read-only listing role, the description covers the essentials and usefully enumerates the returned fields in place of an output schema. It could go further on pagination and on the organizer-token fallback, but nothing critical for calling it 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 all eight parameters are already documented in the schema; baseline is 3. The description only mentions the event scope and does not add semantics for the filter parameters (active, admission, search, category) or page/page_size.

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 products ... of an event') and parenthetically clarifies the domain terms (ticket types, merchandise). It is distinguishable from pretix_get_item by the plural 'List' verb, though it never explicitly contrasts with 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?

Usage is only implied by the verb — an agent can infer this is the bulk-fetch counterpart to pretix_get_item, but the description gives no explicit when-to-use or when-not-to-use guidance, and no mention of the available filters as a selection rationale.

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, the description adds genuinely useful context: the results contain attendee personal data and ticket secrets are stripped. It stops short of discussing pagination limits or permission scopes, but the PII and secret-redaction notes are the important behavioral disclosures for this tool.

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

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

The scope statement and field list are front-loaded, and the PII/secret notes immediately follow. The inline endpoint path is somewhat redundant with the tool name but does not bloat the text significantly.

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 13-parameter filtered-list tool with no output schema, the definition covers scope, return fields, data sensitivity, and redaction, which is enough to call it correctly. It omits explicit pagination guidance and alternative-tool routing, both of which the schema partially covers.

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 13 parameters is already documented in the schema, making the baseline a 3. The description only adds the event-omission behavior, which the schema also states; it adds little else about parameter semantics.

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?

It gives a specific verb and resource ('List the individual tickets (order positions)'), states the scope (one event, or all events of the organizer when no event is given), and enumerates the returned fields. The distinction from pretix_list_orders is clear from the parenthetical 'order positions' and the per-attendee field list.

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 key routing condition: omit the event to search across all events of the organizer, which directly controls a major parameter. It does not name pretix_list_orders or pretix_list_checkin_list_positions as alternatives or state when to prefer those, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, yet the description adds substantive context: the response contains customer personal data, and order secrets, order links and payment details are stripped. That redaction disclosure is exactly the kind of beyond-annotation signal an agent needs, though return-shape particulars (counts, next_page) are 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?

Front-loaded with scope then return contents, followed by the security caveat and the endpoint path. Every sentence carries information except the raw GET URL, which is largely redundant with the tool's own naming and adds length without adding decision value.

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 this is nearly complete: scope, returned field inventory, and a PII/redaction warning are all present. Only the pagination contract and result-cap behavior are unaddressed in prose, and those are covered by the page/page_size schema descriptions.

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 17 parameters, including the event/organizer conditional and pagination defaults, so the structured data does the heavy lifting. The description only reinforces the event-omission behavior and the field set, adding little semantic 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 plus the dual scope ('one event, or of all events of the organizer when no event is given'), and enumerates the fields returned. This clearly separates it from the single-order sibling pretix_get_order and from pretix_list_order_positions.

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?

Explains the two operating modes: supply an event to scope to one event, omit it to sweep all events of the organizer. It does not explicitly contrast with pretix_get_order for single-order lookups or with the position-level listing tool, so there is no named alternative or when-not clause, but the usage context is unambiguous.

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

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 behavioral context: token-scoped visibility rules and the underlying endpoint GET /organizers/.

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, with the returned fields and endpoint appended without waste.

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 names the returned fields and explains the token-based visibility filter. It stops short of noting that pagination may be needed to retrieve the full list, a minor gap for a simple list tool.

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

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

Schema description coverage is 100%, so page and page_size are already fully documented, including the next_page chaining hint. The description adds nothing about pagination, which is acceptable given the schema baseline.

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

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

States a specific verb and resource (list organizer accounts) plus the scope qualifier ('this API token can access') and the returned fields (slug, name, public URL). It is clearly distinguishable from the singular sibling pretix_get_organizer.

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

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

Gives clear context for when this applies: enumerating organizers reachable by the current token, with the note that a team token sees only its own organizer. It does not explicitly name pretix_get_organizer as the alternative for fetching a single known organizer.

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 the underlying endpoint and that availability fields are conditionally included, but says nothing about pagination behavior or result volume beyond what the schema already states ('Can be slow on big events').

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

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

A single front-loaded sentence covering purpose and payload, plus the endpoint for reference. Minor waste in the duplicated word ('with with_availability') and the endpoint restates structured context, but overall tight.

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

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

With no output schema, the description usefully enumerates what the response contains (size, covered products, closed state, availability counts), which is exactly what an agent needs to decide whether to call it. Only the subevent filtering nuance is left to the schema, which handles it well.

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 (page, page_size, organizer, event, subevent, with_availability) is already documented. The description only echoes the with_availability effect, adding no syntax or semantics beyond the schema — 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 quotas (capacity pools) of an event') and enumerates the payload fields (size, covered products, closed state, availability). This makes it distinguishable from the single-quota sibling pretix_get_quota_availability, though it never names that sibling explicitly.

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

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

Usage is implied by the field list and the parenthetical 'with with_availability, how many are still available' hints at when to enable that flag, but there is no explicit when-to-use/when-not guidance and no pointer to pretix_get_quota_availability as the alternative for a single quota's availability.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned fields (id, name, dates, location, presale window, price overrides) and the underlying endpoints, but says nothing about pagination behavior beyond the schema or about what auth/visibility constraints govern non-public dates.

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 sentences: purpose and scope first, then payload contents, then endpoints. Nothing is wasted, though the trailing endpoint URL sentence is largely redundant given the tool name and adds little for an agent already choosing the tool.

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, no output schema, and rich annotation coverage, the description does enough — it names the returned attributes and both call modes. Pagination flow (page/next_page, page_size limits) lives entirely in the schema and is not echoed, which is acceptable but leaves the description slightly thin on multi-page behavior.

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 all 11 parameters are already documented, including the event-omission rule and date filters. The description only echoes the dual scope implied by the optional event parameter and adds no syntax or interaction 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 ("List the dates (sub-events) of an event series") and clarifies the two scopes: one event or all series of an organizer. That phrasing separates it cleanly from pretix_list_events (series) and pretix_get_subevent (a single date), and the endpoint paths reinforce the distinction.

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?

Makes the selection condition explicit for the main branching decision: supply an event slug for one series, or omit it to span all series of the organizer. It stops short of naming alternatives such as pretix_get_subevent for adjacent detail or when to prefer pretix_list_events.

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, so the safety profile is covered; the description adds value by confirming no voucher is dispatched as a side effect and by disclosing that results contain personal data (name, email, phone). It does not mention rate limits or result-set size, but the extra PII and no-side-effect context goes 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?

Three short sentences: what it returns, the safety/PII caveat, and the underlying endpoint. The content description is front-loaded and nothing is redundant with 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 no output schema, the description usefully characterizes the returned record fields (waiter, product, entry date, voucher status) and notes PII, which is what an agent needs to interpret results. Paging behavior and total counts are only implied via schema, leaving 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 description coverage is 100%, with every parameter including event, item, email, has_voucher, ordering, and paging documented inline. The description adds no parameter-level detail beyond the general notion of listing entries, so the schema carries the full burden — 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 ('List the waiting list entries of an event') and enumerates the actual content of each entry (who waits, for which product, since when, voucher status). No sibling tool covers waiting lists, and the endpoint path confirms the resource unambiguously.

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 useful operative context — 'Read-only: no voucher is sent' and 'Contains personal data' — which tells the agent this is a safe inspection call and flags PII handling. It stops short of stating filtering scenarios (e.g., use has_voucher=false to find unserved entries) or pointing at a follow-up tool for sending vouchers, so no explicit 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.