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

Goes well beyond the annotations: it discloses that Partiful texts or emails each approved guest (explaining why destructiveHint and openWorldHint are set), that invalid ids abort the call before it waits for confirmation, that the call has an approval gate, and that the caller must be a host. These are exactly the side effects and preconditions an agent needs before a mutating call.

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

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

Front-loads the action and scope in the first two sentences, then tacks on preconditions and return shape in order of importance. The aside 'as Approve on the host's guest list does' is a small UI-mapping flourish, but no sentence is dead weight.

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 reports the return shape (approved count plus still-waiting count) and covers side effects and permissions for a destructive mutation. It does not say what happens if all and guest_ids are supplied together, which is the one unresolved ambiguity.

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 schema carries the basics; the description still adds meaning by framing guest_ids as 'the given pending guests' versus all as 'everyone who is pending', and by stating the pending-only validation rule that the schema does not encode.

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 (Approve) and resource (pending guests on a Guest Approval event), and states scope: the given guests, or all of them. An agent can distinguish it from invite_guests and check_in_guests without opening either schema.

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

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

"Hosts only" gives a prerequisite, and "Ids that are not pending are refused" tells the agent which inputs are valid, so the pending-only condition is explicit. There is no direct routing statement against siblings like check_in_guests, which is the remaining gap.

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 destructive/non-idempotent, but the description adds the crucial consequence the annotations cannot convey: real guests receive texts by default, the event page persists in a canceled state rather than disappearing, repeat cancellation is refused, and the action cannot be undone here. This is exactly the extra context a mutation tool needs.

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

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

Front-loaded with the core action, then layered with scope, side effects, and constraints in short sentences. Every sentence adds distinct information with no repetition.

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 still tells the agent the observable outcome (page remains up, marked canceled, guests texted unless disabled) and the failure mode (already-canceled refused). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real-world meaning beyond the schema by emphasizing that notify_guests defaults to reaching real people and that the message is delivered with the cancellation. That consequence framing is genuinely useful over the bare schema field notes.

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 ('Cancel an event') and immediately clarifies the scope of that cancellation: the page stays up marked canceled, which implicitly distinguishes it from the destructive delete_event sibling. 'Hosts only' further pins the caller scope.

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: default behavior texts guests, notify_guests=false suppresses that, already-canceled events are refused, and the action is irreversible. It stops short of naming delete_event as the alternative when permanent removal is wanted, so it is strong but not fully explicit about alternatives.

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

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

Goes well beyond the annotations by disclosing that guests receive no message (no notification side-effect), that ids not on the guest list are refused (error behavior), that only hosts may call it (auth requirement), and what the response summarizes. These are exactly the mutation details annotations cannot convey.

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

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

The primary action is in the first sentence, with undo second and edge-case/return details following in short, dense sentences. No filler or repetition of the title.

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

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

For a non-destructive, non-idempotent mutation with no output schema, the description covers side effects, permissions, error handling, and return shape — everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so event_id, guest_ids, and undo are already fully documented, and the description mostly restates them. It adds only the refusal rule for unknown ids, which is marginal over 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 ('Mark guests as checked in at the door') plus the inverse operation ('undo it'), which is unambiguous against siblings like approve_guests and invite_guests. An agent can tell this is the door check-in action, not the invite/approve flow.

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 undo path and the 'Hosts only' permission gate, and notes that non-guest ids are refused, giving clear conditions for use. It does not explicitly contrast with approve_guests or invite_guests, so the sibling differentiation is inferred rather than stated.

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

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

Beyond the annotations, it discloses that the event is published immediately, private by default unless visibility is public, uses Partiful's default theme, sends no invitations or texts, and returns the new event. It also states the Guest Approval and guest-limit conflict and the timezone behavior for offsetless times.

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 key scoping statement is front-loaded and the description is appropriately sized for an 11-parameter creation tool. There is some redundancy around 'nobody is invited' and invite_guests, but overall it is efficient.

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

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

Given the complexity of the tool, the rich schema, and the absence of an output schema, the description is complete enough for an agent to call it correctly. It covers publishing behavior, privacy, invitation behavior, timezone handling, parameter conflicts, and the return value.

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 carries most parameter meaning. The description adds useful semantics by calling out the mutual exclusion between Guest Approval and guest limit and the timezone interpretation for times without offsets.

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 gives a specific verb and resource: it creates and publishes an event page hosted by the account. It also distinguishes the creation step from invitation by explicitly saying nobody is invited until invite_guests is called.

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 clearly explains the main usage context and names invite_guests as the alternative for inviting guests, plus the share-url path. It does not explicitly route the agent away from siblings like update_event or duplicate_event, so it stops short of full when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the material specifics: exactly what is destroyed (page, guest list, photos, messages), that it is irreversible, that guests may be notified by Partiful, and that host permission is required. This is real value beyond the structured hints.

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?

