Lemonvite

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

Annotations only declare the mutation/safety profile; the description adds substantial context beyond them: nobody is messaged, matching/dedup by email or phone, the name-only re-save exception, the atomic 2000-contact cap failure, and per-contact validation failure isolation. The idempotentHint=false annotation is consistent with the stated re-save behavior, not contradicted.

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 densely packed with no filler; it is front-loaded with the when-to-use rule before the mechanics. Each sentence carries a distinct constraint (routing, batch size, validation, dedup, cap), though slightly more could be tightened.

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 explained, and the description still covers limits, atomicity, side effects, validation behavior, and dedup rules. Nothing an agent needs to call this correctly is absent.

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 field formats are already documented, but the description adds real meaning: the 1-50 batch constraint, the requirement of at least name/email/phone, and the dedup key semantics. These go beyond the structured schema without fully compensating for anything missing.

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)') and immediately distinguishes the tool from siblings by name. An agent can separate saving contacts from inviting guests 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?

Gives an explicit trigger ('when the user wants people saved... without inviting them to an event now') and names the alternatives for the contrasting case ('to invite people, use lemonvite_add_guests or lemonvite_invite_contacts'). Both when-to-use and when-not-to-use 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 flag destructive/openWorld/non-idempotent; the description goes far beyond them, disclosing draft vs published invite timing, SMS-consent prerequisites, guest_limit enforcement, the payment_required failure mode that saves none of the guests, per-guest independent results, and that purchased credits are shared with publishing so no further charge applies.

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

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

Information is densely front-loaded with the when/when-not clause and batching instruction first. It is long and packs several distinct flows (consent, limits, credits, retry) into one paragraph, so it is efficient but borders on overloaded.

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 four parameters, an output schema, and destructive annotations, the description covers everything an agent needs: prerequisites, failure semantics, credit flow, and follow-up tools. Return values are left to the output schema, as intended.

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; the description adds meaning beyond it by explaining that authorized_credits is a host-confirmed spend cap and that newly bought credits are shared with publishing, and by restating the min-contact rule for each guest.

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 actually added to the guest list of an existing Lemonvite invitation') and immediately differentiates from the near-neighbor scenario of brainstorming invitees. It also names the sibling to use for modifications (lemonvite_update_guests), so an agent can separate it from update/list/remove tools 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 (user wants people added) and when-not (brainstorming), plus concrete batching rules ('whole list in one call of up to 50 guests, not one call per guest'). It routes to specific alternatives: lemonvite_list_invitations to obtain event_id, lemonvite_start_checkout to buy credits, lemonvite_update_guests to fix existing 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?

The description adds high-value behavior beyond the annotations: 'It creates a DRAFT only and does not publish, charge, or contact anyone.' It also discloses failure behavior ('nothing is created and the error names the field'), which is important for an agent deciding how to recover. This is genuinely useful context that the plain boolean hints do not provide.

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 dense but every sentence earns its place: trigger condition, draft-only caveat, negative trigger, required fields, error behavior, and next steps all flow in a logical order. No filler or redundant restatement of 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?

Given the rich schema and output schema, the description covers everything an agent needs to decide when to call the tool, what minimal fields to provide, what failure looks like, and what to do afterward. The only remaining details belong to the schema itself, which is appropriately left there.

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 value by identifying the minimal required parameter set, calling out the conditional requirement for location_name on in-person events, and explaining how to map a conversation image to invitation_image. This is meaningful guidance for a 26-parameter tool, though the schema already does most of the semantic work.

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: creating an actual Lemonvite invitation/RSVP page, and lists concrete triggers ('create an invitation, make an invite, set up RSVPs'). It also distinguishes itself from related work by warning 'Do not call it merely because invitation wording or images are being discussed' and by pointing to lemonvite_update_invitation, lemonvite_add_guests, and lemonvite_publish_invitation for later steps.

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 explicitly says when to use the tool ('when the user wants an actual Lemonvite invitation or RSVP page'), when not to use it ('merely because invitation wording or images are being discussed'), and names the sibling alternatives for follow-up actions. It also gives a clear next-step sequence: add guests, publish, and checkout when payment is required.

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 indicate destructive=true and readOnly=false; description elaborates with specifics: spends one design generation, REPLACES current artwork, previous version remains in history, and constraints (no GIF, no text/image layers). Adds substantial behavioral context beyond annotations with no contradiction.

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?

