Humanitix MCP by usefulapi

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

Annotations only declare destructiveHint=true and a title, so the description carries real weight here: it discloses that the operation is reversible via humanitix_check_out_ticket and that the response includes configured scanning messages. It does not cover re-check-in behavior or error conditions, but the added context is substantive for a terse annotation set.

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

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

Three short sentences, front-loaded with the action and its undo path; the return-value note follows logically. The trailing REST endpoint is mildly redundant for an agent but not wasteful.

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

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

With no output schema, the description does the right thing by noting the return payload (scanning messages), and it covers reversibility and the mutation's scope. Only minor gaps remain around error/failure modes and permission requirements.

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 both required ids and the override_location enum fully documented in the schema (including the per-region storage note). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Mark a ticket as checked in at the door') and distinguishes it from the sibling it is not, humanitix_check_out_ticket. An agent can identify the operation and its inverse without opening the schema.

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

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

Gives clear operational context ('at the door') and explicitly names the inverse tool for undo, which helps an agent choose between the check-in/check-out pair. It stops short of stating when NOT to use it (e.g. duplicates, already-checked-in tickets).

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

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

The destructiveHint=true annotation already flags this as a mutating operation, and the description usefully clarifies the resulting state (ticket becomes checked out). However it says nothing about permissions/API-key requirements, what happens if the ticket is not currently checked in, or whether the change is reversible or rate limited.

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

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

Two tight sentences with the operational meaning front-loaded and the endpoint appended for API mapping. The endpoint restates the resource path somewhat redundantly, but 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?

For a simple two-required-parameter state-change tool with full schema coverage and a destructiveHint annotation, the description covers purpose, state transition, and rationale. It does not address the response shape or failure modes, but no output schema exists so those gaps 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% — event_id, ticket_id, and override_location all carry their own descriptions, including the region enum semantics. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("mark a checked-in ticket as checked out") plus the state transition and the API endpoint it maps to. The parenthetical rationale (undo a mistaken check-in, track re-entry) makes it unambiguous against the sibling humanitix_check_in_ticket, whose inverse it is.

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

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

Gives clear when-to-use context: reversing an erroneous check-in or recording re-entry. It does not explicitly name humanitix_check_in_ticket as the counterpart operation or state a when-not condition (e.g. ticket already checked out), so it stops short of full routing guidance.

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

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

Annotations only supply destructiveHint=true; the description adds genuinely useful behavior the agent could not otherwise know, namely the account-level permission requirement and the 403 failure mode. It also clarifies that ticket setup is out of scope for this call. It omits whether the call is idempotent or what happens on partial success, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with what gets created, followed by the follow-on step and the permission caveat. 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?

For an 8-parameter tool with nested oneOf locations and enums, the schema and description together cover inputs well and the permission requirement is surfaced. With no output schema, the description never hints at what a successful call returns (e.g. an event id needed for subsequent calls), which is the only meaningful gap.

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

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

Schema description coverage is 100%, so every parameter, enum and nested variant (online/address/custom/toBeAnnounced) is already documented in the schema. The description recaps the field list (name, description, timezone, dates, location, keywords, classification) but adds no syntax or constraint detail beyond it, 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 ("Create a base event") and enumerates the core payload fields, distinguishing it from update_event and get_event among siblings. The "base event" framing plus the note that ticket types come later makes the boundary of this tool unambiguous.

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

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

Gives clear preconditions (special permission must be activated, else 403) and a boundary rule: ticket types are configured afterward in the Humanitix console, not through this tool. It does not explicitly say when to prefer humanitix_update_event for changing an existing event, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond that: it flags the endpoint as BETA and discloses the return ordering ('most check-ins first') and filtering ('ticket types with sales only'). It stops short of noting rate limits or auth requirements, but for a read tool this is solid.

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

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

A single, front-loaded sentence that leads with the question answered, followed by scope and the raw endpoint. No filler; every clause earns its place.

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

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

With no output schema, the description compensates by explaining the return shape (total plus per-ticket-type counts, ordered by check-ins). Combined with annotations and full parameter coverage, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both event_id and event_date_id are fully documented by the schema. The description only weakly reinforces that event_date_id denotes a single date ('one date of an event') rather than a range; 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+resource: retrieving check-in counts for one date of an event. Clearly distinguishes from the mutation siblings (humanitix_check_in_ticket / humanitix_check_out_ticket) and other get_* tools by naming the exact quantity returned. An agent can tell what it does without opening the schema.

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

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

