Lemonvite

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

Annotations only supply readOnly/destructive/idempotent/openWorld hints; the description goes well beyond them by disclosing dedup semantics (matched by email or phone, name-only re-saved every time), the 2000-contact cap with all-or-nothing batch rejection, per-contact partial validation failure, and that nobody is messaged. These are the operationally decisive facts an agent 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 routing rule, then batch limits, dedup, and cap behavior in compact clauses. Every sentence carries an operational fact, though the density is near the upper bound for a single-call description.

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?

An output schema exists so return values need no explanation; the description covers scope, alternatives, batch limits, validation behavior, dedup, and the hard cap. Nothing an agent needs to call this 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% and documents the batch and field limits, so the schema carries most of the load. The description adds genuine value the schema does not: each contact needs at least a name, email, or phone (the item schema has no required array), and that malformed email/phone fails only its own contact.

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 ('people saved to their Lemonvite contact list (address book) for future invitations') and immediately contrasts the scope with sibling tools (lemonvite_add_guests, lemonvite_invite_contacts). An agent can distinguish this from the invite/guest tools 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?

Explicit when-to-use ('without inviting them to an event now') plus named alternatives and the condition that selects each. It also advises searching before re-saving name-only contacts, giving a concrete pre-call 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 declare a write/destructive/non-idempotent/open-world profile, and the description substantially enriches it: immediate invitation on published vs deferred to publish on draft, SMS consent requirement, guest_limit immutability, phone pricing behavior, payment_required short-circuit that saves no guests, per-guest isolation of failures, and credit sharing with publishing. This goes well beyond what annotations 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?

Long but front-loaded with purpose and batch rule; nearly every sentence carries operational weight given payment, SMS-consent, and batch complexity. It reads as one dense block rather than scannable sections, which is the only weakness.

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 an output schema present, return values need not be described, and the description still covers the branching behaviors (published vs draft, consent, credits, per-guest results) an agent needs to call this correctly. Complete for a high-complexity write tool.

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

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

Schema coverage is 100%, so the schema carries parameter definitions; the description nonetheless adds workflow meaning beyond it, explaining the authorized_credits shortfall/buy-then-retry loop and the semantic weight of host_confirms_sms_consent. Marginal but real added value over 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+resource ('people actually added to the guest list of an existing Lemonvite invitation') and explicitly fences off the nearest sibling behavior (brainstorming) and the update path (lemonvite_update_guests for fixing existing guests). An agent can distinguish this from list/add/update/invite siblings without opening schemas.

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 explicit when-to-use, when-not ('do not use it while the user is only brainstorming whom to invite'), batch guidance ('send the whole list in one call of up to 50 guests, not one call per guest'), and names alternatives (lemonvite_update_guests, lemonvite_start_checkout). Nothing is left 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?

Beyond the annotations (which only say write/destructive/open-world/non-idempotent), the description discloses that the call produces a DRAFT and does not publish, charge, or contact anyone, that invitation_image triggers a download-and-store side effect, that reminder_date schedules a future host email, and that validation failure creates nothing and returns a field-specific error. That is exactly the kind of mutation semantics annotations cannot carry.

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 trigger condition and the required-field summary, then next steps. Every sentence carries information, though the middle section (image download, reminder email, draft caveat, required fields) is dense and slightly run-on for a single paragraph.

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 26-parameter mutation tool with nested objects and an output schema, the description covers the gaps structured data can't: draft-vs-published state, absence of side-effect charges/notifications, error behavior, and the multi-tool workflow that follows. Return values are correctly left to the output 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 the baseline is 3, but the description adds a useful synthesis: the required set (title, event_type, start_datetime, timezone) plus the conditional requirement of location_name for in-person events, and the reassurance that everything else is deferred to update_invitation. It doesn't explain the nested custom_fields replacement semantics, but the schema does.

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

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