Description is long but every sentence carries essential information: usage trigger, constraints, cost, confirmation, and alternative pathways. Front-loaded with the primary usage condition. Minor redundancy with annotations but overall well-structured.

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

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

Covers all critical aspects: destructive nature, cost (design generation), prerequisites (existing non-GIF artwork without layers), confirmation requirement, source for event_id, and alternatives. With an output schema present, return format is handled. Nothing an agent needs to invoke 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 already fully documents both parameters (100% coverage), so baseline is 3. Description adds value by instructing to put the request in user's own words and not rewrite into a design brief, effectively clarifying the intended content of edit_request beyond 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?

Description states specific verb 'edit' and resource 'current artwork', with concrete examples and explicit contrast to generating a new design. It clearly distinguishes from sibling lemonvite_generate_design while naming the alternative.

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 says when to use ('change to CURRENT artwork rather than a new design'), when not to use (GIF or layered artwork), and names alternatives (lemonvite_generate_design for from-scratch, invitation_image via update_invitation for attaching images). Also instructs to confirm before calling and how to get event_id.

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 mark destructiveHint=true, and the description adds concrete behavioral context: each call spends one design generation, replaces current artwork, keeps earlier designs in history, and reference_image is not stored as artwork. It also discloses credit economics for new accounts. No contradiction with 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 dense but every sentence earns its place: purpose, exclusions, parameter guidance, behavioral consequences, and alternatives are all present. It front-loads the core purpose and never repeats schema boilerplate.

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, credit-costing tool with nested parameters and sibling overlap, the description fully covers invocation conditions, parameter semantics, side effects, and alternatives. The presence of an output schema means return-value detail is not required, and nothing necessary for correct invocation 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 the description still adds meaning: design_brief should be art direction and need not repeat auto-lettered event details; include_event_details defaults true and false only for artwork without details; reference_image guides style/subject/palette and is not stored; event_id is explicitly distinguished from guest invitation_id and 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 and resource: Lemonvite's design engine creates invitation artwork. It explicitly distinguishes from siblings by naming lemonvite_edit_design for changing artwork and lemonvite_update_invitation for attaching assistant-made images, so an agent can select correctly.

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 conditions: user wants a Lemonvite design, assistant cannot make images, or user asked for a Lemonvite design. It also gives a negative rule ('Never call it merely because designs or themes are being discussed') and names alternatives for related but distinct actions, including edit_design and update_invitation.

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 mark this as readOnly and non-destructive, but the description goes further by explaining the semantics of credits and generations_remaining, including that credits are a shared balance, publishing uses one credit, extra phone-guest batches use additional credits, and generations_remaining does not reset over time. This is valuable behavioral context beyond the annotations.

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

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

Every sentence earns its place: trigger conditions, credit semantics, generation semantics, the credit-to-generation conversion, and related tool routing. The most important usage guidance is front-loaded, and 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?

For a zero-parameter account status tool with an output schema, the description is complete. It explains both key output fields, their relationship, non-resetting behavior, and related tools for actions like adding credits or checking invitation requirements. No important context 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?

The tool has zero parameters and 100% schema description coverage, so the baseline is 4. The description adds meaning to the output fields (credits and generations_remaining) rather than input parameters, which is appropriate for a zero-parameter read-only account tool.

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 explicit trigger conditions: which account is connected, how many credits it has, or how many design generations are left. It names the resource (Lemonvite account) and the specific fields, clearly distinguishing it from generation, invitation, and checkout 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?

The description gives explicit when-to-use guidance and points to alternatives: lemonvite_start_checkout for adding credits and lemonvite_get_invitation for invitation-specific required_credits. It also clarifies how generations_remaining relates to lemonvite_generate_design and lemonvite_edit_design, so an agent can route correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: co-hosts can read it, and it returns payment/publication status and credits needed to publish. It could mention potential errors or response format, but the output schema covers that. No contradictions with 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 a single long sentence but is front-loaded with the primary purpose and then packed with useful routing and usage context. It avoids fluff and every clause adds value. Slightly verbose but not redundant.

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 tool has an output schema and annotations, the description need not repeat return details. It covers when to use, what it returns, how to obtain the parameter, and how it relates to sibling tools. Nothing essential is missing for an agent 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% and the parameter description already clarifies that event_id is not a guest invitation_id or RSVP URL. The description adds cross-tool guidance ('Get event_id from lemonvite_list_invitations') which aids retrieval. While not strictly necessary, this additional context earns above the baseline 3.

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

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