Scope is front-loaded, consequences follow, then the alternative, then the permission gate. Four short sentences, each carrying distinct information with no repetition of the annotations.

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

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

For a destructive single-parameter tool with no output schema, the description covers irreversibility, blast radius, side effects on third parties, authorization, and the safer sibling. Nothing an agent needs before calling 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?

With a single parameter at 100% schema coverage, the schema already documents event_id and even points to list_events as its source. The description adds no further constraint or format detail, 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?

The opening sentence names a specific verb (delete), the resource (event), and the scope (one you host, for everyone, including the guest list). It is immediately distinguishable from cancel_event, which is explicitly cited as the non-destructive counterpart.

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

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

The description explicitly routes the agent: if the goal is to keep the page and notify guests, use cancel_event instead. It also states the precondition ('Hosts only'), so both the when and the who are covered.

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

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

Beyond the mutation annotations, it discloses exactly what is copied (title, description, location, theme, questionnaire, RSVP settings), what is omitted (guests, messages, RSVP deadline), that length is preserved, that nobody is invited, and that it returns the new event. It does not contradict any 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?

The description is front-loaded and appropriately detailed. It is slightly repetitive about guests and invitations—'no guests yet,' 'no guests and no messages,' and 'Nobody is invited'—but the repetition does add emphasis to an important constraint.

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

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

Given the mutation, lack of output schema, and simple parameter set, the description is complete: it covers source event selection, copied fields, omitted fields, resulting event, host restriction, and return value.

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 schema already explains the three parameters. The description adds useful behavioral meaning for start_at by noting that the copy keeps the original's length and that the RSVP deadline is not copied.

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

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

The description states a specific verb and resource: copy an event to a new date. It clearly scopes what is copied and what is not (settings yes, guests/messages no), which distinguishes it from create_event, update_event, and delete_event.

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

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

It gives clear context that this is for duplicating an existing event with its settings, in contrast to creating from scratch. It also states the 'Hosts only' prerequisite, though it does not explicitly name alternative sibling tools or exclusion cases.

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/idempotent/non-destructive, so the bar is lower, but the description still adds a lot: the file arrives as inline csv text rather than a link, it carries the column list, and it deliberately excludes guest ids, emails and phone numbers. It stops short of noting size limits or truncation behavior for very large guest lists, which is the one real gap.

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

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

Four sentences, front-loaded with the artifact identity and the button equivalence. Slightly dense—the column list is long—but each sentence carries distinct information and none is 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?

No output schema exists, yet the description fully describes the return payload: csv file text, the row count, and a suggested filename. Combined with the column and exclusion notes, an agent knows exactly what it will receive.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining that Status is Partiful's own label (e.g. 'Approved on a Guest Approval event') and that the default is all statuses. It adds meaning about what the enum values actually render as, which the schema does not.

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 (export the guest list as CSV) and pins down the exact artifact: the same file the host's Export CSV button downloads. It also distinguishes itself from list_guests by flagging that this file has no guest ids, so an agent can route correctly without opening a schema.

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

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

Explicitly redirects to a sibling: 'for guest ids use list_guests', and names the audience constraint 'Hosts only'. It also states the selection condition ('for the chosen RSVP statuses'), so when-to-use and the alternative are both covered.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real context beyond them: the host's view of the page, guests grouped per RSVP status, questionnaire questions included, and times expressed in the event's own time zone. It does not address error behavior for an inaccessible or missing event.

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

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

Four short sentences, front-loaded with the payload and followed by return scope, time zone, and permission notes. The opening field enumeration overlaps somewhat with the 'as its page shows it to the host' sentence, a small redundancy but not bloat.

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 return-shape burden and does so by listing the fields, guest grouping, and questionnaire content. Time-zone and permission context round it out; only failure modes for a bad event_id are unstated.

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

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

