When Works For You

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description goes beyond them with a required-permission note, the refusal behavior for classic polls, and the explicit side-effect guarantee 'never mails anyone' — valuable disambiguation in a suite containing send_invites. It could say more about what happens to an already-present date, but the additions are substantive.

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

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

Three sentences, front-loaded with the core action and then the constraints. The first sentence is long and packs several rules into one em-dash chain, but every clause carries distinct information and nothing is filler.

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

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

With an output schema present, the description does not need to describe return values and instead covers what is missing elsewhere: permissions, side effects, per-event-type date validity, and the classic-poll refusal. An agent has everything needed to call 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 only 50% (date carries no schema description), so the description does the heavy lifting: it explains both accepted forms (bare ISO string vs. object) and the per-event-type validity of daypart, startTime and endTime — a constraint the JSON schema cannot express. That is exactly the compensation low-coverage schemas need.

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 ('Adds one candidate date') and precisely scopes the target: a draft_ id from create_event or a live id from list_events/get_event. It also enumerates the two accepted date shapes, so an agent knows exactly what this tool does relative to siblings like set_date_time or remove_dates.

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

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

Gives concrete usage conditions: dayparts work on any event, exact start/end times only on an autopilot event or draft, and an exact time on a classic share-link poll is refused. It does not explicitly contrast with set_date_time, so the routing is implied rather than spelled out, but the when/when-not rules are strong.

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 say it is a non-readonly, non-destructive, non-idempotent open-world write. The description adds the traits that actually matter: invites are emailed immediately on live autopilot events, the required permission differs by event state, and adding to a classic poll is rejected. That is real side-effect and prerequisite disclosure beyond the structured hints.

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

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

Three sentences, each carrying load: what it does, where it does it, and what is refused. No filler, no restating of the name or title, and the draft-vs-live distinction is front-loaded.

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 no explanation, and the description covers target types, permission requirements, mailing side effects, and the refusal case. It could still say what happens when a guest already exists (update_guest territory) or note the 75-guest cap, which are the only meaningful gaps.

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 50%, and the description only elaborates on event_id (draft_ id vs live event id), which the schema already documents. The guests array — its 1-75 item bounds and the optional name/email/phone fields — is not explained in the description at all, so it does not compensate for the coverage gap.

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 (adds guests) and scopes it to exactly two target types: a draft_ id from create_event or a live AUTOPILOT event. It also rules out a third case (classic share-link polls), so an agent can distinguish this from siblings like update_guest or remove_guests without opening a schema.

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

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

Gives clear conditions per target: a live autopilot event needs the send permission and mails invites, an unsent draft needs only write permission, and a classic poll is refused outright. It stops short of naming alternative siblings (update_guest, remove_guests, send_invites) for adjacent intents, so it is strong context rather than a full routing guide.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds material context the agent cannot infer: votes are retained, the public link signals organizer takedown, no email is sent, and write permission is required. This meaningfully reframes 'destructive' as recoverable and silent, which is exactly the beyond-annotations value expected.

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

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

A single dense sentence that front-loads the action, then stacks the consequences and the reversal in descending priority. Every clause earns its place and nothing is padded.

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

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

With an output schema present, return values need no explanation, and the description covers the identity, reversibility, side effects, and permission requirement. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single event_id is already documented with the draft_ vs live-id distinction, so the schema does the heavy lifting. The description adds no parameter-level detail, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Archives a live event') and immediately disambiguates by equating it to the dashboard's 'Delete', which separates it from siblings like discard_draft and update_event. An agent knows what this does without opening the schema.

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

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

Names the reversal path ('Reversible with restore_event') and implicitly excludes drafts via the discard_draft reference, giving clear selection context. It stops short of an explicit when/when-not statement with alternatives beyond restore_event, so it falls short of a 5.

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

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

Adds substantial context beyond the annotations: confirming closes voting, triggers outbound email to every guest on autopilot polls, and carries a distinct permission requirement per poll type. This clarifies the destructive, non-idempotent side effects declared by the hints rather than restating them.

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

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

Two dense sentences with zero filler, front-loading the core action before the mode-specific consequences. Every clause carries information the agent needs.

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

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