The description clearly states the tool retrieves the full current state of a Lemonvite invitation, enumerating specific fields (details, publication/payment status, credits, guest/RSVP counts, custom fields, guest settings). It also distinguishes itself from sibling tools by specifying what it is not (e.g., not for guest responses or RSVP summaries). This is a specific verb+resource with strong sibling differentiation.

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 explicitly instructs when to use this tool ('Use this when the user wants the full current state'), provides an alternative for obtaining event_id, and gives clear exclusions: use lemonvite_list_guests for per-guest responses, lemonvite_get_rsvp_summary for counts alone, and check payment_status here before calling lemonvite_publish_invitation. This is thorough and leaves no ambiguity about 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?

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: counts are read live, cover only active guests, remove excluded guests, count each guest once, and include plus-ones in party-size totals. It also discloses the conditional behavior around returning the public RSVP link only once the invitation is published, which the annotations do not 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 description is front-loaded with the primary use case and then delivers dense, relevant detail in a compact space. Every sentence earns its place: usage criteria, live count semantics, party-size calculation, link behavior, parameter source, and the sibling alternative. There is no redundant filler.

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

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

For a tool with one well-documented parameter, a read-only annotation profile, and an output schema, the description is complete. It covers when to use it, how to obtain the event_id, what the counts mean, the edge case around plus-ones, and when the RSVP link appears, leaving no practical gap for an agent invoking the tool.

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

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

Schema description coverage is 100%, and the input schema already documents event_id as the Lemonvite event identifier, not a guest invitation_id or RSVP URL. The tool description restates this guidance, adding marginal clarity but no genuinely new parameter semantics beyond what the schema provides, so the high-coverage baseline of 3 applies.

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

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

The description names a specific resource (Lemonvite RSVP summary) and the exact queries it answers: how many guests are going, declined, maybe, have not replied, or how many adults and children are coming. It also distinguishes itself from lemonvite_list_guests by stating that this tool returns counts, not per-guest details.

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 states when to use this tool ('when the user asks how many guests are going...') and names the alternative for a different need ('To see which guest said what, use lemonvite_list_guests instead'). It also tells the agent where to obtain the required event_id, making the routing and prerequisites clear.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description adds substantial operational detail beyond them: the 50-contact cap, that already-invited contacts fail alone, guest_limit enforcement, all-or-nothing payment_required on published phone overages, immediate invitation on published events, and the SMS-consent gate. This is exactly the kind of failure-mode disclosure that helps an agent call safely.

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 most important routing information (when to use, search first) is front-loaded, and the error/credit/SMS handling follows logically. It is dense and slightly long, with a couple of details that echo the schema (the 50-contact limit), but nearly every sentence carries operational 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?

For a destructive, credit-consuming, multi-step tool, the description covers prerequisites, error semantics, credit/consent workflow, and side effects. Since an output schema exists, return values need not be re-explained, and 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 the schema already documents each parameter (baseline 3). The description adds value beyond it by explaining that the saved name/email/phone are pulled from the contact and must not be retyped, and by describing the authorized_credits retry workflow and host_confirms_sms_consent trigger condition.

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: adding people from the Lemonvite contact list to an invitation's guest list, with a concrete example. It clearly distinguishes this tool from siblings like lemonvite_add_guests and lemonvite_search_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?

It opens with an explicit when-to-use trigger, mandates lemonvite_search_contacts as the source of contact_ids, and explains the relationship to lemonvite_add_guests. It also routes the credit shortfall case to lemonvite_start_checkout with the exact conditions (no event_id, retry with authorized_credits after host confirmation).

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 signal read-only, but the description adds non-obvious behavior: every active guest is returned in one response, there is no paging, ordering is unspecified, removed guests are excluded, and invite_url stays null until publication. These are behavioral caveats an agent could not infer from the schema or annotations. There is no contradiction.

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 dense at around 140 words, but every sentence earns its place: scope, response behavior, publish caveat, filtering behavior, ID sourcing, downstream tool IDs, and alternative routing. The primary use case is front-loaded, with caveats and routing details following naturally. No filler or redundant restatement of the schema.

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

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