The description scopes the tool to 'one date of an event', which implies the usage context, but it never states when to prefer this over sibling tools or any prerequisites/exclusions. No explicit when-to-use or when-not-to-use guidance is 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?

readOnlyHint=true already declares the safety profile, and the description goes further by disclosing the concrete return fields and, most usefully, that each date's _id is the event_date_id accepted by other tools. That cross-tool identity mapping is real behavioral context not present in annotations or schema.

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

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

One dense sentence opens with the verb and payload list, then the hidden-resource hint, then the endpoint. Efficient and front-loaded; the REST path is mild redundancy but harmless.

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 returns and does so by enumerating the main fields, plus it explains the event_date_id linkage needed for follow-up calls. It stops short of noting region-scoping behavior of override_location, which is the only notable 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%, so both event_id and override_location are already documented in the schema, making 3 the baseline. The description mentions dates and ids but never explains the override_location region semantics, adding nothing parameter-specific beyond the schema.

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

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

States a specific verb ('Fetch') and resource ('one event'), then enumerates exactly what is returned. 'One event' clearly distinguishes it from the sibling list_events, and the REST path removes any ambiguity about the underlying resource.

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-resource framing, so an agent can infer it is for retrieving a known event_id rather than enumerating. However, it never says when to prefer this over humanitix_list_events or humanitix_get_order, nor are there any prerequisites or 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?

readOnlyHint=true already declares the safe-read profile, so the description's job is context, and it delivers by disclosing the returned data surface (totals, checkout-question answers, buyer details) in the absence of an output schema. It stops short of stating auth requirements, failure modes for a missing/foreign order id, or region scoping 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 tight sentences: the value payload is front-loaded and the endpoint mapping trails as a compact reference. No filler, 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 read-only single-resource fetch with full schema coverage and no output schema, the description supplies the essential return-content summary and endpoint mapping. Only minor gaps remain: no mention of region-scoped access semantics or error behavior when the order/event pairing is invalid.

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

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

Schema description coverage is 100%, so all three parameters including the override_location enum are already documented. The description adds only the implicit 'event plus order' pairing, which the schema already conveys, 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 ('Fetch') and resource ('one order of an event'), names the resolved identifiers, and enumerates what the payload contains (totals breakdown, checkout answers, buyer details). The singular 'one order' plus the required event/order ids cleanly distinguishes it from sibling list_orders, and the REST endpoint mapping removes ambiguity.

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: it fetches a single order when you already have event_id and order_id. There is no explicit guidance on when to prefer this over list_orders, how to obtain the order id, or when override_location applies, which are the decisions an agent actually faces.

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, so the safe-read profile is covered. The description adds the backend route (GET /v1/tags/{tagId}), which is mildly useful context, but says nothing about missing-tag/404 behavior, authentication requirements, 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?

Two short sentences, purpose front-loaded, and the endpoint mapping appended compactly. No filler or redundancy.

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

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

For a single-resource getter with complete parameter documentation this is largely adequate, but with no output schema the description gives no hint of what a returned tag contains or its fields, leaving a modest 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% and the single tag_id parameter is fully documented with a 24-character hex pattern in the schema. The description adds no format, syntax, or sourcing detail beyond what the schema already provides, 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 verb and resource ("Fetch one tag by id") and the singular "one tag" combined with the id parameter distinguishes it from the sibling humanitix_list_tags. An agent can tell immediately this retrieves a single tag rather than enumerating 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?

There is no explicit when-to-use guidance, no prerequisite (e.g., that a tag_id must first come from humanitix_list_tags), and no named alternative or exclusion. Usage is only weakly implied by the "by id" phrasing.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds useful behavioral context by disclosing that the response includes check-in history and swap history, which the annotations do not cover, though it says nothing about error behavior for invalid/missing tickets.

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 purpose and payload contents, with the endpoint mapping appended. Every clause carries information and nothing is repeated from the schema.

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

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