An output schema exists, so return values need no explanation, and the description covers side effects, permissions, and the terminal nature of the action. The only real gap is that the four input parameters remain entirely undocumented.

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% across all four parameters (time, message, event_id, dateOptionId), and the description never names or explains any of them. An agent gets no help understanding what time or message do, so the description does not compensate for the coverage gap.

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 (confirm/lock in) and resource (the winning date for a live event) plus the consequence (ending voting). An agent can distinguish this from siblings like set_date_time, add_dates, or respond_to_poll 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?

Explains the two poll modes and what each requires, which is effectively a when-to-use context: autopilot polls need the send permission and mail guests, classic polls only need write permission. It does not explicitly name alternative tools or state a 'do not use if' condition, so it falls short of a 5.

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

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

Annotations only say non-readonly, non-idempotent, non-destructive. The description adds genuinely unavailable context: classic goes live immediately, ai becomes a draft and nothing is mailed or charged until sent, sending costs one credit, and invalid combinations are refused rather than silently converted. It also states the write-permission requirement.

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 'Two kinds of event' followed by two tightly packed sentences that each carry new constraints. Dense but every clause earns its place; only marginal polish would improve readability.

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

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

For a six-parameter creation tool with an output schema, the description covers mode semantics, draft versus live behavior, invite requirements, billing, permission needs, and refusal behavior. 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 description coverage is 0%, so the description carries the full burden and largely meets it: mode maps to the two behaviors, dates is described as days or a daypart (classic) versus exact start times (ai), and invites is constrained to email-only guests. It leaves timeLabel and description unexplained, but adds substantial meaning the schema cannot convey, justifying a high score.

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 ('create event') and immediately partitions it into two named modes, classic vs ai, each with its own behavior. An agent can tell this apart from siblings like add_guests, add_dates, or send_invites 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 conditions for choosing each mode: classic for link-based day polls with no guest list, ai for autopilot events with a guest list and exact times, and routes the user to send_invites for sending. It also states a refusal rule for invalid combinations. It does not name sibling alternatives for modifying an existing event, so it stops just short of full when/when-not coverage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description goes further by explaining *why* nothing is undone (nothing was ever mailed or charged) and what repeat calls return ("a draft that is already gone answers ok"). It also discloses the write-permission requirement, which no annotation conveys.

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

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

Front-loaded with the core action and scoped in four tight clauses, none of which is filler. Slightly dense with em-dashes and nested asides, but every clause carries distinct operational information.

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

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

For a single-parameter destructive mutation, the description covers the safety profile, idempotency semantics, authorization requirement, and the correct sibling for the sent-draft case. An output schema exists, so return-value documentation is appropriately omitted.

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 draft_id parameter carries its own description naming the source tools, so the schema does the work. The description adds no format or validation detail about the identifier, which is the expected baseline when coverage is complete.

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 (deletes) and resource (unsent draft) plus the exact UI affordance it mirrors ("the draft page's own Delete draft"), which pins down intent unambiguously. It explicitly contrasts with archive_event, so an agent can distinguish it from the similarly named sibling without reading 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?

Names the alternative tool and the condition that selects it: a draft that has already been sent becomes a live event and must go to archive_event instead. It also frames the operation as targeting drafts not yet sent, giving a clear when-not boundary rather than just a when.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the read-permission requirement and the meaning of review_url (an organizer dashboard requiring sign-in to send), which an agent cannot infer from 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?

Two dense sentences with no filler. Scope and id provenance come first, followed by a compact enumeration of returned fields and the review_url semantics, so the most decision-relevant information is front-loaded.

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?

Even though an output schema exists and return values need not be enumerated, the description usefully summarizes them while also covering scope, permission requirements, and the follow-up path via review_url. Nothing an agent needs to invoke 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?