With an output schema present, the description does not need to re-enumerate return fields. It covers input sourcing, filter semantics, important behavioral caveats, and the alternative tool for counts, which is everything an agent needs to call it correctly. The description is complete for a read-only list operation of this complexity.

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 already high, and the description adds meaning beyond it: it tells the agent where to obtain event_id and interprets rsvp_status=pending as 'who has not responded'. It also explains that omitting rsvp_status lists everyone, which reinforces the schema without restating enum definitions. This is modest but useful added value.

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 leads with a specific use case: seeing who is on a Lemonvite invitation and how each guest responded, then enumerates the returned fields. It clearly distinguishes itself from siblings by describing itself as a guest-listing operation and even points to the count-summary alternative. It is not a tautology of the title and gives an agent enough to identify the right tool.

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 explicitly says when to use the tool ('Use this when the user wants to see who is on a Lemonvite invitation...') and when not to ('For counts only, use lemonvite_get_rsvp_summary instead'). It also provides operational routing: get event_id from lemonvite_list_invitations, and note that each guest's invitation_id is what update/remove tools consume. This is strong guidance for tool selection and sequencing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read profile is clear. The description goes further by disclosing non-paginated single-response behavior, split into upcoming/past, newest-first ordering, and the differing field sets for each category. This is rich behavioral context that the annotations do not provide.

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 with the primary usage, followed by a compact breakdown of return structure and field details, and ends with explicit routing to sibling tools. Every sentence contributes a distinct, necessary piece of information; there is no filler.

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

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

For a zero-parameter tool with an output schema, the description fully covers what an agent needs: what triggers the call, what comes back, how it's organized, and where to go for deeper detail. The absence of pagination is called out, and the field-level differences between upcoming and past items are specified. Nothing 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?

The tool has zero parameters, and the schema coverage is 100% (vacuously). Per the baseline for 0-param tools, a 4 is appropriate since description adds nothing about parameters, but nothing is needed. It does mention what the returned data contains, which indirectly aids understanding of what can be used.

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 ('find or pick... Lemonvite invitations') and precisely scopes the result set ('every event the connected account created or co-hosts'). It explicitly differentiates itself from lemonvite_get_invitation and lemonvite_list_guests, leaving no ambiguity about which tool to choose.

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 the exact trigger condition ('when the user wants to find or pick one of their Lemonvite invitations, or when you need the event_id...') and then names the alternatives for full details and guests. This gives an agent explicit when-to-use and when-to-use-other 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 provide the safety profile (not read-only, open-world, destructive, idempotent), and the description meaningfully expands on it: it discloses the external-contact side effect ('contacts people outside this conversation'), the cost model (1 credit plus one per extra phone batch), that calling on an already-published invitation is a safe no-op, and the permission boundary for co-hosts. Nothing contradicts the annotations.

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

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

Despite being long, every sentence carries load-bearing guidance: when to use, when not to, prerequisite reads, cost, payment fallback, permissions, edge cases. The main intent is front-loaded in the first sentence and the structure follows the execution order an agent would need. For a paid, externally-sending side-effecting action, the density is justified with zero 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 an output schema present and both parameters fully documented, the description covers everything an agent needs to call it correctly: triggers, prerequisites, pricing, checkout path, permission restrictions, cancelled-event handling, and idempotent no-op behavior. Nothing an agent would need to ask about 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 genuine semantic value beyond the schema: it explains the credit pricing that determines authorized_credits, instructs that authorized_credits should only be passed 'after the host agrees' and after explaining extra charges, and ties event_id into the checkout fallback flow (pass it to lemonvite_start_checkout). This goes beyond the field-level descriptions already present.

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 title and description state a specific verb and resource: 'Publish an invitation' means taking it live, opening the RSVP page, and DELIVERING it to guests with pending email or phone invitations. This distinguishes it clearly from siblings like lemonvite_create_invitation, lemonvite_update_invitation, and lemonvite_edit_design — an agent can tell exactly what action this triggers.

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

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