For a read-only single-resource fetch with full schema coverage and annotations covering the safety profile, the description supplies the missing piece: what extra data the ticket payload carries. It is nearly complete, though a note on the split-region lookup (why override_location exists) would round it out.

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 event_id, ticket_id formats and the override_location enum semantics. The description adds no parameter-level detail beyond the endpoint template, 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 (Fetch) and resource (one ticket of an event) and clarifies scope as a single ticket, which distinguishes it from the sibling humanitix_list_tickets. The description also names the payload's distinguishing content (check-in history, swap history) and the underlying REST endpoint.

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: needing a single ticket's detail rather than a ticket list. No explicit when-to-use/when-not statement, no named alternative (e.g., humanitix_list_tickets) and no prerequisites such as required IDs being valid for the caller's region.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds sorting order, the pagination shape returned (total/page/pageSize), and the underlying endpoint. It does not mention rate limits or auth requirements, but for a read-only list tool this is solid added context.

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

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

Three short, front-loaded sentences with no filler; the most important scoping information (your events, newest first) leads. The trailing endpoint reference is slightly incidental but cheap.

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 read-only, filterable list tool with 100% schema coverage and no output schema, the description covers filtering, ordering, and pagination response shape well. Region override behavior (override_location) is left entirely to the schema, which is 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%, so all five parameters are already documented. The description restates the concepts behind in_future_only and since but adds no format, default, or boundary 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 and resource ('List your events') and adds scope details (newest first, dates, ticket types, pricing, capacity). The possessive 'your events' implicitly separates it from the sibling humanitix_list_global_events, but no sibling is named explicitly.

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

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

Explains the two filtering modes ('upcoming events or events changed since a date'), which tells an agent when the in_future_only and since parameters are relevant. No explicit when-not or named alternatives, 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 only declare readOnlyHint=true, and the description adds genuinely useful behavior beyond that: the special account permission required (403 otherwise), the 'one row per date' cardinality, inclusion of on-sale status per ticket type, and that results are paged. No contradiction with the read-only annotation.

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

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

Three dense sentences with the resource and granularity front-loaded, followed by the permission constraint, pagination, and endpoint. Every clause carries information; the description is appropriately sized for a 7-parameter listing 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?

Covers the essentials an agent needs: scope, row granularity, permission requirement, and pagination. With no output schema, the description could say more about what fields each row returns, but for a read-only list tool it is close to 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% with all 7 parameters documented, including enums and the subcategory->category dependency. The description adds no parameter-level syntax or format detail, so the schema carries the full load and 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 verb+resource (list event dates) and clarifies the granularity that separates it from the sibling list_global_events: 'one row per date' and platform-wide scope. It never names the sibling explicitly, which keeps it short of a 5, but the resource and scope are unambiguous.

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

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

Usage is implied by the scope ('from across the platform') and the permission prerequisite, which tells the agent when the call will fail (403). It does not say when to prefer this over humanitix_list_global_events or humanitix_list_events, so the agent must infer the alternative.

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?

Adds real behavior beyond readOnlyHint=true: an authorization prerequisite with the concrete failure mode (403), pagination ('Paged'), and the underlying GET endpoint. Missing detail on pagination limits/return shape keeps it from a 5.

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

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

Three short sentences, front-loaded with what the tool returns and its scope, followed by the permission caveat, pagination note, and 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?

A read-only list tool whose safety profile is covered by annotations and whose seven parameters are fully documented in the schema; the description adds the permission gate, pagination, and endpoint. Return format is not described, but no output schema exists to cover it either.

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 enums and constraints fully documented, so the schema carries parameter semantics. The description only restates the filterable fields (type, category, subcategory) without adding syntax or usage nuance, so baseline 3 is appropriate.

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

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

States a specific verb and resource (list public events) plus a precise scope: across the whole Humanitix platform. The platform-wide scope implicitly separates it from humanitix_list_events, though no sibling is named explicitly, so it falls just short of a 5.

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

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

Gives clear context for when this tool applies: platform-wide (not account-scoped) events, gated behind a special permission that yields a 403 otherwise. It does not explicitly contrast with humanitix_list_events or state when not to use it, so no exclusions are offered.

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

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

