Lemonvite

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

The description discloses that on published invitations, added guests with contact info are invited immediately, while on drafts invitations go out at publish — a side effect an agent must know. It also exposes the SMS consent requirement for phone-number additions, adding real behavioral context beyond the annotations' readOnly/idempotent/destructive hints.

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

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

The description is compact, front-loaded with the core use, and each sentence earns its place — the batching advice, validation rule, publish behavior, and consent condition are all essential. No fluff or redundant restatements.

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 mutating batch operation, the description covers when to use, validation, side effects, and a conditional consent requirement; output schema handles return values and annotations handle idempotency. There are no obvious gaps an agent would need to call it correctly.

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

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

With 0% schema description coverage, the description carries the full burden: it states the per-guest requirement of name/email/phone and explains when host_confirms_sms_consent must be true. event_id is left to the schema/name, but the two non-obvious parameters are meaningfully explained.

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 action — adding one or more people to the guest list of an existing Lemonvite invitation — and contrasts it with brainstorming, making the tool's scope unambiguous. This clearly distinguishes it from creation, removal, and update siblings.

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

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

It explicitly says 'Use this when...' and 'Do not use when the user is merely brainstorming whom to invite,' and it advises a single batched call for multiple guests. It does not name sibling tools like update_guests or remove_guests as alternatives, so it misses full marks for alternative guidance.

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

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

Annotations only include readOnlyHint=false and destructiveHint=false, which are not very informative. The description compensates by stating 'Creates a DRAFT only — it does not publish, charge, or contact anyone', which clarifies non-destructive behavior and side effects. It also notes that if an image is passed, Lemonvite downloads and stores it permanently, which is important behavioral context. Missing details on rate limits or idempotency but given the draft-only nature, this is sufficient.

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 then clarifies boundaries slash use cases. Every sentence adds value: trigger conditions, draft behavior, when not to call, and which fields are essential now. It is long but justified given the 25-parameter surface and need to prescribe usage; no fluff detected.

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 25 parameters and nested objects, the description covers the essential decisions: what is required, what can be deferred, how image handling works, and how this differs from update. The output schema exists, so return value documentation is not needed. The description is complete enough for an agent to invoke correctly without ambiguity.

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

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

Schema coverage is high at 84%, meaning most parameters are described in the schema. The description adds value by emphasizing which fields are required at creation (title, event_type, start_datetime, timezone) and which can be added later, plus special notes like location_name being required for in-person events and host_name needed when account has no display name. This goes beyond the schema's individual descriptions to guide overall usage.

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 creates a Lemonvite invitation from an event plan, listing specific trigger phrases and the key capability of turning an image into an invitation. It distinguishes itself from mere discussion and from the update tool by explicitly mentioning the draft state and pointing to lemonvite_update_invitation for additions. This is a specific verb+resource with clear scope.

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

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

The description explicitly says when to use it (when the user wants an invitation/RSVP page to exist) and when not to (merely discussing wording/images). It also distinguishes from lemonvite_update_invitation by noting that most fields can be added later, and implies that other actions like publishing are separate (lemonvite_publish_invitation). This is explicit and actionable 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?

The description goes beyond annotations by disclosing that each call consumes a design generation credit (starting at 5, +5 per publish credit), that it REPLACES the current artwork (with the old one preserved in history), and that user confirmation is required before calling. This reinforces destructiveHint=true and adds quota and confirmation context.

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

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

The description is information-dense with no filler. It front-loads the core purpose and usage conditions, then systematically covers parameters, side effects, quota, and the alternative. Every sentence contributes actionable guidance, and it is well-structured for an agent to parse.

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, quota-consuming mutation with an output schema, the description covers all essential aspects: when to use, parameter semantics, automatic behaviors, side effects, cost, confirmation requirement, and routing to an alternative. The agent has everything needed to call it correctly and safely.

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 description enriches the schema: it explains that design_brief carries theme/colours/mood/motifs, that event details are lettered automatically unless include_event_details is false, and that reference_image guides style but is not stored as artwork. These clarifications go well beyond the schema descriptions, significantly aiding correct invocation.

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's purpose: it uses Lemonvite's design engine to create invitation artwork. It explicitly differentiates from siblings by noting when to use it (when the assistant cannot produce images or when the user asks for a Lemonvite design) and names an alternative (lemonvite_update_invitation) for attaching existing images.

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?

Provides explicit usage conditions: use it when the user wants the design engine to create artwork, and never merely for design discussion. It also states a clear alternative (lemonvite_update_invitation) when an image already exists in the conversation, giving the agent unambiguous 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, and the description reinforces this with 'Read-only.' It adds useful context about the scope of account information returned (publish credits, design generations), but does not address potential edge cases like missing accounts or authentication failures. The annotation does the heavy lifting, so the description is not underperforming.

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, front-loaded sentence with a clear 'Use this when' trigger, followed by a minimal 'Read-only' note. Every word earns its place, with no redundant information.

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

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