The description gives an explicit when-to-use ('only when the user's intent to go live and send is clear, never merely because a draft exists'), names the prerequisite flow (lemonvite_get_invitation to read payment_status, required_credits, publishing_price), and names the exact alternative for the payment_required case (lemonvite_start_checkout with event_id). It even states who cannot use it (co-hosts get an error) and which events are excluded (cancelled).

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, and the description adds substantially beyond them: deletion is permanent and not undoable, contacts are not notified, unmatched ids land in not_found, and guest lists are unaffected. This is exactly the kind of consequence disclosure a destructive 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 trigger, then constraints, then the sibling exclusion — a sensible order. It is dense with semicolon-joined clauses, but essentially every clause carries unique information, so it stays close to 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?

An output schema exists, so return-value explanation is not needed; the description covers trigger, ID source, permanence, notification behavior, unmatched-id handling, and sibling routing. Nothing an agent needs to invoke this destructive tool 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 the single parameter is well documented, so the baseline is 3. The description still adds real value by naming the origin of the ids (lemonvite_search_contacts) and the not_found behavior for unmatched ids, which the schema does not state.

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 deleted from their Lemonvite contact list (address book)') and explicitly distinguishes itself from the nearest sibling by stating it does not touch invitation guest lists. An agent can differentiate it from lemonvite_remove_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?

Opens with an explicit trigger ('Use this when the user wants people deleted...') and names the alternative with its selecting condition ('use lemonvite_remove_guests for that'). It also routes the agent to lemonvite_search_contacts as the ID source, so both the when and the from-where 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?

The description goes well beyond the annotations, detailing permanent deletion on drafts, archiving on published invitations, invite links stopping, guest counts and RSVP totals dropping, host restoration on the website, phone-guest allowance behavior, and lack of guest notification. No annotation is contradicted; in fact, the description reinforces the destructiveHint.

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 with the primary use case and then packs high-value behavioral details, source guidance, and an exclusion into a compact set of sentences. Every sentence earns its place, and there is no redundant restatement of the tool name or 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?

Given the destructive nature, the tool supplies all necessary side effects (deletion vs. archive, counts, restoration, phone allowance, notification), a source for IDs, and an explicit alternative for a related but different action. An output schema exists, so return-value details are not required in the description.

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 provenance for invitation_ids by instructing callers to get them from lemonvite_list_guests, and it explains the consequence that removed guests' invite links stop working, enriching the schema's 'these guests are removed' note.

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 ('remove') and resource ('guests from a Lemonvite invitation'), and it differentiates from the sibling lemonvite_update_guests by explicitly warning not to use removal for detail fixes. It also clarifies the draft vs. published distinction, making the tool's purpose unmistakable.

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 ('Use this when the user wants guests taken off'), tells the caller where to source invitation_ids ('from lemonvite_list_guests'), and names the alternative tool for fixing details (lemonvite_update_guests). This leaves no ambiguity about when it applies versus its siblings.

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 safety is covered. The description adds real behavioral context beyond that: the search scope is limited to the connected account's own contacts, results cap at 50 sorted by name plus a total match count, and it advises how to handle overflow. It stops short of richer detail but the added value is genuine.

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 use cases before mechanics (matching behavior, result cap). Every sentence carries information, though the paragraph is dense and slightly long for a single-parameter tool.

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

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

An output schema exists, so return shape need not be described, yet the description still communicates the cap, ordering, and total count that matter for deciding whether to re-query. Combined with annotations and full schema coverage, an agent has everything needed to 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: matching is case-insensitive and the query may be omitted to list contacts from the top. These are useful selection hints for an agent deciding how to construct the call.

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 in the Lemonvite address book') and immediately scopes it with three concrete intents (find someone, check if saved, get contact_ids). It is clearly distinguishable from siblings like lemonvite_list_guests, which it explicitly names as the alternative.

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 says when to use it (user refers to people in their contact list) and routes to alternatives by name: lemonvite_invite_contacts and lemonvite_remove_contacts for downstream use of contact_ids, and lemonvite_list_guests for invitation rosters. No inference required.

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 provide readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds genuine value beyond these: 'creating the link charges nothing', 'Stripe expires an unpaid link after 24 hours', 'an abandoned checkout charges nothing', and the guarantee that a published invitation's payment_status stays paid. These are non-obvious side effects an agent could not infer from the schema or 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?

Front-loaded with the core purpose, and every sentence is functional across the two operational modes and safety constraints. It is long, but the length is earned by genuine complexity; it could be tightened into structured bullets but contains 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?

Given two operational modes, integration with three sibling tools, payment-side effects, and safety constraints, nothing an agent needs to call it correctly is missing. The output schema exists, so return values need not be explained, and post-payment verification steps are specified in detail.

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 already covers both params at 100%, so baseline is 3. The description adds value above that: how to derive quantity (pass publishing_price.credits_to_buy), the server-rejecting-changed-shortfall behavior, and the mode-dependent interpretation of event_id. This exceeds the schema, though it doesn't fully restate parameter formats.

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 ('start checkout', 'buy account credits') and the exact triggers (publishing, extra phone guests, design generations). It distinguishes itself from sibling tools by inlining the follow-up workflows (lemonvite_get_invitation, lemonvite_publish_invitation, lemonvite_get_account), so an agent can separate checkout from the other 14 tools 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?

Exceptionally explicit: states when to use (host buying credits), when NOT to call (before the host has seen and agreed to the amount), and fully splits the two modes (with event_id vs. omitted). It names the exact sibling calls to make after payment and the retry/authorization behavior, leaving no ambiguity about selection.

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 readOnly=false, and the description earns its keep with non-obvious behavior: partial-update semantics (only passed fields change, empty string clears), per-guest independent results so one failure doesn't stop the batch, invitation re-send rules on published invitations, the SMS-consent requirement, and the credits/payment_required path.

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 opening is front-loaded with the trigger and the batch/partial-update rules before the more specialized payment and consent conditions. It is dense and long-ish, but nearly every sentence carries operationally necessary information; the credit-retry sentence is the only slightly heavy passage.

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

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

A mutation tool with an output schema, so return values need not be described. All decision-relevant behavior (identity source, batch limits, consent and credit gates, sibling routing) is present; 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 already 100%, so the structured fields carry the parameter detail; the description rises above baseline by tying parameters to workflow (authorized_credits is only set after the host agrees, host_confirms_sms_consent is required when adding a phone to a guest who had none) and by mapping invitation_id back to lemonvite_list_guests.

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 ('fix saved guests on a Lemonvite invitation') and enumerates the mutable fields (name, email, phone). It explicitly distinguishes itself from the add and remove siblings in the final sentence, 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?

Gives explicit when-to-use triggers, names alternatives ('To add new guests use lemonvite_add_guests; to take someone off the list use lemonvite_remove_guests'), and covers edge-case routing such as the payment_required flow and the lemonvite_start_checkout fallback for a credit shortfall.

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=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds crucial behavioral context beyond those flags: partial-update semantics (omitted fields keep saved values), the destructive replace behavior of custom_fields (a saved field left out is deleted with its guest answers), the fact that published invitations update on next page load without notifying guests, and the requirement to pass existing field_ids. This is rich, non-obvious behavioral disclosure that materially changes how an agent should call the tool.

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

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

The description is a single dense paragraph that front-loads the core purpose and usage condition, then packs the most important behavioral warnings (partial update, custom_fields replacement, published page behavior) before the sibling routing. Every sentence earns its place; there is no filler or repetition of schema 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 26-parameter mutation tool with a full output schema and 100% schema description coverage, the description covers the essential operational context: when to use it, what changes, what doesn't, the destructive custom_fields behavior, published-invitation visibility, and which siblings handle other intents. The output schema exists, so return values need no explanation. 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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the overall partial-update model ('Only the fields you pass change; omitted fields keep their saved values') and by highlighting the custom_fields replace semantics and the need to read current values first. It also clarifies the invitation_image parameter as 'pass a new invitation_image' for artwork changes. The description doesn't enumerate every parameter, but the schema already covers them thoroughly, so the added semantic layer is meaningful.

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

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

The description opens with a specific verb and resource ('change a saved Lemonvite invitation') and enumerates exactly which fields can be changed, including artwork via invitation_image. It also distinguishes itself from siblings by naming lemonvite_create_invitation, lemonvite_generate_design, lemonvite_edit_design, and lemonvite_publish_invitation as the tools for other intents. An agent can tell exactly what this tool is for.

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

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

The description gives explicit when-to-use guidance ('Use this when the user asks to change a saved Lemonvite invitation'), tells the agent to read current values with lemonvite_get_invitation first, warns against calling it merely to discuss changes, and names the sibling tools for create, design, and publish. This is exemplary routing guidance.

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