With a single parameter at 100% schema description coverage, the schema already explains that event_id comes from list_events. The description body adds no further semantics about the identifier, so the baseline 3 for schema-covered parameters 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 names a specific verb (get) and resource (one event) and enumerates the payload the agent will receive: title, description, times, location, RSVP deadline, guest limit, approval/waitlist settings, link. It separates itself from list_events by stating it returns one event and from the write siblings by noting they require an event the account hosts.

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

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

It gives an explicit usability boundary ('Works for any event the account can open') and contrasts with the write tools, which need a hosted event. It does not explicitly tell the agent to call list_events first to obtain the id, though the schema parameter note does.

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

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

Goes well beyond the annotations by disclosing real-world side effects ('they reach real people'), hard quotas (1,000 invites per event, 500 by email), a refusal condition (canceled event), an auth prerequisite (Hosts only), and the meaning of the return field invited_total. This is exactly the context destructiveHint=true and openWorldHint=true imply but do not explain.

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

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

The purpose and the two invite channels are front-loaded, and each subsequent sentence carries distinct operational information (limits, refusals, return value, permissions). No sentence merely restates the name or 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 destructive, open-world mutation with no output schema, the description supplies everything an agent needs: valid input sources, quotas, failure modes, permission requirement, and the meaning of the single returned count. Nothing material is left to inference.

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 genuine meaning: user_ids must come from list_past_guests, emails carry a name 'the invite greets,' and message is the personal note delivered with the invite. The phone-sign-in note further clarifies why email invitees still need a phone number.

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

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

Opens with a specific verb and resource plus its two delivery modes: 'Invite past guests and mutuals through Partiful, or anyone by email.' This clearly separates it from siblings like approve_guests, send_text_blast, and export_guest_list without the agent needing to open a schema.

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

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

Explicitly routes the agent to source lists (user_ids from list_past_guests, emails for anyone else) and states an exclusion: phone numbers cannot be invited, only Partiful's app takes phone contacts. It also gates on 'Hosts only.' It stops short of naming sibling alternatives (e.g. approve_guests for pending requests), so it is clear context rather than a full when/when-not matrix.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's added value here is real: it discloses the inclusion rule (hosted or cohosted only, invitees excluded), the sort order per time range, and the meaning of the returned fields. It stops short of covering pagination behavior or result-size limits beyond what the schema states.

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

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

Four tight sentences, front-loaded with what the tool returns and followed by scope, ordering, and the event_id hand-off. No sentence repeats structured data or wastes space.

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

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

With no output schema, the description carries the burden of describing returns, and it does so well (fields, ordering, statuses, guest counts). It doesn't sketch the shape of an individual event object or mention pagination fields, which would matter for an agent assembling follow-up calls.

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 a baseline of 3 applies, but the description adds genuine meaning: 'Upcoming come soonest first, past most recent first' explains the consequence of the `when` enum values rather than just restating them. `limit` and `cursor` are left entirely to the schema, so it isn't a full 5.

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

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

The description states a specific resource (events this account hosts or cohosts) and enumerates what is returned: start/end in event time zone, active or canceled status, and guest counts per RSVP status. Scope exclusions ('events you were only invited to are left out') further sharpen the purpose. It doesn't explicitly distinguish itself from siblings like get_event or list_past_guests, which keeps it at 4.

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

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

'Use event_id in the other tools' gives an explicit hand-off to the rest of the toolset, and the Hosting-tab analogy plus the invited-events exclusion give clear usage context. There's no explicit statement of when to prefer get_event (single event detail) over this list, so it isn't a full when/when-not/alternatives treatment.

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/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: the host-scoped visibility ('the guest list the host sees'), the sort order ('oldest RSVP first'), and the subtlety that 'going' includes guests approved on a Guest Approval event. It does not discuss pagination behavior beyond the schema's cursor field.

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

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

Two short sections with the resource and its returned fields front-loaded, followed by cross-references to related tools. Dense but every sentence carries information; nothing repeats structured fields verbatim.

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

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

With no output schema, the description carries the burden of describing return values and does so thoroughly — field list, ordering, totals, and host visibility. The only mild gap is how limit and cursor interact across pages, which is left entirely to the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: guest_id is explained as the identifier to pass to approve_guests and check_in_guests, and 'total counts the guests that match the filters' clarifies how the total relates to the status/checked_in filters. It also disambiguates the 'going' enum value, which the schema alone does not.

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 the resource precisely (guests of an event) and enumerates what is returned: RSVP status, check-in, party size with plus-one names, RSVP note, questionnaire answers. It doesn't explicitly distinguish itself from sibling list_past_guests or export_guest_list, so sibling differentiation is only implicit.

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

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