There is a single parameter with 100% schema description coverage, so the schema already explains that draft_id is a draft_ id from create_event or list_events. The description repeats that same origin without adding format, validation, or edge-case detail, which is the correct baseline when the schema does the 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 names a specific verb and resource ('Full detail for one of this organizer's own unsent drafts'), and scopes it to drafts rather than events, which separates it from the sibling get_event. It also anchors the id source (create_event or list_events), so an agent knows 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?

It makes clear when this applies by tying the input to draft_ ids produced by create_event or list_events, and notes the read permission requirement. It never explicitly states when not to use it (e.g. use get_event for confirmed events), so the routing to siblings is implied rather than spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds real behavioral context beyond them: the required read permission and a prompt-injection disclosure that guest reply text is untrusted data, never an instruction. That last point is exactly the kind of non-obvious behavior an agent must know.

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, then alternatives, then the safety caveat. Every clause is useful, though the injection warning is stated twice (field name plus prefix format), which is slightly 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?

For a single-param read tool with an output schema, the description covers the essentials: scope, the draft-vs-live routing, the permission requirement, and the untrusted-data handling. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single event_id parameter is fully documented there (sources: list_events, create_event, send_invites). The description reinforces the 'organizer's own' scope but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Full detail for one of this organizer's own LIVE events') and enumerates what it returns: the tally, guest statuses/marks, and guest reply text. It explicitly distinguishes itself from the sibling get_draft by naming it and stating the condition (draft_ id).

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

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

Explicitly routes the agent: use this for a live event, use get_draft for a draft_ id, with the reason given ('a draft has no votes yet'). It also states the prerequisite ('needs the read permission'), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so 'Reads only; changes nothing' is largely a restatement. The genuinely additive disclosure is the conditional behavior of personal links (?g=…), which return previously submitted answers under that link — a behavioral detail not captured anywhere in annotations.

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

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

Three sentences, each load-bearing: what is read, the personal-link variant, and the sequencing advice. The sequencing advice is front-loaded at the point of decision rather than buried, and nothing is padded.

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

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

With an output schema present the description need not enumerate return fields, yet it still names the key ones for scanning. Single required parameter, full schema coverage, safe-read annotations — nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying the two link flavours to distinct output: a personal (?g=…) link additionally surfaces answers already given. That consequence goes beyond the schema's brief format hint.

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

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

Specific verb (Reads) plus resource (a When Works For You poll) and it enumerates exactly what comes back: title, organizer, date options with yes/maybe counts, and confirmation status. This lets an agent distinguish it from get_event or get_draft 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?

Explicitly names the downstream tool and the reason to call this first: 'Use this before respond_to_poll so you can match the person's availability to the poll's exact dates.' It also explains the branch condition for a personal link, so there is no ambiguity about when the extra data appears.

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, idempotentHint and openWorldHint=false, so the safety profile is covered; the description adds the non-obvious auth requirement ('needs the read permission'), which is genuinely useful context beyond the structured fields.

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

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

Two compact sentences, with the core action and filter behavior front-loaded and the permission note trailing. Nothing is 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?

A single optional parameter, full schema coverage, an output schema covering return values, and annotations covering safety; the description adds scope, filter semantics and the permission prerequisite, so nothing an agent needs 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 schema already says 'Filter text; omit for the whole book', so baseline is 3; the description adds meaning by naming the searched fields (name/email/phone), which the schema does not specify.

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 ('Lists this organizer's saved address book') plus the optional narrowing dimension, which cleanly separates it from the sibling list_events and list_groups tools.

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

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

Gives clear context for the optional filter ('optionally filtered by a name/email/phone search'), implying use the unfiltered form to enumerate and the filtered form to find someone. No alternatives or exclusions are named, but no sibling competes for this read operation.

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 read-only/idempotent, and the description reinforces that while adding genuinely non-obvious behavior: that create_event parks drafts which surface here, that drafts are excluded from the archived list, that review_url requires sign-in, and that the read permission is needed. This is context an agent cannot get from the annotations or schema.

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

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

Front-loaded with the core capability, and the parentheticals carry real information rather than filler. It is dense but every clause (drafts, archived behavior, review_url, permission) adds actionable detail; only a slight compression opportunity remains.

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

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

An output schema exists so return values need not be spelled out, yet the description still enumerates key fields and covers the non-obvious draft/archived interaction, the review_url flow, and the permission requirement. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's terse 'true for archived events instead of live ones' by adding that drafts are omitted from the archived view, which materially affects how the flag should 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?

States a specific verb and resource ('Lists this organizer's own events') plus scope, ordering (newest first), and the exact payload returned (id, title, status, who's answered, leading date). The inclusion of drafts distinguishes it clearly from get_event and the other event tools in the sibling list.

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 conditional guidance for the one parameter ('Pass archived:true for the archived list instead of the live one') and clarifies the draft edge case (drafts appear in the live list but not the archived one). It does not name sibling alternatives such as get_event or list_contacts, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so 'Read-only' is partly redundant, but the description adds a genuine behavioral fact not in the annotations: the caller needs the read permission. It also pre-announces that results include member counts, which is helpful return 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?

Two tight clauses with zero filler; the scope statement comes first and the constraint second. Every phrase carries 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 an output schema present, return-shape explanation is unnecessary, and with no parameters there is little else to cover. The description supplies scope, safety, and permission needs, leaving only minor omissions like result ordering or pagination.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline for a 0-param tool is 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?

Clear specific verb+resource: lists the organizer's saved contact groups, and adds the scope detail that each entry carries a member count. It is distinguishable from the sibling list_contacts by the 'groups' resource, though it never names that sibling explicitly to reinforce the boundary.

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?

No when-to-use or when-not-to-use guidance appears. The nearest sibling, list_contacts, is never referenced, so the agent must infer the choice from the resource noun alone; the only conditional in the text is the permission prerequisite.

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

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

Goes well past the annotations (destructiveHint=true, idempotentHint=true) by naming the collateral damage ('any votes on that day go with it'), the hard constraints (confirmed date can't be removed, at least one date must remain), the draft exception, the side-effect guarantee ('Never mails anyone'), and the required write permission.

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

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

A single dense sentence that front-loads the operation and then the constraints in priority order; the semicolon clauses all earn their place. Slightly packed, but 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?

An output schema exists so return values need no explanation, and the description covers the destructive side effects, invariants, permission requirement, and draft/live branching — everything an agent needs to call it correctly.

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

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

Schema coverage is 100% and both params document their own format, so the schema does the heavy lifting. The description restates that event_id accepts a draft_ or live id and that dates are ISO days, adding little beyond the schema — the baseline 3 applies.

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

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

States a specific verb and resource ('Takes dates off a draft ... or a live event') and names the two entity types it operates on. An agent can immediately separate it from add_dates and set_date_time without opening schemas.

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

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

Gives clear conditional context: draft vs live event behave differently, and it notes that send_invites refuses a dateless draft, implying the follow-on workflow. It does not explicitly name a sibling alternative or an exclusion ('use X instead when...'), so it stops short of 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?

Beyond the annotations' destructive/idempotent hints, the description discloses non-obvious side effects: on a live event the guests' votes are removed with them, nobody is notified because the person is no longer being asked anything, and the organizer's row is protected. It also states the write-permission requirement, 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 core action and its two target forms are front-loaded, and every clause (votes, no mail, organizer protection, permission) carries information. It is a single dense sentence with em-dash parentheticals, which is efficient but slightly harder to scan than short separate statements.

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 no explanation, and the description already covers target types, identifier sources, side effects, notification behavior, protected rows, and the permission requirement. Nothing material 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%, so the baseline is 3, but the description adds real meaning: it explains that guests are identified by the participant_id that get_event reports (or by email), and that event_id accepts either a draft_ id or a live event id. That provenance guidance goes beyond the schema text.

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

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

The description names a specific verb+resource (remove guests) and immediately scopes it to the two target types (a draft_ id or a live event), distinguishing it from siblings like add_guests, remove_dates, and update_guest. An agent can tell what this does and on which entity without opening the schema.

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

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

It gives clear conditions: works on drafts or live events, requires the write permission, and cannot remove the organizer's own row. It does not explicitly route to an alternative tool (e.g., update_guest for edits), but the removal use case is unambiguous, so context is strong without an exclusion clause.

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

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

Adds substantial behavior beyond the annotations: personal link updates existing answers and preserves untouched dates and earlier comments unless a new one is given, plain share link appends a new response and returns a personal link, and no email is sent except the organizer notice. This is exactly the write-semantics detail the readOnlyHint=false/non-idempotent annotations leave open.

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

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

Dense but front-loaded with the core action and the safety constraint before the link-type mechanics. No filler sentences, though the final clause about email notice is slightly convoluted in phrasing.

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

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

An output schema exists so return values need no elaboration, yet the description still notes the returned personal link. Together with the mutation, comment-preservation and date-keying semantics, an agent has everything needed to call 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 baseline is 3, but the description adds genuine meaning: dates are keyed by ISO day as get_poll reports them, `all` answers every date at once, and a per-date answer overrides `all`. That precedence rule and the link/name interaction are not 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?

States a specific verb and resource ('Answers a When Works For You poll on someone's behalf') and immediately frames it as acting for another person, which distinguishes it from get_poll (read) and set_my_availability (self). The scope and the answer domain (yes/maybe/no per date) are 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?

Gives a strong usage constraint — only answer for the person being helped, using availability they gave or confirmed, never guess — and explains the two link-type conditions that select different behavior. It does not explicitly name sibling alternatives such as set_my_availability, but the 'someone's behalf' framing implicitly routes the agent.

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

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

Goes well beyond the annotations: it discloses the permission model (send permission required for a restored open autopilot event, write permission otherwise), explains that the tool sends nothing itself yet rejoins automatic reminders, and documents the nightly re-archiving side effect. These are exactly the behaviors an agent cannot infer from readOnly/destructive/idempotent 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 core action is front-loaded in the first clause, followed by genuinely load-bearing caveats about re-archiving and permissions. Every sentence adds a decision-relevant fact with no filler.

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

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

With an output schema present, return values need no explanation, and the description supplies the remaining operational context an agent needs: id source, permission requirements, and the re-archiving quirk. Nothing material is missing for a one-parameter restore operation.

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

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

Schema description coverage is 100%, and the single event_id parameter is fully documented in the schema. The description restates the id's source but adds no new syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a precise verb+resource ('Brings an archived event back to the live list') and anchors it to the dashboard's own 'Restore'. It is clearly distinguishable from the sibling archive_event (the inverse operation). No schema opening is needed to understand what it does.

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?

Tells the agent exactly which id to supply (from list_events with archived:true) and warns that events with all-past dates get re-archived by the nightly sweep unless a future date is added. It does not name alternative tools explicitly, but the context is unambiguous for an agent choosing between archive/restore operations.

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

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

Annotations already declare destructive=true, idempotent=false, and openWorld=true, but the description adds cost and side-effect detail the annotations cannot convey: it spends one autopilot credit (or a Plus subscription slot), mails the guests, requires the send permission, and cannot be undone. That is exactly the extra context an agent needs before a costly, irreversible action.

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 verb and resource, then packed with cost, permission, and irreversibility in one dense em-dash sentence. Every clause carries information, though the single run-on sentence is slightly heavy for the amount of 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?

An output schema exists, so return values need not be explained. The description covers the input's provenance, the credit/subscription cost, the required permission, and the irreversibility — everything an agent needs to decide and act 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?

Schema description coverage is 100% for the single draft_id parameter, and the schema already says it is the draft_id create_event returned. The description restates the same provenance without adding format, validation, or lookup guidance, so it sits at the baseline for a fully documented single parameter.

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 ('Sends a draft's invites') and immediately disambiguates with parenthetical detail ('mails the guests, spends one credit') plus an equivalence claim ('the exact Send the draft's own review page runs'). It also anchors the input to a sibling ('a draft_id from create_event'), so an agent can separate this from confirm, discard_draft, or get_draft without opening another schema.

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

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

Gives clear context for when this applies: only for a draft_id that create_event produced, and it is the same action as the draft's review page Send. No explicit when-not or named alternative (e.g., discard_draft for abandoning a draft) is offered, so it is clear context without exclusions.

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

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

Annotations only cover safety/idempotency, and the description adds substantial non-obvious behavior: autopilot charging on a draft at send, refusal on a live classic poll, immutability of a confirmed date, the write-permission requirement, and that no email is sent. It is close to complete, though it doesn't say what the response looks like or what happens to an existing daypart when an exact time is set.

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

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

The primary action and its exclusivity rule are front-loaded, followed by routing, refusal, and side-effect details. Every sentence carries a distinct constraint, though the density of em-dash clauses makes it slightly harder to scan than a shorter equivalent.

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 5-parameter mutation tool with an output schema (so return shape needn't be described), the description covers prerequisites, alternative tools, refusal conditions, side effects, and the clearing semantics. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), but the description adds constraints the schema does not encode: exact start/end and daypart are mutually exclusive ('never both'), and omitting all three clears the time. That mutual-exclusivity rule is genuine value beyond the field descriptions.

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 precise verb+resource pair (set/clear the time on an existing date) and immediately scopes it against the sibling add_dates, which 'refuses a duplicate day'. An agent can route between set_date_time and add_dates 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?

Explicitly names the alternative and its limitation ('The one way to put a time on a date that is already there'), and states where the tool is refused (live classic/share-link poll, confirmed date on a live event). It also gives the clearing case: omit all three to revert to a plain day.

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 cover the safety profile (idempotent, non-destructive, not read-only, closed-world), and the description adds substantial context beyond them: the write permission requirement, the fact that no mail is sent, the draft-id refusal, and the precedence rule when both inputs are given. That is exactly the extra behavioral detail the annotations cannot carry.

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

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

Three dense sentences, front-loaded with the core action, followed by input-combination rules and then the permission/no-mail constraints. Every clause carries information; the mid-sentence dash constructions are slightly packed but not wasteful.

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

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

With an output schema present, the description need not explain return values, and it covers the remaining ground: identity of the actor, valid event state, input combination semantics, permission requirement, and notification side effects. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the precedence rule ('a per-date answer wins for the dates it names') and the combined use of all+responses. It does not expand on the yes/maybe/no enum, but that is self-evident.

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 ('marks the organizer's own availability') and immediately distinguishes it from the sibling respond_to_poll by noting it is 'the same vote a personal link submits' but scoped to the organizer's own poll. An agent can identify the operation and its boundary without opening the schema.

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

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

Gives clear when-to-use context (organizer is a participant on their own poll) and an explicit when-not ('a draft_ id is refused — vote after sending'). It does not name respond_to_poll directly as the alternative for guests, but the personal-link framing implies the split.

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

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

Goes well beyond the annotations by spelling out that no mail is triggered and that the change only surfaces on the next invite, nudge, confirmation or public page. It also declares the permission requirement ('Needs the write permission'). This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the purpose and dense with useful signal; every sentence carries meaning. The '(#529's mail rule)' internal reference is the only slightly noisy element.

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

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

An output schema exists, so return values need no explanation, and the description covers behavior, permissions, and scope. It stops short of noting whether at least one of title/description must be supplied or what happens if both are omitted — a minor gap for a partial-update tool.

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

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

Schema coverage is only 33%, so the description should compensate. It clarifies that event_id accepts a draft_ id or a live event id — but that is already in the schema description — and identifies title/description as the editable fields without adding format, length, or 'at least one required' constraints.

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

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

States a specific verb and resource ('Changes the title and/or description of a draft ... or a live event') and scopes it tightly to those two fields, explicitly matching the console's Edit form. An agent can immediately tell this apart from siblings like set_date_time or update_guest, which touch different fields.

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 scope limitation ('for those two fields') implies usage, and naming the draft_ vs live event id forms helps the agent pick the right input. However, there is no explicit when-to-use/when-not guidance or reference to an alternative tool for editing other event properties.

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 say this is a non-read-only, non-destructive, non-idempotent, open-world mutation. The description adds the crucial side effect (on a live AUTOPILOT event the corrected address is mailed its invite), the reason for it, and the differing permission requirements (write vs write+send). No contradiction with destructiveHint=false, since the send is a notification rather than data loss.

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

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

Front-loaded with the core action, and each clause (draft vs live, mail side effect, share-link exclusion, permissions) carries distinct information. The heavy em-dash and parenthetical nesting makes it denser than ideal, but there is little true waste.

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

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

With an output schema present, return values need not be explained; what remains — applicability, side effects, permissions, and the no-guest-list edge case — is fully covered for a 4-parameter mutation tool.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description reinforces that the name change is draft-only ('a name can be changed there too' on a draft) and that the guest argument targets one specific guest. It adds modest but real meaning over the schema rather than repeating it verbatim.

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 precise verb and resource ('Corrects one guest's email address') and immediately scopes it to drafts or live events, which cleanly separates it from add_guests, remove_guests, and update_event. It even equates itself to the console action ('the console's own "Change address"'), removing ambiguity about intent.

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 (draft_ id or live event) and when-not ('A live classic (share-link) poll has no guest list, so there is nothing to correct there'), plus the differing permission preconditions per context. The agent can decide applicability without consulting siblings or schemas.

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