icloud-mcp

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

Annotations only declare the write/open-world/non-idempotent profile; the description goes further, disclosing the duplicate-name refusal (and that a repeat call errors rather than duplicating, consistent with idempotentHint=false), visibility timing across calendar tools vs. device sync, that undo is via calendar_delete_calendar with no preview, and the exact return shape and error strings.

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?

It is longer than most one-parameter tools, but it is clearly front-loaded (purpose, then Use when, Parameters, Behavior, Returns, Errors) and every labeled section earns its place. Slightly dense, but no filler sentences.

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 one-parameter mutation with no output schema, the description covers the return value, the undo path, cross-tool visibility, the failure modes, and sibling routing. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and the schema itself only says 'Name of the new calendar', so the baseline would be 3. The description adds real constraints beyond the schema: 1-100 characters, single line, whitespace runs collapsed to one space, plus the empty/too-long/multiline error conditions.

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 first clause states a specific verb+resource+scope: 'Create a new, empty event calendar in the owner's iCloud account', and adds the sync consequence. It is unmistakably distinct from siblings like calendar_create_event (events) and reminders_create_list (Reminders lists), which are named explicitly.

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

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

It gives an explicit 'Use when' condition (owner wants a separate calendar and calendar_list_calendars shows none that fits) and four 'Not for' exclusions that each redirect to the correct alternative (calendar_update_calendar, reminders_create_list, calendar_move_event). Nothing is left to inference.

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

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

Annotations only give the generic safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description goes far beyond: iCloud sends invitations itself so no mail should be sent, invites are gated by ALLOW_CALENDAR_INVITES/INVITE_ALLOWLIST/MAX_ATTENDEES, pre-write overlap and same-title duplicate checks with refuse semantics, request_id retry semantics that qualify the non-idempotent default, and per-recipient delivery status where ok=false means the owner must not be told the person was invited.

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 sentence, then clearly labeled Use-when / Parameters / Behavior / Returns / Errors sections, so scanning is cheap despite the length. A few statements duplicate schema text (the iCloud invitation rule appears in both the Behavior block and the attendees description), which is minor waste for a definition this dense.

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

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

No output schema exists, so the description carries the return contract itself and does so precisely: field list, created=false semantics, conflicts/possible_duplicate meanings, delivery[] ok flag, and a catalog of error conditions with the recovery tool for each. For a 19-parameter mutating open-world tool this is as complete as it needs to be.

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 would be 3, but the description adds real cross-parameter meaning absent from the schema: start/end must both be all-day or both date-times, calendar fallback resolution order (DEFAULT_CALENDAR, then 'Calendar'/'Home', then first), travel_origin/travel_routing require travel_minutes (1–1440) sourced from owner or maps, location_geo requires location, and the 48-fires/day rrule cap. It also converts relative dates to ISO 8601 up front, which is the main failure mode for a 19-param 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?

States a specific verb+resource ('Create one calendar event') and enumerates the scope it covers in a single call (repeat, location, notes, alarms, travel, guests). It explicitly distinguishes itself from the nearest siblings (calendar_update_event, reminders_create_reminder, calendar_respond_to_event, calendar_find_free_time), so an agent can route correctly 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?

The 'Use when' block gives the positive trigger (owner asks to book/schedule/add) and four named exclusions with the alternative tool for each, plus a cross-server handoff (mail_extract_bookings supplies ready arguments for bookings found in mail). There is nothing left to infer about when to pick this tool.

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 non-idempotent, but the description goes well beyond: the confirm-token preview flow, 10-minute token expiry bound to calendar and event count, default-calendar refusal, iCloud shared/subscribed refusal, and the 30-day restore window at iCloud.com that this server cannot perform. This is exactly the extra context annotations can't 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?

Front-loaded with the core action, then sectioned into Use when / Parameters / Behavior / Returns / Errors, so an agent can scan. It is long, but nearly every line is operational (refusals, token lifecycle, error strings) rather than padding; a slight trim of the Behavior bullets would not lose 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?

No output schema exists, yet the description documents both return shapes (preview vs done), the full error taxonomy with actionable recovery, and the irreversible-within-server nature of the delete. Nothing an agent needs to call this correctly or recover from failure is missing.

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

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

Schema coverage is 100% so baseline would be 3, but the description adds real meaning: the name-vs-id ambiguity resolution, omitting confirm_token on the first call and passing the preview token on the second, and the token's binding/expiry semantics. That is beyond what the schema states.

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 ('Delete a whole calendar with every event in it') and immediately flags the two-step nature and the sibling tools it is not (calendar_delete_event, calendar_update_calendar, calendar_move_event). An agent can distinguish it from every calendar sibling 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?

Explicit 'Use when' clause (owner explicitly asks to remove a calendar) plus an explicit 'Not for' list naming three alternatives with the condition that selects each. Usage is fully determined.

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 (destructiveHint, idempotentHint=false) the description discloses permanence/no-undo, that a single occurrence becomes an exception date while the series persists, guest cancellation emails gated by ALLOW_CALENDAR_INVITES, optimistic concurrency ("delete only lands if the event is unchanged since it was read"), and the non-idempotent second-call failure mode.

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?

Well front-loaded and organized into labeled sections (Use when / Parameters / Behavior / Returns), with every sentence carrying semantic weight. It is long and dense for a 4-parameter tool, but the length is largely earned by the edge-case and error detail rather than filler.

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

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

No output schema exists, yet the description documents the return object ({deleted, uid, summary, calendar}, plus occurrence_only/occurrence_start for single-date deletes) and the exact error strings for already-gone, changed-on-server, non-repeating, and settings-blocked cases. Nothing an agent needs to invoke or interpret it correctly is missing.

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

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

Schema coverage is already 100%, but the description goes well past it: uid is opaque and shared across all dates of a series with a specific error for unknown values, calendar only narrows an otherwise slower all-calendar search, occurrence_start must be recurrence_id-or-start and date-time vs date depending on series type, and timezone is read only when occurrence_start lacks an offset.

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

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

The opening clause states a specific verb+resource ("Delete an event by uid") and immediately enumerates the three deletion scopes: single event, whole series, or one date. It explicitly names sibling tools (calendar_move_event, calendar_update_event, calendar_respond_to_event) it must not be confused with.

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 an explicit "Use when" trigger plus three named exclusions with the correct alternative for each, including the non-obvious instruction never to delete-and-recreate for a move. The extra note about cancellation notices from others distinguishes when this tool is and isn't 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?

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them, defining how busy time is computed, that free/cancelled/declined events do not block but unanswered invitations do, that all-day events never block, and what complete=false with not_read means (run icloud_check_health). It also enumerates error conditions. This is unusually rich behavioral disclosure for a read-only tool.

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

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

It is a long description, but it is clearly sectioned (Use when / Parameters / Behavior / Returns / Errors) and front-loaded with the core purpose. The prose is dense and largely non-redundant, though the Parameters block slightly duplicates the 100%-covered schema and could be trimmed.

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

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