With zero parameters, readOnlyHint set, and an output schema present, the description covers what the agent needs to call and interpret results. It does not include edge-case behavior, but for a simple parameterless read operation the description is complete enough.

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

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

The tool has zero parameters, and schema description coverage is 100%, so no parameter documentation is required. The description adds value by indicating what the returned account object conveys (credits and generation counts), which is sufficient for a parameterless 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 clearly identifies the tool's purpose by listing the exact user intents it serves (connected account, publish credits, design generations). This distinguishes it from siblings focused on invitations and guests, though it does not explicitly name a sibling 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?

It explicitly states 'Use this when the user asks...' and specifies the exact queries that trigger this tool. It lacks explicit exclusions or alternative tool references, but the trigger conditions are clear and sufficient for the agent to 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, so the description's 'Read-only' adds no new information. However, the description does add behavioral context by enumerating what can be reviewed (status, payment state, publication state, guest counts, configuration), which helps the agent understand the scope of the operation. It doesn't disclose return format or error behavior, but the output schema exists to cover that.

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, well-structured sentence that front-loads the trigger condition ('Use this when...') and then lists the specific aspects covered. It ends with 'Read-only' as a concise behavioral qualifier. No wasted words.

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

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

For a simple read-only tool with one parameter and an output schema, the description is largely complete. It clearly states the purpose and scope. The only minor gap is not explicitly stating that event_id is the identifier of the invitation to fetch, but this is easily inferred from the parameter name and the tool's name. The output schema covers return values, and annotations cover safety.

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 0%, so the description must compensate for the single parameter event_id. The description mentions 'a Lemonvite invitation' but does not explicitly explain that event_id identifies the invitation. However, with only one parameter named event_id, the meaning is fairly inferable. The description adds some context by listing what details can be reviewed, but it doesn't directly map event_id to the invitation being reviewed.

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's purpose: reviewing current details, status, payment state, publication state, guest counts, or configuration of a Lemonvite invitation. It uses a specific verb ('review') and resource ('Lemonvite invitation'), and the read-only qualifier distinguishes it from mutation siblings like update_invitation or publish_invitation.

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 says 'Use this when the user wants to review...' which provides clear context for when to invoke it. It doesn't explicitly name alternatives or exclusions, but the read-only nature and the list of reviewable aspects imply when not to use it (e.g., not for modifications). Sibling names like update_invitation and publish_invitation make the boundary clear enough.

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 the description reaffirms 'Read-only' without contradiction. Beyond that, it adds behavioral context about what information the tool provides (attendance counts, statuses), which helps the agent predict the response type even though an output schema exists. This adds value beyond the annotation.

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

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

The description is concise, with the core usage scenario front-loaded, followed by the alternative and read-only note. Every sentence earns its place; no wasted words.

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 are covered. The description covers the primary use cases, the sibling alternative, and read-only nature. It lacks explicit guidance on the event_id parameter, but that is a minor gap given the tool's simplicity and the clear naming convention.

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 schema has a single parameter (event_id) with 0% description coverage. The description does not explain what event_id is, how to obtain it, or any constraints beyond the schema's minLength. Since the coverage is low, the description should compensate but doesn't, leaving the parameter's semantics to inference from the name.

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's purpose: summarizing RSVP responses (who responded, counts of attendees, adults/children, non-respondents) for a Lemonvite invitation. It distinguishes itself from per-guest detail and names the sibling for that purpose, making the scope explicit.

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

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

The description provides explicit when-to-use criteria ('when the user asks who has responded, how many people are attending...') and directly names the alternative tool for per-guest detail (lemonvite_list_guests), with a clear condition for choosing it. No ambiguity remains.

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 the description confirms it is 'Read-only.' Beyond that, it adds valuable behavioral context: it mentions the tool returns personal invite links and party sizes, and that rsvp_status can be used as a filter. This enriches the agent's understanding without contradicting the annotation. The absence of pagination or limit details is a minor gap, so a 4 fits.

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 two sentences, with the primary purpose and included data front-loaded in the first sentence, and the filter usage and read-only note in the second. There is no filler or redundancy; every clause adds useful information.

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

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