The description opens with a specific verb+resource ('create an invitation, make an invite, set up RSVPs') and scopes it to 'an actual Lemonvite invitation or RSVP page'. It distinguishes itself from siblings by explicitly naming lemonvite_update_invitation, lemonvite_add_guests, lemonvite_publish_invitation and lemonvite_start_checkout, so an agent can route 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 gives an explicit trigger ('when the user wants an actual Lemonvite invitation or RSVP page'), an explicit exclusion ('Do not call it merely because invitation wording or images are being discussed'), and names the alternatives for the follow-up steps (add_guests, publish_invitation, start_checkout). Nothing about when to select this tool is left 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 declare destructiveHint=true and idempotentHint=false; the description goes well beyond them by disclosing the cost (one design generation), the destructive effect (REPLACES current artwork, prior version retained in history), and a required confirmation step. It also states eligibility limits (non-GIF, no web-editor layers) that the annotations cannot express.

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 design/versus-edit distinction is front-loaded and every clause carries operational weight (cost, replacement, confirmation, preconditions, alternatives). It is dense and long for a two-parameter tool, but there is no filler or 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 an output schema present, return values need not be described. The description covers side effects, cost, confirmation requirement, preconditions, and routing to three alternative tools, leaving nothing an agent needs before calling it.

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 semantics: edit_request must be the user's own words and must NOT be rewritten into a design brief, and unmentioned aspects stay unchanged. Silence on event_id is acceptable since the schema already forbids confusing it with invitation_id or RSVP URL.

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 (edit the invitation's existing artwork) and immediately contrasts it with the sibling lemonvite_generate_design. The examples ('make the sky a sunset') pin down the resource boundary between editing and creating, so the agent can distinguish it from siblings without opening schemas.

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?

Explicit when-to-use ('user wants a change to CURRENT artwork rather than a new design'), explicit when-not ('to create artwork from scratch use lemonvite_generate_design'), and a third routed case ('to attach an image this assistant made use invitation_image on lemonvite_update_invitation'). Preconditions are also spelled out (existing non-GIF artwork, no text/image layers).

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 destructiveHint/idempotentHint annotations: it discloses that each call consumes one design generation, REPLACES the current artwork while earlier designs remain in the event's design history, requires user confirmation, and explains the credit economy (5 to start, +5 per purchased credit). That is exactly the cost/side-effect context an agent needs before a destructive, non-idempotent 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-loaded with the routing condition, then guidance, then side effects. Every sentence carries distinct information, though the paragraph is dense and a reader must hold several constraints at once; minor structural cost, no 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?

Output schema exists so return values need no explanation. With annotations covering the safety profile, the description still supplies cost, replacement behavior, confirmation requirement, credit accounting, and parameter intent — nothing an agent needs to call this 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 already 100%, so the baseline is 3, but the description adds genuine semantics: design_brief should be written as art direction, it need not repeat date/time/venue because those are lettered on automatically, include_event_details=false is the escape hatch for detail-free artwork, and reference_image guides style but is not stored as the artwork. The last point in particular is not derivable from 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+resource (Lemonvite's design engine creating the invitation artwork) and immediately distinguishes itself from siblings by naming lemonvite_edit_design for changes and invitation_image on lemonvite_update_invitation for attaching existing images. An agent can route correctly 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?

Explicit when-to-use (user asked for a Lemonvite design, or this assistant cannot make images), explicit when-NOT ("Never call it merely because designs or themes are being discussed"), and named alternatives with the condition selecting each.

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 the safe read-only, closed-world profile, and the description adds real substance beyond them: credits are consumed by publishing (one) and by extra phone-guest batches (one more), generations_remaining never resets over time, and each purchased credit yields 5 generations. It stops short of stating auth/permission needs or any freshness/caching behavior, which keeps it below 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?

Front-loaded with the triggering user questions, then the two field definitions, then credit rules, then sibling routing. Every sentence carries functional information (cost model, non-resetting counter, 5-generations-per-credit conversion) 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?

With zero parameters, a present output schema, and annotations covering the safety profile, the description supplies everything else an agent needs: when to call it, how to interpret the two numeric fields, and which sibling to use for the adjacent credit questions. Nothing material is missing for correct invocation.

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?

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The prose describes the account fields returned rather than call inputs, which is appropriate here.

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

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

It names a specific resource (the connected Lemonvite account) and enumerates exactly what the caller learns: which account is connected, credits, and generations_remaining. The two returned quantities are defined in domain terms, so an agent can tell this apart from siblings like lemonvite_get_invitation without opening any schema.

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

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

The opening clause states the user intents that should trigger this call, and the closing clauses route the agent elsewhere when appropriate: lemonvite_start_checkout for adding credits, lemonvite_get_invitation (required_credits) for per-invitation cost. When-not-to-use is handled by explicit alternative naming rather than 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds value by disclosing that co-hosts may read the invitation and by scoping exactly which fields are returned. It does not discuss rate limits or freshness of the data, so it falls 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?

Front-loaded with the trigger condition ('Use this when...'), followed by permission context and then three routing sentences. Every sentence either defines scope, clarifies access, or redirects to an alternative — nothing 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?

An output schema exists so return values need not be detailed, and the description still previews them. With a single fully-documented required parameter, complete annotations, and explicit sibling routing, an agent has everything needed to select and invoke this 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 description coverage is 100% and the schema already explains that event_id comes from create/list and is not a guest invitation_id or RSVP URL. The description's 'get event_id from lemonvite_list_invitations' partially repeats that. Baseline 3 applies 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 specific read operation on a single named resource and enumerates the exact payload contents (publication/payment status, credits needed, guest and RSVP counts, custom fields, guest settings). This is clearly distinguishable from sibling read tools like get_rsvp_summary and list_guests.

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: get event_id from lemonvite_list_invitations, check payment_status here before lemonvite_publish_invitation, and use lemonvite_list_guests or lemonvite_get_rsvp_summary for guest-level or count-only needs. Both when-to-use and when-to-use-something-else are 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 the safety profile (readOnlyHint=true, destructiveHint=false), but the description adds substantial operational context: counts are live, only active guests are included, removed guests are excluded, each guest counts once under one status, and plus-ones are folded into adults_going/kids_going party sizes. It also discloses that the public RSVP link is only returned after publication.

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 triggering scenario, then metric semantics, then prerequisite, then the sibling alternative. Six tight sentences with no filler; every clause carries information the agent needs.

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?

An output schema exists so return structure needn't be explained, yet the description still defines what the returned counts mean (party-size inclusion, active-only scope, single-count rule), which is exactly the context needed to interpret the numbers 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, and the description goes beyond it by warning that event_id is the event's id, not a guest invitation_id, and by pointing to lemonvite_list_invitations as the source. It does not add format/syntax detail, but the disambiguation is genuinely useful.

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 ('counts how many guests are going, declined, maybe or have not replied') and explicitly disambiguates from lemonvite_list_guests ('To see which guest said what'). An agent can select it 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?

It gives a concrete triggering user question, names the alternative tool and the condition that selects it, and states the prerequisite for obtaining event_id from lemonvite_list_invitations. When-to-use, when-not, and alternative are all present.

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?

Far exceeds the annotations (destructiveHint/idempotentHint/readOnlyHint). It discloses per-item failure semantics ('already-invited contacts fail alone'), the guest_limit interaction, and atomic whole-call failure on published phone overages ('none of its guests saved'), plus immediate-invite behavior on published invitations and the credit/SMS-consent obligations.

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 trigger and example, then layers workflow, limits, and failure modes. It is dense and runs long, but nearly every sentence carries operational information an agent needs; only the credit-flow block is slightly verbose.

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 an output schema present and full schema coverage, the description fully covers the gaps that structure cannot: sibling routing, the contact-vs-guest distinction, limits, partial/atomic failure behavior, and the credit and SMS-consent preconditions. Nothing needed to invoke 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 already 100%, so the schema documents each field. The description still adds meaning by explaining that the tool pulls the saved name/email/phone from the contact rather than the caller supplying them, and clarifies the credit-confirmation semantics tied to authorized_credits and host_confirms_sms_consent.

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 (invite/add) and resource (contacts from the Lemonvite contact list into an invitation's guest list), with a concrete example utterance. It explicitly distinguishes itself from siblings by contrasting with lemonvite_search_contacts (used to find ids) and by likening behavior to lemonvite_add_guests.

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 an explicit trigger ('when the user wants people from their contact list added'), a precondition workflow (find contact_ids with lemonvite_search_contacts first), the correct alternative behavior (never retype name/email/phone), and the follow-up repair path (buy credits with lemonvite_start_checkout, then retry) with the confirmation gate spelled out.

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

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

Beyond the readOnly/destructive annotations, it discloses non-obvious behavior: no paging, unordered results, removed guests excluded, invite_url null until publish, and the filter semantics. These are genuine behavioral facts an agent could not infer from 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?

Purpose and trigger are front-loaded, and nearly every clause carries unique information. It is a single dense paragraph rather than structured lines, which slightly hurts scannability, but there is no filler content.

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 an output schema, it covers everything an agent needs: source of identifiers, filtering, pagination/ordering behavior, nullability, and cross-links to the related sibling tools. Nothing material 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. The description adds meaningful semantics beyond the schema, notably that 'pending' answers 'who has not responded' and that omitting rsvp_status returns everyone, plus tracing event_id back to lemonvite_list_invitations and invitation_id to the update/remove siblings.

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+resource ('see who is on a Lemonvite invitation and how each guest responded') and enumerates the returned fields, so the agent knows exactly what this tool produces. It also explicitly differentiates from the sibling lemonvite_get_rsvp_summary ('For counts only, use... instead').

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 opens with an explicit when-to-use trigger, states the alternative for the counts case (lemonvite_get_rsvp_summary), and explains the rsvp_status filter's effect versus omitting it. It also tells the agent where to source event_id (lemonvite_list_invitations).

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=false and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: no paging, all events returned in one response, upcoming/past split by date, newest-created-first ordering, and differing field payloads per list. That said, some of the per-item field detail overlaps with the separate output schema, so it falls just 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?

Four sentences, front-loaded with the use case before the return-shape detail and the sibling routing. It is dense rather than padded, though the enumeration of returned fields is heavier than strictly needed given an output schema exists.

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 zero-parameter list tool with an output schema, an agent has everything it needs: when to call it, what it returns at a high level, how the results are partitioned and ordered, and which tool to use instead for detail or guest data.

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?

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. There is no parameter semantics to add and the description correctly avoids inventing any.

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+resource (list the account's invitations) and immediately distinguishes itself from siblings by naming lemonvite_get_invitation and lemonvite_list_guests as the tools for detail and guest data. An agent can tell exactly which tool to pick 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?

It opens with an explicit trigger ('when the user wants to find or pick one of their invitations, or when you need the event_id') and closes with clear routing rules to the two alternatives, each with its own condition. This is explicit when/when-not/alternatives 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?

With annotations already flagging destructive/openWorld/idempotent, the description still adds substantial context: it contacts people outside the conversation, costs 1 credit plus one per phone batch, requires host authorization before charges, errors for co-hosts, blocks cancelled events, and is a safe no-op when already published. This exceeds the annotation baseline considerably.

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?

Long but well-organized and front-loaded with the trigger condition and its most important caveat. The payment paragraph is dense, but for a high-stakes outbound-and-billing operation nearly 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?

An output schema exists so return values needn't be explained, and the description fully covers the tool's complexity: triggers, payment flow, credit cost, permissions, and edge cases (co-host, cancelled, already-published). Nothing an agent needs 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% (baseline 3), and the description adds genuine meaning: it explains authorized_credits should be passed only after the host agrees and describes the credit mechanics (1 credit + one per extra phone batch) that the schema's terse note does not fully convey.

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

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

States a specific verb and resource ('invitation made live') and, crucially, describes the actual effect: it opens the RSVP page and delivers the invitation to every pending guest. This lets an agent distinguish it from siblings like lemonvite_update_invitation or lemonvite_create_invitation without opening schemas.

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?

Explicit when-to-use ('when the user explicitly wants their invitation made live'), when-not ('never merely because a draft exists'), and a named alternative for a blocker case (payment_required → lemonvite_start_checkout). It also states prerequisites (read payment_status/required_credits via get_invitation) and constraints (primary host only).

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=true, so the safety profile is covered; the description goes further by disclosing that deletion is permanent and irreversible here, that contacts are not notified, and how unmatched ids surface as not_found. That is substantive context beyond the structured fields.

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: trigger first, input source and limit second, irreversibility plus the sibling exclusion last. No filler and nothing 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?

For a destructive, single-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs: when to call it, what to pass, irreversibility, notification behavior, and the sibling it must not be confused with.

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

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

Schema coverage is 100% and the single parameter is fully documented (1–50 ids returned by lemonvite_search_contacts), so the baseline is 3. The description repeats the max of 50 and the provenance of the ids rather than adding new syntax or format constraints.

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 — deleting people from the Lemonvite contact list (address book) — and explicitly contrasts that scope with invitation guest lists. An agent can distinguish it from lemonvite_remove_guests without opening a schema.

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

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

Gives the trigger condition ('when the user wants people deleted from their contact list') and an explicit exclusion with the correct alternative ('does not take anyone off an invitation's guest list; use lemonvite_remove_guests for that'). It also names the upstream tool that supplies ids.

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=true, but the description goes well beyond them: it discloses the divergent draft (permanent delete) vs published (archive) semantics, that invite links stop working, that guests drop out of counts and RSVP totals, that the host can restore them on the website, the phone-allowance edge case, and that guests are not notified. This is exactly the mutation-impact context an agent 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 trigger condition, then the behavioral consequences, then the sibling routing. Dense and largely waste-free, though the middle sentence stacks several clauses and could be split for faster scanning.

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 mutation, the description covers reversibility, side effects, notification behavior, and input sourcing. An output schema exists, so return-value explanation is correctly omitted. Nothing needed to invoke this safely 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 the baseline is 3; the schema already documents event_id (with its disambiguation from invitation_id) and the 1–50 invitation_ids bound. The description adds only provenance guidance (get ids from lemonvite_list_guests), which is helpful but not a substantive semantic addition.

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 ('guests taken off a Lemonvite invitation') and immediately distinguishes the two operating modes (draft vs published), which an agent cannot infer from the name alone. It is clearly differentiated from lemonvite_add_guests and lemonvite_remove_contacts.

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 names the source of the input ('Get invitation_ids from lemonvite_list_guests') and gives an explicit exclusion plus the alternative: 'Do not remove a guest just to fix their details; use lemonvite_update_guests instead.' That is textbook when/when-not/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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: case-insensitive substring matching, a 50-result cap sorted by name, a total match count, and the scoping fact that only the connected account's own contacts are searched. It stops short of a 5 only because some return-shape detail is duplicated in the output 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 the primary use case, then matching behavior, result limits and scope, with sibling routing at the end. Mostly every sentence earns its place, though the description is on the longer side and the return-limit sentence slightly overlaps the output 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?

Given a single optional parameter, rich annotations and an output schema, the description supplies everything an agent needs: triggers, matching semantics, result limits, fallback behavior when there are more than 50 matches, scope restrictions, and sibling alternatives. Nothing critical 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% and the single 'query' parameter is fully documented in the schema, including that omitting it lists from the top. The description restates the same matching semantics ('matches any part of a contact's name, email or phone, ignoring case') without adding format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (search contacts / address book) and immediately differentiates the tool from siblings by naming lemonvite_invite_contacts, lemonvite_remove_contacts and lemonvite_list_guests. An agent can tell exactly what this does and how it differs from the other contact/guest tools.

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 trigger phrases ('find Alice in my contacts', checking whether a contact is saved) and explicitly names the downstream tools whose inputs it feeds (invite/remove contacts need contact_ids). It also routes the agent elsewhere with 'To see who is on an invitation, use lemonvite_list_guests.' Both when-to-use and when-to-use-something-else 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?

Annotations only supply readOnly=false/openWorld=true/idempotent=false/destructive=false. The description goes well beyond them by disclosing that link creation charges nothing, that Stripe expires an unpaid link after 24 hours, that an abandoned checkout incurs no charge, and that a published invitation's payment_status stays paid.

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 but front-loaded: purpose first, then the no-charge/expiry behavior, then the event_id branching. Every sentence carries operational information, though the paragraph is long enough to be slightly demanding.

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?

An output schema exists, so return-format detail is unnecessary, and the description nonetheless covers the full purchase-to-confirm workflow including post-payment verification and retry steps. Nothing an agent needs to invoke 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 baseline is 3, but the description adds real semantic value: it ties event_id to the draft publishing shortfall and instructs passing publishing_price.credits_to_buy as quantity, and specifies omitting event_id for account credits and guest changes.

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 (start a Stripe checkout link) and enumerates the concrete goods being bought (account credits, publishing, phone guests, design generations). It is clearly distinguishable from all siblings, none of which handle payment.

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 on event_id: use it to buy a draft's publishing shortfall, omit it for account credits or published-event guest changes. States a hard precondition ('Do not call it before the host has seen and agreed to the amount') and names the follow-up siblings (lemonvite_get_invitation, lemonvite_publish_invitation, lemonvite_get_account).

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 flag destructive/openWorld/idempotent; the description adds substantial behavior beyond them: only passed fields change, an empty string destructively clears a field, contact edits don't re-send the invitation but adding first-time contact does on a published invitation, SMS consent gating, and the full payment_required/authorized_credits/checkout recovery path. This is rich mutation-safety context not derivable from structured fields.

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 every sentence carries operational weight, but the passage is dense and the credits/checkout sentence is a run-on that could be trimmed for readability. Still efficiently sized for the tool's complexity.

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?

An output schema exists so return values needn't be explained, yet the description still notes per-guest results and that one failure doesn't abort the batch. Combined with consent and credit/payment flows, an agent has everything needed to call it correctly in edge cases.

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, and the description pushes past it: it explains partial-update semantics, the empty-string-clear convention, the 50-item batch cap, and the conditional requirement for host_confirms_sms_consent and the meaning of authorized_credits (0 = return payment_required without spending).

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 ('fix saved guests on a Lemonvite invitation') with the exact editable fields named (name, email, phone). It explicitly differentiates from siblings by naming lemonvite_add_guests and lemonvite_remove_guests for the adjacent operations.

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 explicit when-to-use ('when the user wants to fix saved guests'), concrete alternatives ('to add new guests use lemonvite_add_guests; to take someone off the list use lemonvite_remove_guests'), and where to source the required invitation_id (lemonvite_list_guests). Nothing is left 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 destructiveHint=true, idempotentHint=true, openWorldHint=true, readOnlyHint=false, so the safety profile is covered structurally. The description adds real value beyond that: the partial-update semantics ('only fields you pass change'), the destructive custom_fields replacement rule with deletion of guest answers, and the published-page propagation with no guest notification. It does not restate annotation fields, so it complements rather than duplicates.

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 trigger and scope, then the critical custom_fields warning, then sibling routing. Every sentence earns its place. Slightly dense, but 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 26-parameter mutation tool with nested objects, the description covers the highest-risk behaviors: partial updates, custom_fields replacement and data loss, published-page timing, and redirect routing. With a 100%-covered schema and an existing output schema, nothing an agent needs to call it safely 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 the schema carries most parameter meaning and the baseline is 3. The description adds semantics the schema does not: partial-update behavior for omitted fields, the replace-and-delete hazard for custom_fields, and the pointer to pass a new invitation_image. It does not, however, cover individual field constraints (timezone format, guest limits), which remain schema-only.

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 (update/change) plus resource (saved Lemonvite invitation) and enumerates the editable surface. It explicitly contrasts itself with lemonvite_create_invitation, lemonvite_generate_design, lemonvite_edit_design, and lemonvite_publish_invitation, so an agent can route correctly without opening schemas.

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 explicit when-to-use ('when the user asks to change a saved invitation'), a when-not ('Do not call it merely to discuss possible changes'), a prerequisite ('read current values with lemonvite_get_invitation first'), and named alternatives for each adjacent intent (create, design, publish). This is the strongest tier of usage guidance.

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