No output schema exists, yet the description fully specifies the return shape and the meaning of each field (free_slots, more_slots, all_day_events, not_counted_as_busy, complete, etc.) and the slot structure, plus degraded-mode guidance. Nothing an agent needs to invoke or interpret this tool 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 operational semantics not in the schema: the 62-day cap, that the range never starts before now, that weekday names need only three letters, and that limit is capped at 100. It largely mirrors schema text otherwise, so it is a modest rather than decisive lift over the schema.

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

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

States a specific verb+resource with scope: 'Find open slots of at least duration_minutes within daily hours across the owner's calendars, with busy time and travel worked out for you.' It names what it does not do and points to the sibling tools that do those things, so an agent can distinguish it from calendar_list_events and calendar_create_event immediately.

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

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

Explicit 'Use when' clause (proposing meeting times, checking whether days have room) plus an explicit routing rule: not for listing bookings (calendar_list_events) or booking a slot (calendar_create_event once the owner picks one). Use/when-not/alternatives are all present.

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

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

Annotations already declare readOnlyHint, but the description adds material context beyond them: the performance caveat (read-whole-calendars when a uid isn't stored under its own), a prompt-injection warning that event text is untrusted third-party data, calendar-search ordering, and exact error strings with remediation.

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 purpose, then cleanly sectioned into Use/Parameters/Behavior/Returns/Errors. Every line carries operational information; nothing is padding, and the Returns enumeration is justified because no output schema exists.

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

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

With no output schema, the description compensates by enumerating the full return shape including attendee status semantics and overridden_instances. Combined with error handling and search-order behavior, an agent has everything needed to call and interpret the tool.

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

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

Schema coverage is 100%, but the description adds real meaning: uid is opaque, must be copied exactly, is not a title, and is shared across all dates of a series; calendar is case-insensitive name or id, scopes the search, and produces specific errors when wrong or unknown.

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 ('Get one event by uid') and immediately enumerates the payload it returns (notes, organizer, guests+answers, alarms, repeat rule, series definition). It explicitly distinguishes itself from calendar_list_events and calendar_create_event, so an agent can route 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?

Provides an explicit 'Use when' clause naming the exact cases (notes past 2,000 chars, rrule, per-guest answers, re-check before editing) and an explicit 'Not for' clause routing date-range browsing and single-occurrence detail to calendar_list_events. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the 2-minute cache and its staleness rules, the exclusion of Reminders lists, the exact return shape, and the error/sign-in failure path. This is the kind of 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 purpose, then cleanly sectioned into Use when / Parameters / Behavior / Returns / Errors. Every line carries information, though the total length is slightly heavy for a zero-argument list tool and a couple of clauses restate what the Returns section already implies.

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 no-parameter, read-only listing tool with no output schema, the description covers everything an agent needs: when to call it, what it excludes, caching caveats, return format, and failure handling. No meaningful gap remains.

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?

Zero parameters, so the baseline of 4 applies. The description usefully adds that there are no parameters and that the list always covers every event-capable calendar, plus that other tools accept either name or id case-insensitively, which is helpful even though no schema fields exist to document.

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 ('List the owner's event calendars') and immediately scopes it to the values other calendar tools accept. It explicitly distinguishes itself from calendar_list_events, reminders_list_lists, and icloud_check_health by name, so an agent can route without opening any schema.

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

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

Provides an explicit 'Use when' clause with three concrete triggers (unknown name, 'No calendar named...' error, before create/move/delete) and an explicit 'Not for' clause naming the correct alternatives for each adjacent need. Nothing is left to inference.

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

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

Annotations only supply readOnlyHint and openWorldHint, and the description goes well beyond them: server DEFAULT_TIMEZONE behavior, 800-day range cap, limit range 1-200, unreadable dates skipped, spam series left unexpanded and counted in series_not_expanded, notes truncated at 2,000 characters, and a prompt-injection warning for untrusted event text.

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?

Clear front-loading and labeled Parameters/Behavior/Returns/Errors sections make it scannable, but it is a long block whose Returns and Errors detail approaches reference-manual length. Given the 8-parameter surface and no output schema, most of the length is earned, but the size is a real cost for an agent loading many definitions.

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

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

With no output schema, the description correctly documents the return shape (now, range, total, events, complete, the per-event field list, all-day end exclusivity, recurrence_id handling) and the error conditions. For an 8-param, zero-required tool this is complete enough to call 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 already 100%, yet the description adds meaning the schema lacks: no timezone parameter and how offsets change interpretation, +Nd/-Nd up to 800 days, starting_within_minutes (1-10080) suppressing start/end and excluding in-progress events, query as a single case-insensitive substring, and the AND-combination of query/needs_reply/calendar.

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

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

Opens with a specific verb+resource+scope: 'List event occurrences in a date range across one or all calendars, oldest first, with repeating events expanded.' It explicitly distinguishes itself from three siblings by name (calendar_find_free_time, calendar_get_event, calendar_list_calendars), so an agent can route 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 an explicit 'Use when' list (day/week view, text query, starting_within_minutes, needs_reply) and an explicit 'Not for' list naming the correct alternatives and the condition that selects them. Both inclusion and exclusion criteria are stated rather than inferred.

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, closed-world), and the description goes well beyond them: the ALLOW_CALENDAR_INVITES gate for events with guests, the WebDAV-MOVE-absent copy-then-delete-with-rollback path that guarantees the event is never in two calendars, and the no-op when the target equals the current calendar. This is exactly the extra context 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?

Front-loads purpose then usage, and uses clear Parameters/Behavior/Returns/Errors sections with no wasted filler. It is long, but with no output schema the Returns and Errors blocks are load-bearing rather than padding.

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 move tool with no output schema and no annotations on failure modes, the description supplies the exact return shapes ({moved:true,...} and already-there variant) and enumerates every error path with recovery guidance, leaving nothing 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 already 100%, so baseline is 3, but the description adds real meaning: uid must be copied exactly and a series cannot be narrowed to one date; to_calendar accepts any case or id and fails with a message listing valid names; calendar is only a lookup-narrowing filter that fails loudly if wrong. This is useful semantics beyond the schema.

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

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

States a specific verb+resource (move an event to another calendar) with precise scope: whole series, preserving uid, times, place, alarms, notes, guests. It also names the sibling tools it is not (calendar_update_event, calendar_delete_event), so an agent can distinguish it 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?

An explicit 'Use when' clause gives the triggering intent ('filed under a different calendar'), and explicit exclusions route time/detail changes to calendar_update_event and removals to calendar_delete_event. It even warns against the anti-pattern of delete-and-recreate to move an event.

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

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

Annotations declare a non-read-only, non-idempotent, open-world mutation; the description goes well beyond by disclosing that iCloud sends the organizer the answer itself (so no separate email), that it is refused unless ALLOW_CALENDAR_INVITES permits and the organizer passes INVITE_ALLOWLIST, that only the owner's own attendee entry changes, and that re-calling replaces the prior reply.

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 definition is long but structured and front-loaded: purpose first, then Use when/Not for, then Parameters, Behavior, Returns, and error strings. Every block carries actionable content, though the parameter bullets are verbose enough that some tightening is possible.

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

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

For a mutation tool with no output schema and rich policy constraints, the description covers trigger, alternatives, per-parameter edge cases, side effects (email to organizer), gating settings, and the return shape and error strings. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: response accepts case-insensitive synonyms (accept/yes, decline/no, maybe) and refuses anything else before mutating; occurrence_start must be the recurrence_id (else start) and is refused for non-repeating events; calendar only narrows/speeds the lookup; timezone is only for offset-less occurrence_start. This is above the schema baseline.

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

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

The opening sentence names a specific verb (answer/set reply), the resource (an invitation someone else sent), the value set (accepted, tentative, declined), and the scope (whole series or one date). It clearly distinguishes this from organizer-side and invitation-side 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?

An explicit 'Use when' clause names the prerequisite (owner has decided, found via calendar_list_events(needs_reply=true)), and the 'Not for' clause routes to three named alternatives (calendar_update_event, calendar_delete_event, calendar_create_event) plus the mail path. Nothing is left to inference.

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

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

Annotations only cover the basic safety/idempotency profile; the description goes well beyond them, disclosing that only the display name changes, the duplicate-name refusal rule (with the case-only-rename exception), idempotent repeat behavior, and propagation timing across tools vs. devices. It also enumerates error classes, which is exactly the kind of 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 one-line purpose, then clearly labeled Use when / Parameters / Behavior / Returns sections. The bullet list is dense with load-bearing constraints rather than filler, and no sentence duplicates the schema or annotations verbatim.

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

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

No output schema exists, and the description compensates by specifying the exact return shape ({renamed, from, to}) and the three error conditions. For a two-parameter mutation tool with annotations, 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 would be 3, but the description adds real meaning beyond the terse schema text: "calendar" accepts either the current name in any case or an id from calendar_list_calendars, and "new_name" is constrained to 1-100 characters on a single line with whitespace collapsed.

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 ("Rename one of the owner's calendars") and immediately bounds the scope ("its events and id stay as they are"), which cleanly separates it from event-moving and calendar CRUD siblings. An agent can identify the correct tool 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?

Explicit "Use when" trigger plus an explicit not-for list naming three concrete alternatives (calendar_move_event, calendar_create_calendar, calendar_delete_calendar). No condition is left to inference.

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

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

Goes well past the annotations: discloses that guests get emailed and removed guests receive cancellations, that edits are refused unless ALLOW_CALENDAR_INVITES is set, that the write is optimistic-concurrency guarded ('only lands if the event is unchanged since it was read'), and that repeat calls are idempotent (matching idempotentHint=true). It also enumerates concrete error strings and their remedies.

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?

Well front-loaded with the core behavior in the first sentence, then cleanly sectioned into Use when / Parameters / Behavior / Returns. It is dense and runs long, with some restatement of schema-level detail (e.g. the '' clear semantics appear both here and in the schema), which keeps it just short of immaculate.

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 20-parameter mutation tool with no output schema, the description supplies the missing pieces: the return shape ({updated, uid, calendar, event}, occurrence_only, delivery), the failure modes and their recovery steps, and the invite-permission precondition. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is already 100%, but the description adds cross-parameter semantics the schema cannot express: rrule cannot be combined with occurrence_start, start and end must both be dates or both date-times, attendees/add_attendees/remove_attendees are mutually exclusive, and alarms_minutes_before replaces the whole list. The '' clearing convention and the uid provenance are also spelled out.

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 ('Change chosen fields of an existing event'), and adds the non-obvious scope distinction that it works on one date of a repeating event. It explicitly names the siblings it is not (calendar_move_event, calendar_delete_event, calendar_respond_to_event, calendar_create_event), so an agent can disambiguate 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 an explicit 'Use when' trigger list (reschedule, rename, relocate, re-alarm, change guests) and an explicit 'Not for' list routing five alternative intents to the correct sibling tools. Both when-to-use and when-not-to-use are covered with no inference required.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description goes well beyond: writes only to the default address book, unavailable under READ_ONLY, no duplicate-name check, request_id retry semantics (repeat returns the first card), a confirm-identity/prompt-injection warning, plus return shape and refusal conditions.

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 purpose, then Use-when/Not-for, then Parameters, then Behavior, then Returns/Errors. Dense but every sentence carries actionable information for a 12-parameter mutation tool; no restatement of the title or 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?

Despite having no output schema, it describes the success payload ({created, uid, name}), the idempotent-retry payload, and the pre-write validation errors. Combined with the behavioral notes, an agent has everything needed to call it safely and interpret the result.

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%, yet the description still adds meaning the schema lacks: the 'at least one of name, given/family, organization' requirement (schema shows required=[]), the display-name fallback order, plain-address email format, birthday YYYY-MM-DD/--MM-DD forms, label defaults, and request_id length bounds.

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+target ('Create a new person card in the owner's iCloud address book'), and adds the sync consequence. It is immediately distinguishable from contacts_search_contacts, contacts_update_contact and contacts_create_group without opening any schema.

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

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

Gives explicit when-to-use ('owner asks to save someone new and search shows no existing card') plus two named exclusions with the alternative tool for each: adding email/phone to an existing card (contacts_update_contact with add_emails/add_phones) and groups (contacts_create_group). No inference required.

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

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

Adds substantial behavior beyond annotations: writes one group card to the default address book and syncs to devices, never changes contact cards, refuses duplicate names ignoring case and accents, validates all member uids before creating anything, and is unavailable in READ_ONLY mode. Annotations already cover safety hints, and the description enriches rather than contradicts 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?

Front-loads purpose and usage, then uses labeled sections for parameters, behavior, returns, and errors. Despite its length, every section provides actionable information for a write tool with no output schema.

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

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

Covers the full lifecycle an agent needs: prerequisites, side effects, validation rules, failure modes, and the return shape. With no output schema, the description appropriately supplies return and error details itself.

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 meaningful constraints: name is 1-100 characters with space-run collapsing, members are uids from contacts_search_contacts, omitting members creates an empty group, and duplicates are dropped. This goes well beyond the schema's simple property 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 specific verb and resource: 'Create a new contact group in the owner's address book.' It distinguishes itself from siblings by explicitly naming contacts_update_group, contacts_list_groups, and contacts_create_contact as alternatives for other needs.

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 an explicit 'Use when' condition and a 'Not for' clause listing three sibling tools with the specific scenarios each handles. An agent can route correctly without opening another schema.

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

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

Annotations already mark this destructive and non-idempotent, but the description adds substantial extra context: removal propagates to all synced devices, irreversibility through the connector, group cards left unedited and surfacing as unresolved, optimistic-concurrency conditional delete, unavailability in READ_ONLY mode, and a prompt-injection caution. This is far beyond what the annotations convey.

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

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

Long but tightly organized into Purpose, Use when/Not for, Parameters, Behavior, and Returns/Errors sections, with the core action front-loaded in the first sentence. Every line carries actionable content (error strings, recovery steps, failure modes) rather than 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?

Even without an output schema, the description documents the return shape ({deleted: true, uid}) and the two failure modes with their exact error strings and recovery paths. Given a single required parameter and full annotation coverage, this is complete enough to call correctly and handle errors.

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 documents uid's source, but the description adds real meaning: uid is opaque, must be copied exactly, is matched case-sensitively, must never be a name or email, and a group uid is rejected. It also tells the agent to verify the resulting name matches the intended person.

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 (permanently delete), the exact resource (one person's card in the owner's iCloud address book), and the keying parameter (by uid). It also implicitly separates itself from contacts_delete_group and contacts_update_group by scoping to a single person's card.

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

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

Explicit 'Use when' condition (owner explicitly asks to remove that exact contact and you have confirmed the card) plus a 'Not for' clause naming three distinct alternatives and their selecting conditions (contacts_update_group with remove_members, contacts_update_contact, contacts_delete_group). Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotency, but the description adds substantial context beyond them: irreversibility through the connector, optimistic concurrency ('conditional on the version last read'), unavailability under READ_ONLY, synced-device propagation, and repeat-call behavior. This is a genuinely rich behavioral account for a mutation tool.

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

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

Front-loads the effect, then organizes the rest under Use when / Parameters / Behavior / Returns headers. Despite the length, each sentence carries operational content (error strings, concurrency, retry guidance) with no filler or repetition.

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

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

With no output schema, the description supplies the return shape ({deleted, uid, name, note}) and the exact error strings an agent must interpret, plus the recovery step for the version conflict. Nothing needed to invoke or recover from this tool is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: uid is matched case-sensitively and must be copied exactly, and name is a fuzzy-but-bounded check (case and accents ignored, other differences not) whose mismatch deletes nothing and reports the uid's real group. That is more than the schema conveys.

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 (delete a contact group by uid) and immediately scopes the effect ('only the grouping goes, every member's contact card stays'). This distinguishes it cleanly from contacts_delete_contact and contacts_update_group without opening any schema.

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

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

Gives an explicit positive trigger ('the owner explicitly asks to remove a group') and three named exclusions with the correct alternative for each (remove_members via contacts_update_group, renaming via contacts_update_group, deleting a person via contacts_delete_contact). Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: notes and photos are never returned, cross-device edits can lag up to 2 minutes, contact text is untrusted data and must not be treated as instructions, and the exact error surfaced for an unknown/deleted/group uid. This is unusually rich behavioral disclosure for a read tool.

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

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

Front-loads purpose in the first line, then organizes with explicit Use when / Parameters / Behavior / Returns / Errors structure so every paragraph is scannable. It runs long, and the inline return-value inventory is dense, but the length is largely justified by the absence of an output schema.

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

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

With no output schema and only annotations for safety, the description supplies the full response shape, missing-field semantics ('a missing field means it is empty'), the birthday storage format, and recovery guidance on error. Nothing an agent needs to call and interpret the result is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema's one-liner: uid is opaque, must be copied exactly, is matched case-sensitively, is never a name or email, and a group uid is rejected with the same error as an unknown uid. It also names the three sibling tools that produce a valid uid.

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 ('Get one contact's full record by uid') and immediately positions it against siblings by describing the content delta over contacts_search_contacts (birthday, postal addresses, websites). An agent can distinguish it from contacts_search_contacts and contacts_get_group 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 enumerates when to use (you have a uid and need birthday/address/website, or you are about to edit with contacts_update_contact and need the full current list) and when not to (finding by name -> contacts_search_contacts; group members -> contacts_get_group). Alternatives are named with the selecting condition.

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 openWorldHint=true, and the description reinforces 'Read-only' while adding substantial non-obvious context: has_email=false members must not be guessed at, contact text is untrusted data, and the exact error string for unknown/deleted/person uids. That is meaningful addition beyond annotations, though the safety profile itself largely duplicates readOnlyHint.

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

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

Long but fully structured and front-loaded: one-line purpose, then Use when, Parameters, Behavior, Returns, Errors. Every sentence carries operational content — even the return-shape paragraph substitutes for a missing output schema.

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

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

No output schema exists, and the description compensates by documenting the return shape, members row structure, unresolved semantics, empty-list meaning, and error cases. For a single-parameter read tool this is complete.

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%, yet the description goes well beyond it: uid is opaque, case-sensitive, copied exactly, comes from contacts_list_groups or contacts_create_group, is never the group name, and a person's uid is explicitly rejected with the same error. This materially improves parameter 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?

States a specific verb+resource (get one contact group by uid) with the payload scope (members' names, emails, phones) and the intended use (invite/mail the group). Sibling tools such as contacts_list_groups and contacts_get_contact are explicitly excluded, so the agent can route 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?

Has an explicit 'Use when' clause plus three named alternatives with the condition that selects each (listing groups / finding a uid, one person's record, changing membership). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description goes far beyond: it states nothing is sent or scheduled, explains clamping behavior for the days parameter, notes that only contacts with a saved birthday appear (group cards never do), handles 29 February in non-leap years, and describes error handling via icloud_check_health. No contradiction with annotations.

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

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

The description is well-structured with clear sections (Use when, Parameters, Behavior, Returns, Errors) and front-loads the purpose and usage. However, it is somewhat lengthy for a single-parameter list tool; while every sentence adds value, it could be trimmed slightly without losing critical 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 tool's simplicity (one optional parameter), no output schema, and existing annotations, the description is complete. It covers the return structure (from, days, count, birthdays, notice), sorting, edge cases, and errors, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% for the single 'days' parameter, so the schema already defines default 30 and max 366. The description adds meaningful edge-case semantics: omitted means 30, values outside 1-366 are clamped not refused, today is day 0, and the returned days field shows the value used. This is useful but somewhat overlaps with behavioral guidelines rather than pure parameter meaning.

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: 'List the owner's contacts whose birthday falls within the next N days, soonest first, with the date, days until it and the age they turn.' It also explicitly distinguishes itself from siblings by naming contacts_get_contact for one person's birthday and contacts_search_contacts for finding by name.

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 explicit when-to-use ('the owner asks whose birthday is coming up, or you are planning greetings or reminders') and when-not-to-use ('Not for one person's birthday (use contacts_get_contact) or for finding someone by name (use contacts_search_contacts)'). The alternatives are named with their conditions.

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 mark readOnlyHint and openWorldHint; the description goes far beyond by disclosing no paging/cap, a ~2 minute cache with the caveat that tool-made changes appear immediately, how members is counted (including unresolved entries), that unreadable cards are silently skipped, and a prompt-injection warning about untrusted group names. It also documents error cases and the required remediation (icloud_check_health).

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 cleanly grouped under 'Use when', 'Parameters', 'Behavior', and 'Returns'. Every line adds real operational value, though the density is high and a few behavior bullets could be tightened.

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

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

With no output schema, the description carries the return burden and does so fully: it spells out the {count, groups, notice} shape, the per-group fields and sort order, the meaning of count=0, and the available follow-up (contacts_create_group). Error conditions are enumerated. 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?

There are zero parameters, so the baseline is 4. The description confirms this ('Parameters: none; it always covers every group in the account'), which is a useful reassurance that no filtering argument is expected, but there is no further parameter detail to add.

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 (list) and resource (contact groups) with scope ('every contact group in the owner's address book') and what each entry carries (uid, member count). It explicitly distinguishes itself from contacts_get_group and contacts_search_contacts, so an agent can tell the three apart 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?

Provides an explicit 'Use when' clause (owner names a group needing its uid, or wants to see existing groups) and an explicit 'Not for' clause routing to the correct alternatives (contacts_get_group for members, contacts_search_contacts for people). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial behavior beyond them: matching semantics, 2-minute propagation delay for edits from other devices, that group cards/notes/photos are never returned, the untrusted-contact-text warning, and the agent_added flag requiring confirmation before mailing. These are non-obvious operational constraints an agent could not derive 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?

Front-loads the one-sentence purpose, then uses clearly labeled blocks (Parameters, Behavior, Returns, Errors) with telegraphic, waste-free lines. Given the tool's search complexity and the absence of an output schema, the length is proportionate and every line 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 no output schema, the description supplies the return contract ({total_matches, offset, returned, contacts, notice} and per-contact fields including safety_warnings and agent_added), plus error handling routing to icloud_check_health. Nothing an agent needs to invoke or interpret this tool 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 genuinely adds meaning: 'every word of query must match' with case/accent insensitivity and 3+ digit phone matching, empty-query listing behavior, limit clamping to 1-50 with offset paging keyed on total_matches, and with_email filtering. That is real search semantics beyond the per-field 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?

Opens with a specific verb+resource ('Search the owner's iCloud contacts') and enumerates the searchable fields and result shape ('best matches first'). It explicitly differentiates itself from siblings by naming contacts_get_contact, mail_find_correspondent and contacts_list_groups in the 'Not for' clause, so an agent can route correctly without opening other 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?

Provides an explicit 'Use when' that ties the tool to downstream tasks (calendar_create_event, mail_send_message, obtaining a uid), plus a concrete 'Not for' list naming three alternatives with the condition selecting each. This is the strongest form of when/when-not 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=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is partly covered; the description still adds a lot — optimistic-concurrency write (conditional on the version last read), 90-day recording of emails/phones flagged agent_added, server-level gating by CONTACTS_ALLOW_EMAIL_CHANGES and READ_ONLY, and a prompt-injection warning. Its 'repeating the same call leaves the card as it is' is consistent with idempotentHint, not a contradiction. Minor gap: it never states what happens to the photo if you pass one, given the opening promise that photos are kept.

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

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

Long, but organized under Purpose, Use when, Parameters, Behavior and Returns headings with the destructive/semantic constraints front-loaded. Almost every sentence carries operational weight (concurrency, idempotency, append-vs-replace, error strings), so little feels padded, though the density could be tightened slightly for a 14-parameter tool.

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

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

No output schema exists, and the description compensates by specifying the return shapes ({updated: true, uid, name} plus added; {updated: false, note}) and the exact error strings with the recovery action for each ('changed since it was read' → search, review, retry; 'No contact with uid' → search again; malformed email/birthday or emails-with-add_emails refused before writing). Nothing an agent needs to call or recover from this mutation 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 would be 3, but the description meaningfully extends it: omitted text fields stay unchanged while an empty string clears them, list fields are whole-list replacements with [] clearing them, add_emails/add_phones append and preserve labels, the rule against combining emails with add_emails, the 'pass every address back with one changed' workflow, and the birthday YYYY-MM-DD or --MM-DD formats (the --MM-DD case is 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 ('Change fields on one existing iCloud contact') and immediately delimits scope with 'keeping everything you do not pass, including its photo, notes and other labels.' It explicitly names the sibling tools it is not (contacts_create_contact, contacts_delete_contact, contacts_update_group), so an agent can route 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 an explicit 'Use when' trigger (correct or add details on a card; save a proven new email or phone) plus an explicit 'Not for' list mapping each exclusion to the correct alternative tool. Covers create/delete/group-membership routing in one place.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description goes well beyond them: version-conditional writes preventing clobbering, rename clashing refused ignoring case/accents, READ_ONLY server unavailability, removal never deleting the contact, and idempotent no-op semantics. These are the exact traits an agent needs before mutating a group.

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

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

Front-loads the one-line purpose, then organizes the rest into Use when / Parameters / Behavior / Returns / Errors sections. Though long, every line carries distinct operational information with no padding.

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

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

With no output schema, the description carries the return-shape burden and does so fully ({updated, uid, name, members count} plus added/removed, the no-change response, and the three exact error strings with remediation for the version conflict). Complete for a conditional 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 100%, so baseline is 3, but the description adds real meaning the schema lacks: uid must come from contacts_list_groups, name is optional and 1-100 characters, add_members are existence-checked and deduplicated, remove_members not present are silently ignored, and all three can be combined.

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

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

Opens with a specific verb set and resource ('Rename one existing contact group and/or add or remove its members') and immediately scopes it against adjacent operations ('without touching any contact card'). This cleanly distinguishes it from contacts_create_group, contacts_delete_group, and contacts_update_contact.

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?

An explicit 'Use when' line states the trigger condition, and it names the three sibling tools to use instead for creating, deleting a group, or deleting a person. Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that IMAP sign-in is fresh, INBOX is opened read-only, CalDAV/CardDAV calls are made, areas run in parallel (latency = slowest area), failures are reported rather than raised, and it still answers while the server is paused. That is exactly the operational context annotations cannot convey.

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

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

Front-loaded purpose followed by clearly labelled Use when / Parameters / Behavior / Returns sections, so it scans well. It is dense and includes some scannable bullet detail that a shorter description could have compressed, but nothing is irrelevant to calling or interpreting the 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?

With no output schema, the description fully documents the return shape (ok, since_start_seconds, areas, safety_warnings_since_start, paused) including per-area fields, error masking and the connections/warmth signal. Nothing needed to interpret results is missing.

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

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

The tool takes zero parameters, so the baseline is 4; the description still states 'Parameters: none; it always checks every area enabled on this server', which usefully clarifies that scope is server-configured rather than caller-controlled.

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

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

Opens with a precise verb+resource+scope: 'Test every enabled area live in one call (mail sign-in, calendar list, address book, Mac helper)'. It names the constituent checks and what it reports, which cleanly separates it from the granular mail/calendar/contacts 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?

Explicit 'Use when:' trigger (a sign-in, connection or timeout error, before telling the owner a service is down) plus two named exclusions routing to icloud_get_helper_status and icloud_get_time. When-to-use, when-not-to-use and alternatives are all present.

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

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

Annotations only supply readOnlyHint and openWorldHint, so the description carries real weight and delivers: it reads the server clock, makes no iCloud call, therefore works during an iCloud outage, but is refused while the server is paused. It also documents the error surface ('Unknown timezone ...') and the exact return shape, none of which the annotations provide.

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

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

Front-loaded with the core action, then segmented into Use when / Parameters / Behavior / Returns / Errors so an agent can scan to the relevant block. It is long, but every sentence carries decision-relevant information (refusal conditions, defaults, outage behavior) 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 no output schema, the description supplies the full return contract (field names, formats, units, 24-hour clock, ISO 8601 with offset) and the error contract. Combined with the default-timezone and paused-server behavior, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description goes beyond the schema: it specifies IANA Area/City format, states that offsets ('+02:00') and abbreviations ('PST') are refused, and clarifies that omission or '' yields the owner's DEFAULT_TIMEZONE, with a bare call as the way to discover the owner's zone. That is meaningful added semantics over the schema's one-line default note.

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

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

States a specific verb and resource ('Get the current date, weekday and clock time') plus the scoping modifier of timezone choice. It explicitly distinguishes itself from calendar_list_events, calendar_find_free_time and calendar_get_event, so an agent can route correctly without opening any schema.

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

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

Gives an explicit trigger ('before proposing, booking or resolving relative dates'), an explicit non-use case ('Not needed right after calendar_list_events or calendar_find_free_time, whose results already carry now'), and names the alternative for a related need ('not for open time (use calendar_find_free_time)'). This is textbook when/when-not/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 already declare idempotentHint=true and destructiveHint=false, but the description goes further: it explains that a duplicate name yields created=false with a note, that repeating the call is safe, that no mail is moved, and that the folder appears after device sync. This is rich behavioral context 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?

Front-loaded with the action, then blocked into Use when / Parameters / Behavior / Returns. Every sentence carries distinct information; there is no repetition of the title or schema.

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

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

With one parameter and no output schema, the description fully covers the gaps: return shape ({created, name}), the duplicate-name outcome, error behavior, and sync timing. An agent has everything needed to call it correctly and interpret the result.

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%, but the description adds meaning the schema does not: the name is case-sensitive, 'Parent/Child' creates a subfolder where nesting is supported, and an alias like 'Sent' must not be passed. It also warns that a rejected name raises an error and points to mail_list_folders for checking.

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 a new, empty mail folder in the owner's iCloud mailbox') and scopes it precisely as empty and owner-owned. An agent can distinguish it from mail_update_folder, mail_delete_folder, and mail_move_messages without reading any schema.

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

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

Explicit when-to-use ('owner wants a place to file mail and mail_list_folders shows no suitable folder') plus explicit when-not with named alternatives for renaming, filing, and deletion. Nothing is left to inference.

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

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

Annotations already mark this as destructive, non-idempotent, and closed-world, and the description aligns with them while adding substantial context: preview-vs-done behavior, token validity, partial-failure handling, refused folder names, and non-repeatability. This is far richer than what annotations alone provide.

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

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

The description is long but tightly structured and front-loaded: purpose first, then Use when, Parameters, Behavior, Returns, and Errors. Every section earns its place for a destructive, multi-step tool with token confirmation.

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?

Despite having no output schema, the description fully documents the preview and done return shapes and the relevant error cases. Combined with the annotations and complete input schema, an agent has everything needed to call this safely and 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 already 100%, but the description adds meaningful semantics beyond the schema: name is matched case-insensitively from mail_list_folders, and confirm_token must be omitted on the first call and is valid for only 10 minutes while folder count and uidvalidity remain stable. This materially improves 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 states a specific verb and resource: delete a mail folder, with the important scope that messages are moved to Trash rather than deleted. It also names the sibling alternatives it is not, so an agent can distinguish it from mail_delete_messages, mail_run_bulk_action, and mail_update_folder without opening other 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?

It gives explicit when-to-use guidance (owner asks to remove a folder they no longer need) and explicit when-not-to-use guidance with named alternatives. The confirm_token workflow is also fully specified: omit on first call, pass only after the owner has seen the preview and said yes.

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

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

Annotations declare destructiveHint=true, but the description adds substantial context beyond them: it requires owner confirmation, explains the copy-to-Trash-then-remove mechanics, restoration via mail_move_messages, the ALLOW_PERMANENT_DELETE gate (off by default) that refuses rather than misbehaves, renumbering refusal, and the partial-stop error 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?

Front-loaded with the core action, then cleanly sectioned into Use when / Parameters / Behavior / Returns. Dense but every sentence carries operational information (gating, errors, restore path), so nothing is wasted.

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?

Although there is no output schema, the description documents the return shapes ({moved_to_trash, from, trash} vs {permanently_deleted, folder}) and the error cases. For a 3-param destructive tool this is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by stating that uids and uidvalidity must originate from the same mail_search_messages/mail_get_messages result for the folder, and enumerating folder aliases (INBOX, Sent, Drafts, Trash, Junk, Archive), which is genuine added meaning.

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 with scope: 'Move specific messages, by uid, to Trash'. It immediately clarifies the recoverability semantics and distinguishes itself from sibling tools (mail_move_messages, mail_run_bulk_action, mail_mark_messages) so an agent can route correctly without opening any schema.

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

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

Explicit 'Use when' clause plus a 'Not for...' clause naming three alternatives with the exact condition that selects each (bulk filtered delete, filing elsewhere/Junk, flags). Nothing about when to prefer this vs alternatives is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context beyond them: nothing is guessed from wording, items without a start are dropped, cancellations have kind 'cancellation' with no calendar_event, request_id prevents double-booking, and uidvalidity triggers an attachment-skipping optimization. Error strings are also enumerated.

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 purpose, then clearly sectioned Parameters/Behavior/Returns/Errors. It is long, but nearly every line carries operational detail (dedup, cancellation, empty-items fallback); a couple of clauses could be tightened without loss.

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?

Despite no output schema, the description fully specifies the return shape ({folder, uid, subject, from, items, found, note}), the 20-item cap, per-item fields, the empty-items fallback to mail_get_message, and the three error conditions. 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 goes further than the schema: folder aliases are case-insensitive or copied exactly from mail_list_folders, uid is valid only within its folder and lists the tools it comes from, and uidvalidity's refusal/skip behavior is spelled out rather than restated.

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 ('Extract exact bookings and appointments from one email's structured data') and immediately scopes the sources (schema.org markup, .ics attachments) and output form (calendar_create_event arguments). An agent can distinguish this from calendar_create_event, mail_get_message, and calendar_respond_to_event without opening a schema.

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

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

Explicit 'Use when: before booking anything from a confirmation or invitation email' plus two named exclusions routing to calendar_create_event (booking) and calendar_respond_to_event (replying). Both the trigger and the alternatives are stated, 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?

Adds rich behavior beyond the readOnlyHint and openWorldHint annotations: it reads only From/To/Cc headers in INBOX and Sent, never bodies or other folders, uses a 10-minute cache, may miss newest mail, ranks exact matches first, and warns that 'similar' matches require owner confirmation. It also documents no-match hints and the empty-query refusal.

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

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

Despite covering purpose, usage, parameters, behavior, returns, and errors, it is tightly structured under front-loaded labels. Each sentence contributes necessary operational detail for a complex search 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 the absence of an output schema and the tool's non-trivial search semantics, the description fully covers return fields, match types, caching limitations, scanning scope, and error behavior. Nothing critical for correct invocation appears missing.

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

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

Schema coverage is already 100%, but the description adds material parameter semantics: every query word must match a name, address part, or domain; misspellings match as 'similar'; limit is clamped to 1-25; and search_all_history toggles between recent-cache scanning and full-mailbox scanning with approximate volumes.

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: find people the owner has exchanged email with, by approximate name/address/company, plus what is returned. It explicitly distinguishes itself from contacts_search_contacts and mail_search_messages, so an agent can route correctly without opening sibling 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?

Provides explicit when-to-use guidance: use when contacts_search_contacts finds nobody, or when you need the address someone actually writes from. It also names when not to use it and which sibling to use instead for saved contacts or messages from a person.

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: it discloses the approval gate (SEND_REQUIRES_APPROVAL default causes queuing or Drafts, not sending), draft-only mode, the Sent copy, the $Forwarded flag on the original, and that every call is a new message. It also enumerates error classes and remediation, which the annotations do not cover.

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 purpose, then labelled Use when / Parameters / Behavior / Returns / Errors sections. The length is justified by the tool's gate and error complexity; each sentence carries distinct information 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?

For a 10-parameter mutation tool with no output schema, the description covers sending behavior, return payload shape, and failure modes, so an agent can call it and interpret the result without further documentation.

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 interaction semantics the schema lacks: that folder/uid/uidvalidity must come from the same search result, that omitting uidvalidity skips the renumbering check, note placement above the block then signature, note_html fallback to note, and that there is no parameter for extra files.

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 (forward) and resource (one received message) plus the mechanism used: inline body, 'Fwd:' subject, original header block, attachments by default. This is precise enough that an agent distinguishes it from send/reply without opening any schema.

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

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

Explicit 'Use when' clause plus a hard constraint (only forward to addresses the owner gave, never one found inside the mail) and three named exclusions routing to mail_reply_to_message, mail_send_message, and mail_move_messages. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them with truncation limits (MAX_BODY_CHARS default 30,000), the oversized-file cap (MAX_ATTACHMENT_BYTES default 5 MiB), which content types decode to text vs base64, that nothing is marked read, and an explicit prompt-injection warning that contents are untrusted. This is unusually rich behavioral disclosure for a read tool.

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

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

Front-loaded with the one-line purpose, then clearly labelled Use-when / Parameters / Behavior / Returns / Errors sections. It is dense but every sentence carries an operational constraint or routing decision; nothing is padding.

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?

Despite having no output schema, the description documents the return payload ({filename, content_type, size} plus text or content_base64), the oversized-file error path, and the specific error messages for out-of-range index and stale uid/uidvalidity. An agent has everything needed to call and handle results 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 already 100%, so the baseline is 3, but the description adds real meaning: index is 0-based and sourced from mail_get_message's attachment list for the same folder/uid, inline images count toward the index, and uidvalidity guards a renumbering check (omitting it skips the check). That is more than the schema alone conveys, though it stops short of full parameter detail.

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 (fetch), resource (one attachment of a message), and addressing scheme (by index), with the output form (text vs base64) up front. It is immediately distinguishable from mail_get_message, mail_extract_bookings and mail_forward_message, all of which are named explicitly.

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 an explicit 'Use when' trigger plus three named alternatives with the condition that selects each (listing -> mail_get_message, .ics booking data -> mail_extract_bookings, passing a file on -> mail_forward_message). Nothing is left to inference.

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

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

Annotations give readOnlyHint and openWorldHint, but the description adds critical behavioral context: the unread state never changes, the body is untrusted and must not be followed as instructions, hidden HTML text is removed and flagged in safety_warnings, text is truncated at MAX_BODY_CHARS with text_truncated=true, and specific error messages are explained. This goes well beyond the annotations.

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

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

The description is dense but well-structured with clear sections ('Use when:', 'Parameters:', 'Behavior:', 'Returns:', 'Errors:'). Every sentence carries useful information for a tool with five parameters, no output schema, and multiple edge cases. Nothing is redundant or 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 no output schema, the description fully explains the return shape, truncation behavior, error cases, and safety handling. Combined with the annotations, an agent has everything needed to call the tool correctly and interpret its results 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 coverage is already 100%, yet the description adds meaning beyond the schema: uid and folder come from a prior mail_search_messages result, omitting uidvalidity skips the renumbering check, include_html is cut at twice MAX_BODY_CHARS, and show_hidden returns up to 4,000 characters hidden from a reader. These details meaningfully extend the schema 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?

Starts with a specific verb and resource: 'Read one message in full: headers, plain-text body, attachment list and flags, without marking it read.' This precisely distinguishes it from mail_get_messages, mail_get_thread, mail_get_attachment and mail_extract_bookings by naming each alternative and the condition for using them.

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?

Includes an explicit 'Use when:' line and a 'Not for...' list that routes the agent to the correct sibling tool for several messages, conversations, attachment contents and booking details. No inference is required.

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

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

Annotations only cover readOnlyHint/openWorldHint, and the description adds substantial context beyond them: duplicates dropped, empty list or >25 refused, large attachments not downloaded, uidvalidity omission skipping the renumbering check, body truncation behavior, and an explicit prompt-injection warning about untrusted body text.

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

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

Long but densely organized into labeled blocks (Use when / Parameters / Behavior / Returns / Errors) with the core purpose front-loaded and zero filler sentences. Every clause carries actionable 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?

Despite no output schema, the description documents the return shape ({folder, uidvalidity, returned, messages, complete}), the missing_uids/complete=false path, the truncation hint, and two named error strings with remediation. Complete for a batch-read tool with these annotations.

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?

Although schema coverage is 100%, the description adds meaning the schema lacks: uids must all come from one folder and one result, uidvalidity omission deliberately skips the renumbering check, and body_chars is clamped between 200 and MAX_BODY_CHARS (default 30,000) – a bound not present 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, resource, batch size and scope ('Read up to 25 messages from one folder in a single call') plus a distinctive trait ('without marking any of them read'). It explicitly distinguishes itself from mail_get_message and mail_search_messages, so an agent can route 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 an explicit 'Use when' scenario (batch from mail_search_messages or mail_list_changes, e.g. a day's unread mail) and explicit anti-cases: not for a single full message (use mail_get_message) and not for summaries (mail_search_messages already has them). Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the threading algorithm (root Message-ID or References match), that messages in other folders are not found, that cross-folder copies are merged by Message-ID, the exact return shape, the degenerate case of missing threading headers, and error messages with recovery steps.

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 answer to the core question, then cleanly sectioned under Parameters/Behavior/Returns/Errors, with no filler sentences. It is on the long side and repeats the INBOX-and-Sent rule in both the Parameters and Behavior sections, a small redundancy that keeps it short of a 5.

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?

There is no output schema, yet the description specifies the return object keys and the per-message folder/uidvalidity fields, plus the failure modes. For a read-only threading tool with 3 parameters this is complete enough to call correctly without guessing.

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 semantics the schema lacks: the accepted folder aliases and case-insensitivity, that INBOX and Sent are always searched regardless of the argument, the provenance of a valid uid (five named sources), and precisely what passing or omitting uidvalidity does on a renumbered folder.

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 with scope: 'List the messages in the same conversation as a given message, found in its folder, INBOX and Sent, oldest first, as summaries without bodies.' It also names adjacent siblings (mail_get_messages, mail_get_message, mail_search_messages), so an agent can distinguish it from every other read tool in the 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?

Explicit 'Use when' clause gives the triggering scenario ('the back-and-forth around a message before replying or summarising') plus two explicit exclusions with named alternatives for each (body reading, subject search). Nothing is left for the agent to infer.

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 and open-world, and the description goes well beyond them: headers only, nothing marked read, the precise definition of 'answered' (In-Reply-To/References or later reply), that Drafts/Trash/Junk are skipped, one message per person, exclusions for no-reply/notification addresses, silent clamping, and a slower-read cost for larger days. It also names the error case and the recovery tool.

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

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

Front-loaded with purpose, then segmented into Use when / Parameters / Behavior / Returns / Errors. Given the non-obvious reply-detection and windowing semantics, nearly every line carries operational information; there is no filler.

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

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

With no output schema, the description fully documents the return shape ({folder, uidvalidity, days, total, returned, awaiting, complete}), per-item fields, how to consume uids (mail_get_message with folder and uidvalidity), the meaning of an empty awaiting, and complete=false semantics. Error handling is also covered.

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% (defaults and ranges), yet the description adds semantics the schema lacks: days counts whole calendar days date-only and bounds both the sent mail and the searched answers, mail before the window is never listed even if unanswered, limit cuts only the awaiting list while total still counts everyone, there is no offset, and out-of-range values are clamped (days 1-90, limit 1-50). This is meaningful value beyond the structured fields.

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+scope ('List messages the owner sent that nobody has answered yet, one per person, longest waiting first') and explicitly distinguishes itself from mail_search_messages with unanswered_only and from mail_reply_to_message. An agent can identify the tool without opening any schema.

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

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

Explicit 'Use when: the owner asks who has not replied or what to chase' plus two named exclusions with the exact alternative tool and parameter ('Not for received mail the owner has not answered (use mail_search_messages with unanswered_only=true) or for writing the follow-up (use mail_reply_to_message)'). Nothing is left to inference.

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

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

Annotations give readOnlyHint/openWorldHint, but the description adds substantial context beyond them: nothing is marked read, IMAP CONDSTORE makes a quiet poll one status request, summaries are untrusted, and per-folder token semantics. This is rich disclosure rather than repetition.

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

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

Front-loads purpose then organizes with labeled sections (Use when / Parameters / Behavior / Returns / Errors). It is long, and the Returns block is dense, but with no output schema most of it earns its place. Slight over-length keeps it from a 5.

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 no output schema, the description fully documents return shapes (first call vs later calls, start_over, over-limit notes) and error conditions. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'omit since on the first call; each folder has its own token' and 'limit caps new and changed separately and is clamped to 1-200'. The per-folder token nuance is genuinely useful 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?

States a specific verb+resource+scope: report new messages and flag/read/answered changes in one folder since a previous token, explicitly 'without searching again'. It also names the sibling it is not (mail_search_messages for a first look), so an agent can route correctly without opening schemas.

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

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

Has an explicit 'Use when: polling a folder... Not for a first look (use mail_search_messages)' section, plus the deleted/moved-out exclusion. When-to-use, when-not-to-use, and the named alternative are all present.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: states it opens no folder and changes no flags, excludes \Noselect folders, documents the Sent/Drafts/Trash/Junk/Archive aliases and INBOX, explains null total/unseen, and routes errors to icloud_check_health. This is rich behavioral context an agent could not derive from structured fields.

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

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

Front-loaded with purpose, then clearly sectioned into Use when, Parameters, Behavior, Returns, and Errors. Despite its length, each sentence carries distinct, actionable information 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 no output schema, the description fully compensates by describing the return shape ({name, special_use, total, unseen}), null semantics, the guarantee of a non-empty list, and error behavior. An agent has everything needed to call and interpret this 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?

Zero parameters, so the baseline is 4. The description reinforces this by stating there are no parameters and that the call always covers the whole account, which usefully clarifies scope, though there is no per-parameter meaning to add.

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 (list) and resource (mail folders) plus the scope of the returned data (total and unread counts) and the practical reason (to learn names other mail tools accept). An agent can distinguish it from mail_search_messages and mail_list_changes immediately.

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

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

Explicit 'Use when' triggers (unknown folder name, 'Could not open the folder' error, seeing where mail is filed) plus explicit exclusions that name the correct alternatives (mail_search_messages for messages, mail_list_changes for recent activity). Nothing is left to inference.

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

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

Annotations only cover readOnlyHint/openWorldHint, but the description adds substantive behavior: headers-only access, nothing marked read, the definition of 'bulk', silent clamping of days/limit, the 1,000-message scan cap and what scanned=1000 implies, and a security note that names/subjects are untrusted third-party text surfaced via safety_warnings. This is far beyond what annotations provide.

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

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

Front-loaded one-line summary, then clearly labeled Use when / Parameters / Behavior / Returns / Errors blocks, so it scans well and each section carries unique information. It is nevertheless long and parenthetical-heavy, slightly denser than needed.

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

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

No output schema exists, and the description fully documents the return object (folder, days, scanned, senders_found, bulk_messages, senders, hint) and per-sender fields including the unsubscribe sub-object and latest_uid caveat (no uidvalidity). It also names the error case and its remedy, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description materially extends each parameter: folder accepts case-insensitive aliases or an exact name from mail_list_folders; days counts whole calendar days and is silently clamped (not refused); limit cuts only the senders list while scanned/senders_found/bulk_messages still span the window, with no offset so limit must be raised.

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

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

Specific verb+resource+scope: 'Rank who sends mail into one folder over recent days, grouped by sender address', plus the exact output shape (message/unread counts, bulk and unsubscribe markers). It is immediately distinguishable from mail_find_correspondent and mail_run_bulk_action, which are named explicitly.

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

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

Explicit 'Use when' (see what fills a folder, plan a cleanup) and 'Not for' with named alternatives for both excluded cases (mail_find_correspondent for a person, mail_run_bulk_action/mail_unsubscribe_from_list for acting). Nothing is left to inference.

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

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

Annotations cover the safety profile (idempotent, non-destructive, closed-world, mutating), and the description adds substantial context beyond them: only Seen and Flagged change, messages stay in-folder, changes sync to devices, repeats are idempotent, a renumbered folder (uidvalidity changed) is refused before any change, and long lists are chunked. It also names error strings and recovery steps.

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?

Structured into Purpose, Use-when, Parameters, Behavior, Returns and Errors blocks with the routing constraint front-loaded ahead of the alternative tools. It is long but every line carries operational information an agent needs; no filler sentences.

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 no output schema, the description supplies the echoed return shape, the idempotency guarantee, the refusal behavior for stale uidvalidity, and the two named error conditions with remediation. 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 real cross-parameter meaning: uids and uidvalidity must originate from the same mail_search_messages/mail_get_messages result, read and flagged are independent, and omitting both is a no-op. The omit-vs-false semantics are restated from the schema rather than newly added, which keeps this just below a 5.

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

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

Opens with a specific verb-plus-resource ('Set or clear the read and flagged state of specific messages, by uid') and immediately scopes it ('without moving them or changing anything else'). An agent can distinguish this from mail_move_messages, mail_delete_messages, and bulk operations without opening any schema.

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

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

Explicit 'Use when' clause names the exact owner intent (mark particular messages read/unread/flagged/unflagged) and then names three alternatives with their distinct roles: mail_run_bulk_action for filter matches, mail_move_messages for filing, mail_delete_messages for deletion. The bulk alternative even notes it previews and is undoable, which is a genuine routing signal.

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

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

Far exceeds the annotations. Discloses the iCloud lack of IMAP MOVE and the copy/flag-deleted/expunge fallback scoped to each uid, that other messages are untouched, that a changed uidvalidity is refused before any move, chunking with partial-failure reporting, and that messages get new uids. Annotations are consistent and the description adds rich operational detail.

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

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

Front-loads the purpose, then uses labeled blocks (Use when, Parameters, Behavior, Returns, Errors). Dense but every sentence carries operational value with no filler.

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