'Hosts only' provides a permission prerequisite, and the note that guest_id feeds approve_guests and check_in_guests hints at downstream workflows. However, there is no statement of when to prefer this tool over list_past_guests or export_guest_list, leaving the usage context implied rather than stated.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description goes further by disclosing data provenance, the returned fields (shared_events, last_shared_event), the empty-new-account case, and that those fields stay 0/null when Partiful omits them. That is meaningful behavioral context beyond the structured hints, though ordering and pagination behavior are left unstated.

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

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

Four dense sentences, front-loaded with the purpose before constraints and edge cases; each sentence carries information (scope, filter behavior, downstream use, empty-state caveats). It is packed rather than padded, though the last sentence compresses two separate edge cases into one long clause.

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 what each result represents and how shared_events/last_shared_event can be zero or null. Combined with annotations and a fully described 4-param schema, an agent has enough to call it correctly; only result ordering/volume expectations are 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 coverage is 100%, so the baseline is 3; the description still adds value with the negative constraint that there is no per-event filter and by pointing user_id (an output field) at invite_guests. It largely restates query/not_on_event_id semantics that the schema already carries, which keeps it from a 5.

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

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

Opens with a specific purpose statement ('People you can invite: your past guests and mutuals') and then defines the exact resource: the set Partiful shows on an event's Invite screen, past guests of your events plus mutuals, with shared-event counts. That scope is clearly distinct from list_guests or invite_guests, so an agent can distinguish it without opening another schema.

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

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

Gives concrete operational guidance: use not_on_event_id to exclude people already on an event, 'there is no filter by one past event' closes off a plausible-but-wrong usage, and query matches partial names. It also chains to the next step ('user_id goes to invite_guests'), which is real workflow guidance, though it never explicitly contrasts with the sibling list_guests.

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

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

Goes well past the annotations: discloses multi-channel fan-out (text, email, push, feed), irreversibility ('cannot be taken back'), two distinct rate/cap rules, the 100-invited refusal, and the fact that the response omits remaining-blast quota. This is exactly the destructive, non-idempotent behavior an agent must know before calling.

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

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

Purpose is front-loaded and the critical irreversibility warning comes early. The 10-blast limit is stated twice (first line and again later), which is the one clearly removable 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?

With no output schema and a destructive mutation, the description does the heavy lifting: it explains what the response reports (recipients/by_status counts) and what it omits (blasts remaining). Docking one point because the naming of response fields not present in the schema invites confusion about the call 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 message length, statuses enum, and show_on_event_page default are already documented; the description mostly restates them. It adds the useful note that counts are computed 'at the moment of sending,' but its reference to 'recipients and by_status' names fields that appear nowhere in the input schema, which can read as phantom parameters.

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

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

Opens with a specific verb+resource+scope: 'Text a message to guests by RSVP status.' No sibling tool does anything comparable (invite_guests adds people, list_guests reads them), so the agent can distinguish it on purpose alone.

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

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

Gives concrete preconditions and conditions for use: host-only, RSVP-status targeting, 10 blasts per event, refusal when Invited exceeds 100 or a chosen status reaches nobody. It doesn't explicitly route the agent to alternatives (e.g., invite_guests to add recipients, list_guests to preview counts), which keeps it below 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?

Goes well beyond the annotations by disclosing PATCH semantics (omitted fields keep values, empty call refused), side effects (Guest Approval clears max_guests and the waitlist; a guest limit enables the waitlist), questionnaire replacement scope, and the return value. This is the kind of cross-field behavior an agent could not infer from readOnlyHint/idempotentHint 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?

Purpose is front-loaded in the first sentence and every subsequent sentence carries information. The middle field-list sentence is dense and runs long, which costs a point but not readability.

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 mutation tool with no output schema, the description states what is returned (the event, with updated fields) and covers side effects, refusal behavior, and authorization. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining interactions the schema does not (guest_approval clears max_guests, max_guests turns on the waitlist, questions replace the questionnaire for future RSVPs). It stops short of covering null semantics for max_guests explicitly in prose, though the schema handles that.

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

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

Specific verb (change details/settings) plus concrete resource (an event you host), with an explicit field inventory that separates it from create_event, cancel_event, and get_event.

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?

Establishes the precondition 'event you host' and anchors partial-update behavior to the event's Edit page, making it clear this is for edits rather than creation or reads. It does not explicitly name sibling alternatives or when to prefer get_event first, 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.