Annotations only declare readOnlyHint=true; the description goes further by disclosing the paged nature of the result set and, importantly, the shape of the record fields returned, which matters because there is no output schema. It does not cover rate limits or per-region data behavior hinted at by override_location.

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: capability plus returned fields first, then paging and the underlying API route. 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 field enumeration compensates for what the agent otherwise could not know about the response, and paging plus the endpoint round it out. Minor gaps remain around regional data semantics and result volume.

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 six parameters (including the page/page_size paging and since ISO filter) are already documented in the schema. The description only adds 'optionally one date of it' for the date filter and 'Paged', so baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (orders for an event), scopes it with the optional single-date narrowing, and enumerates the returned fields (buyer, financial status, totals, discounts, payment type, sales channel). This clearly separates it from sibling humanitix_get_order (single order) and humanitix_list_tickets.

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 resource scope ('orders for an event') and the parenthetical optional date filter, but there is no explicit when-to-use statement and no routing guidance against alternatives such as humanitix_get_order for a single order.

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?

readOnlyHint=true already declares the safe-read profile, and the description adds that results are paged plus the raw GET /v1/tags endpoint. It does not describe the returned tag shape or pagination limits, so it adds moderate value over 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 fragments, scoping statement first, zero filler. Every sentence earns its place.

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

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

For a simple read-only list tool with annotations covering safety and a fully described schema, the definition is nearly sufficient. The only minor gap is that tag fields are not hinted at, though with no output schema that is a small omission.

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

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

Schema description coverage is 100%, so both page and page_size are fully documented in the schema. The description only repeats the paging concept ('Paged.') without adding syntax or bounds, so the baseline 3 is appropriate.

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

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

Specific verb+resource ('List the tags you use to group events') and it even explains the relationship to event records via tagIds, which helps distinguish this from humanitix_get_tag and the event-listing 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?

Usage is only implied — the description frames tags as event-grouping metadata but never states when to call this versus humanitix_get_tag or when tags are needed. No exclusions or prerequisites 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, so the safety profile is covered. The description adds real context beyond that: it discloses paging behavior ('Paged') and enumerates the returned fields (attendee name, ticket type, price, check-in state, seating), which matters because no output schema exists.

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 dense, front-loaded sentence plus the REST endpoint reference; nothing is padded or redundant. The scope, filters, return fields, and paging all appear in a single pass.

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 read-only list tool with full schema coverage, the definition supplies what structured fields lack: the returned field set and the paging trait. The only gap is the absence of guidance on how overlapping list tools differ.

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 including enum values and ISO 8601 format is already documented. The description only loosely gestures at the date and status filters, adding no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('List the tickets (attendees) for an event'), clarifies the plural collection scope, and enumerates the returned fields. The singular sibling get_ticket and the related list_orders are implicitly differentiated, but no sibling is named explicitly.

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

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

The phrase 'optionally one date of it and complete or cancelled only' hints at the available filter dimensions, but never states when to prefer this list tool over humanitix_get_ticket or humanitix_list_orders, nor any prerequisites. 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?

Beyond the destructiveHint annotation, the description discloses that date deletion is not exposed, that unspecified fields are left untouched, that a special account permission is required (403 otherwise), and the underlying PATCH endpoint. These are meaningful behavioral and authorization traits an agent cannot get from the annotations alone.

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?

Information is front-loaded: the field list leads, the date-operation caveat and partial-update rule follow, and the permission requirement and endpoint close it. Every sentence carries load with no filler.

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

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

For a 9-parameter tool with deep nested objects, this is close to complete: it covers mutation scope, date-op limits, partial-update semantics, and authorization. The only minor gap is no explicit guidance on the override_location/regional storage behavior implied by 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 documents each field and nested structure in detail; the description reinforces this by listing the updateable field set. It adds the useful constraint that date operations are limited to CREATE/UPDATE, but the per-field meaning remains schema-driven.

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 (Update) and resource (an event) and enumerates exactly which fields are touched: name, description, timezone, location, keywords, classification, and dates. This is enough to distinguish it from sibling create_event/get_event 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?

It clarifies the date-operation semantics (CREATE and UPDATE, no delete) and that only passed fields are sent, which implicitly signals a partial-update pattern. However, it never explicitly states when to reach for this tool versus create_event, get_event, or list_events, leaving sibling routing to inference.

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