Given the simplicity (2 params, one optional enum) and that an output schema exists, the description need not explain return values. It covers the purpose, the filtering behavior, and the read-only nature. It does not mention pagination or error handling, but those are not explicitly required for this straightforward read tool. It is complete enough for an agent to call it correctly, so a 4 is justified.

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 0%, so the description must explain the parameters. It clarifies that event_id refers to a Lemonvite invitation (implicitly the target) and that rsvp_status is a filter, with a concrete example 'who has not responded'. It does not list the enum values, but those are in the schema. For a two-parameter tool, this covers both meanings adequately, earning a 4.

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 (list/see) and resource (guest list of a Lemonvite invitation), and enumerates the included data: per-guest RSVP status, party sizes, and personal invite links. It is clearly distinct from siblings like get_invitation or get_rsvp_summary, which focus on the invitation itself or aggregated counts, and it even gives a concrete filtering use case ('who has not responded').

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 says 'Use this when the user wants to see the guest list' and provides a filtering example, giving clear context for when to invoke it. However, it does not name any alternative tools or explicitly state when not to use it (e.g., if a summary is needed, use get_rsvp_summary). This is clear context but lacks exclusions, so a 4 is appropriate.

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 read-only behavior is already provided by the readOnlyHint annotation, so the description's 'Read-only.' adds no new information. The phrasing does add minor context about account-scoped invitations and event identification, but it does not disclose any further behavioral details like filtering or listing characteristics.

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 one front-loaded sentence and is easy to scan. The final 'Read-only.' is somewhat redundant with the annotations, but the overall text remains efficient and appropriately sized for a simple parameterless 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?

Given zero required parameters, read-only annotations, and an output schema, the description is sufficient: it states the primary user intent and scope. It does not underexplain the return value because the output schema can carry that. The main missing nuance is a more explicit note on the invitation set or scope boundaries, but that is minor here.

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 coverage, so there are no parameter semantics to document. The description correctly matches a parameterless list/review operation, and since there are no parameters, the description does not need to compensate for schema gaps.

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 makes the tool's purpose clear: find or review the user's Lemonvite invitations and identify which existing event is being referenced. It differentiates well from get_invitation by emphasizing the plural 'invitations' and the review/identification use case, though it does not explicitly contrast sibling 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 explicitly starts with 'Use this when...' and names concrete user intents: finding/reviewing invitations or identifying a referenced event. It gives clear usage context but no exclusions or explicit alternatives, so it stops short of a strong 5.

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

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

The description discloses critical behavioral traits beyond annotations: it consumes a publish credit, contacts people outside the conversation (sends emails/phone invitations), and is a safe no-op on already-published invitations. It also warns about the external contact side effect. This goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) and provides essential context for an agent.

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 concise and front-loaded with the core action and its most important side effect (consumes credit, contacts guests). It then provides conditional guidance and a safety note. Every sentence earns its place, and the structure is logical: action, consequences, when-to-use, alternative, and edge case.

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's complexity (side effects, credit consumption, external contact), the description is complete. It covers the main action, prerequisites (payment_status), edge cases (already published), and the critical warning about contacting people. The output schema exists, so return values don't need to be described. The only minor gap is not explicitly defining event_id, but the context makes it unambiguous.

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 schema has only one parameter, event_id, with no description (0% coverage). The description doesn't explicitly explain event_id, but the tool's purpose makes it obvious that event_id identifies the invitation to publish. Since there is only one parameter and the context is clear, the description compensates adequately, though it could have explicitly stated 'event_id is the invitation's ID.'

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's purpose: making a Lemonvite invitation live, consuming a publish credit, making the RSVP page accessible, and delivering invitations to guests. It distinguishes itself from siblings like lemonvite_start_checkout and lemonvite_update_invitation by specifying the publish action and its effects.

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 says when to use this tool: when the user explicitly wants the invitation made live and sent. It also provides a clear exclusion: if payment_status is payment_required, use lemonvite_start_checkout first. It warns against calling it merely because a draft exists, and notes that calling on an already-published invitation is a safe no-op. This is excellent guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, so the description has lighter burden. It adds genuine transparency by disclosing that removed guests' invite links stop working, reinforcing what removal actually does.

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 three short sentences with no filler. It front-loads the use condition, then gives a behavioral consequence and a parameter source, so every sentence earns its place.

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

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

For a two-parameter destructive tool with annotations and an output schema, the description covers when to use, what happens to invite links, and how to find the needed identifiers. It lacks only fuller coverage of event_id and explicit alternative routing to sibling tools.

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

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

With schema description coverage at 0%, the description must compensate for parameter meaning. It explains that invitation_ids can be found via lemonvite_list_guests, but it does not explain event_id beyond a general reference to a Lemonvite invitation.

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 that this tool removes one or more guests from a Lemonvite invitation and explicitly notes that removed guests' invite links stop working. It distinguishes the intent from sibling tools like add_guests and update_guests by emphasizing 'actually removed'.

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 direct trigger condition: use when the user wants guests actually removed. It also routes to lemonvite_list_guests to find the required invitation_ids. It does not explicitly warn against using this for non-removal updates, but the condition is clear.

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

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

Annotations indicate no readOnlyHint (write op), no idempotency, no destructive hint. The description adds that the tool creates a secure Stripe link, does not charge, and that payment credits appear automatically. It also mentions the post-condition (payment_status becomes credit_available) which is not in annotations, adding valuable context beyond what annotations provide. However, it doesn't mention potential failure modes or what happens if the user cancels, leaving a slight gap.

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

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

The description is three sentences, concise and informative. It front-loads the primary purpose and usage condition, then explains the behavior and follow-up steps. No redundant phrasing or filler; every sentence earns its place. The tone is direct and action-oriented.

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?

The tool has an output schema and annotations, which reduces the description's burden. The description covers the trigger condition, the action, the non-charging aspect, and the follow-up verification step. It doesn't explain the full output schema (but that's provided separately) nor does it cover edge cases like what happens if payment fails. Given the output schema exists, the missing failure behavior is a minor gap, so a 4 is appropriate.

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% for both parameters (event_id and quantity) with descriptions. The description adds minimal extra meaning: it implies event_id is for the invitation being purchased and quantity relates to publish credits, but these are already explicit in the schema. The description doesn't clarify the relationship between quantity and pricing or any constraints beyond schema (e.g., max quantity per event), so it adds little 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?

The description explicitly states the verb ('start checkout'), resource ('Lemonvite invitation'), and the specific use-case (when payment is required to publish and user wants to proceed). It distinguishes itself from related sibling tools like lemonvite_publish_invitation by making clear it creates a checkout link, not the actual publication. This avoids ambiguity with the publish 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?

Provides explicit guidance on when to use (when payment is required and user wants to proceed) and what to do after (verify with lemonvite_get_invitation, check payment_status). It also clarifies what the tool does NOT do (does not charge the user), setting expectations clearly. No exclusion of alternatives is needed since this is a unique step in a workflow.

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

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

Annotations already signal that this is a non-read-only, idempotent, destructive mutation. The description adds useful row-level semantics: only the provided fields change, so omitted values are left untouched. This is beyond the annotation metadata and helps the agent understand partial-update behavior.

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

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

The description is compact and front-loaded with the purpose. Every sentence contributes value: when to use it, what can be changed, multiple-in-one-call capability, the partial-update behavior, and a pointer to list_guests. 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?

Given the output schema, annotations, and sibling tool listing, the description is operationally sufficient for a straightforward update tool. The main gap is that event_id is a required parameter but not explained in the description, and the consent nuance is only in the schema; still, the pointer to list_guests and the reference to invitation IDs keep the agent from being fully lost.

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 description clarifies that multiple guests can be updated at once and maps fields to name, email, and phone, partially compensating for the schema's low 33% coverage. However, event_id is not explained, and host_confirms_sms_consent is only described in the schema, so the description does not fully carry the semantic load for all three parameters.

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

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

The description states a specific action — correct or change saved guests — and names the exact attributes affected (name, email, phone). Because it says 'correct or change saved guests,' it is clearly distinct from adding, removing, or listing 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?

It explicitly scopes when to use the tool ('when the user wants to correct or change saved guests') and tells the agent where to find invitation_ids with lemonvite_list_guests. It does not explicitly exclude use cases like adding or removing, but the trigger condition is clear enough to 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds patch semantics—'only the fields provided change; omitted fields keep their saved values'—which informs how all parameters behave, something annotations alone do not convey. It also tells the agent that replacing the invitation graphic requires passing a new invitation_image, but it does not discuss auth or rate limits, so a 5 is not warranted.

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 two sentences: the first states use cases and the target resource; the second explains the patch model and warns against casual use. Every sentence carries weight, and there is no filler or repetition 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 25 optional parameters, an output schema, and 84% schema coverage, the definition is still sufficiently complete. It states the patch behavior, the image replacement convention, and the distinction from merely discussing changes. A minor gap is that it does not explicitly summarize 'null clears fields', but each individual parameter's schema description covers that and it is not a blocker.

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

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

With 84% schema description coverage the baseline is 3. The tool description adds value by articulating that omission preserves saved values, which is the most important behavior of every update-specific parameter, and it clarifies that a new invitation_image is the way to update artwork. It does not repeat the constraints or enums already documented in the schema.

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

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

The description states a specific verb and resource: 'change the details of an existing Lemonvite invitation' and gives concrete examples such as title, description, time, location, host information, RSVP settings, and invitation graphic. Using the word 'existing' clearly distinguishes it from the create_invitation sibling. The closing instruction 'Do not use this merely to discuss possible changes' further narrows the intended trigger.

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 phrase and a when-not-to-use clause: 'Use this when the user wants to change the details...' and 'Do not use this merely to discuss possible changes.' This is solid routing guidance, but it does not name alternative siblings such as lemonvite_create_invitation for creating new invites, so it stops just short of a 5.

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