icloud-agent

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds important behavioral context beyond annotations: user confirmation is required, an interrupted attempt is blocked from retrying, and event_id should be read in that case. It does not describe the successful return payload, so it stops short of a 5.

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

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

Three sentences, front-loaded with the core action, then prerequisites, then the failure-mode instruction. 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.

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

There is no output schema and annotations are minimal, so the description must do most of the work. It covers purpose, required parameters, confirmation gating, and retry behavior, but it does not state what a successful call returns, even though it references event_id for the interrupted case.

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

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

The schema has low description coverage, so the description must carry weight. It names all required inputs (draft_id, reviewed sha256, confirmed:true) and clarifies that the sha256 must be the one reviewed by the user, which is useful semantic context. It does not explain draft_id sourcing or formatting beyond the schema pattern.

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 the exact local calendar draft confirmed by the user." The phrase "exact local calendar draft confirmed by the user" distinguishes it from sibling tools like calendar_draft, calendar_update_draft, and calendar_discard_draft.

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 gives a hard precondition: "Never call before showing the proposal and receiving confirmation." It also covers the interrupted-attempt case and points the agent to the alternative action: "read its event_id instead."

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 openWorldHint=true, so irreversibility is covered. The description adds genuinely new behavioral context: deletion is keyed on an ETag (optimistic concurrency), whole_series wipes ALL occurrences and is gated on user intent, and attendee meetings are out of scope. That is meaningful disclosure 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?

Three short sentences, zero filler, with the destructive scope constraint and the whole_series caveat front-loaded before the exclusion note. Every clause earns its place.

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

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

For a destructive, no-output-schema tool whose annotations already cover safety, the description supplies the caveats an agent actually needs: ETag requirement, whole_series semantics, and the attendee-meeting restriction. Only minor omissions remain (e.g., exact response/error behavior on a stale ETag).

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

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

Schema description coverage is 0%, so the description must carry the load. It explains the ETag's role in identifying the event version and fully defines whole_series (deletes ALL occurrences, requires user intent). event_id is left implicit but is self-evident from its name, so the gap is minor.

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 personal event') and immediately narrows scope with two disqualifiers (attendee meetings unsupported; whole_series requires explicit user intent). This lets an agent distinguish it from calendar_update, calendar_discard_draft, and the other calendar siblings 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 states a when-not-to-use condition ('Attendee meetings are not supported') and an intent precondition for whole_series deletion, which is the key judgment call for this tool. It stops short of naming an alternative sibling for meeting deletion, so it is strong context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, but the description adds valuable scope beyond them: destruction is confined to the local draft (not the iCloud event) and creation-attempt records are non-discardable. The 'last-read hash' phrasing hints at an optimistic-concurrency guard.

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

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

Three short sentences, all front-loaded with the core action first, then scope, then the exclusion. Every 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 single-argument destructive tool with no output schema, the description covers the safety-scope question, the concurrency mechanism, and a key precondition. It stops short of describing post-discard behavior or error cases, but is otherwise sufficient 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 low, so the description must compensate. It explains 'using its last-read hash,' which maps to the expected_sha256 concurrency token, but says nothing about draft_id, and the hash's role is only implied rather than 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: 'Discard a pending local calendar draft.' It distinguishes itself from the destructive calendar_delete sibling by clarifying it 'Does not delete an iCloud event,' making the local scope explicit.

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

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

Provides exclusion conditions ('Does not delete an iCloud event,' 'Creation-attempt records cannot be discarded') that help an agent decide what this tool won't do, but never names an alternative tool (e.g. calendar_delete) or states positively when to reach for this one.

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 real value beyond annotations: it clarifies the operation is a local draft that writes nothing to iCloud, and discloses format constraints (UTC offsets required for timed values, exclusive all-day end dates). Consistent with readOnlyHint=false and destructiveHint=false; no contradiction.

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

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

Four tight sentences, front-loaded with the core purpose and local-only scope, followed by format rules and the confirmation step. No filler; every sentence earns its place.

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

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

No output schema exists, but the description refers to 'returned calendar and event details' so the agent knows a draft payload comes back. Combined with the local-only scope and format rules, it is largely complete for a single nested-argument draft 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 0%, so the description must carry semantics. It explains calendar_id ('destination calendar name') and start/end formats (UTC offsets, exclusive end dates), which is meaningful guidance, though title/location/description fields are left to inference.

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 ('Prepare a local draft') and resource ('standalone personal event'), and immediately scopes it as local-only ('creates nothing in iCloud'). This cleanly differentiates it from creation siblings like calendar_create.

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

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

Gives clear workflow context: it 'creates nothing in iCloud' and instructs the agent to 'Show the returned calendar and event details to the user for confirmation,' implying it precedes an actual create. No explicit named alternative or exclusion is given, so not a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful scope (account-local only, newest-first ordering, includes failed creation attempts) but says nothing about pagination or result size, so it is a modest add over the structured data.

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?

One sentence, zero filler, front-loaded with the verb and resource, and the ordering constraint is tacked on efficiently at the end.

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

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

For a simple read-only list tool with no output schema this is minimally adequate, but it omits pagination behavior and the default page size of 20, both relevant to calling it correctly. Nothing is misleading, but it is not 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 description coverage is reported as 0%; 'limit' carries only default/max/min and 'before' is a cursor. The description never mentions the page size or the pagination cursor, so an agent gets no help on either parameter from prose. It does not compensate for the coverage gap.

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

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

States a precise verb (List), a specific resource (this account's local calendar drafts) and even the ordering (newest first), plus the subtle inclusion of 'creation attempts'. It does not, however, distinguish itself from siblings like calendar_list or calendar_read, so it falls short of a 5.

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 purpose implies when to use it (you want to see stored drafts), but there is no explicit when/when-not guidance and no mention of alternatives such as calendar_list or calendar_search for non-draft data. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and scope profile is covered. The description adds the useful constraint that only enabled iCloud calendars are returned, which is real context beyond structured fields, though it omits ordering or pagination details.

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

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

A single front-loaded sentence with zero waste. Every word earns its place.

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

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

Adequate for a simple zero-input list tool whose annotations carry the safety profile, but it could go further by noting the discovery role (obtaining IDs for use with calendar_read/calendar_create) and any return ordering.

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 a single empty arguments object, so there are effectively no meaningful parameters and no semantics to explain; the baseline of 4 applies since no param documentation is needed.

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 (enabled iCloud calendars and their IDs). It is distinguishable from siblings like calendar_search and calendar_read, though it doesn't explicitly say how it differs from 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?

Implies usage (enumerate calendars to obtain IDs) but gives no explicit when-to-use or when-not-to-use guidance, and does not name alternatives such as calendar_search. Discovery intent is inferable but not stated.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the bar is lower, yet the description adds real value: it returns the full resource *and* the ETag, and it is a mandatory step in the mutation workflow. That ETag detail hints at optimistic-concurrency requirements an agent would otherwise miss.

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

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

Two sentences, no filler, with the core action and its role in the workflow front-loaded. Every clause 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?

For a single-ID read with annotations covering safety and no output schema, the description covers purpose, returned payload (resource + ETag), and workflow position. The remaining gap is how to obtain a valid event_id, which is left to the caller.

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

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

There is one parameter, event_id, with 0% schema description coverage, and the description says nothing about its form, source, or constraints. Since coverage is far below 50%, the description is expected to compensate and does not.

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 (read) and resource (complete event resource plus its ETag), which implicitly separates it from calendar_list and calendar_search that return collections rather than one full event. It never names those siblings explicitly, so an agent has to infer the distinction from 'complete event resource'.

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?

'Required before changing or deleting events' gives an explicit precondition that routes the agent to call this before calendar_update or calendar_delete. It stops short of naming those tools or stating when reading is *not* needed, but the positive usage condition is unambiguous.

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

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

Annotations already establish the read-only, non-destructive, closed-world profile, so the bar is low. The description still adds real value beyond them: the operation is purely local and does not contact iCloud, and it discloses the returned payload (status and review hash).

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

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

Two short sentences, zero filler, with the core action front-loaded and the network constraint placed as a concise qualifier at the end.

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

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

For a simple single-parameter read tool with annotations covering safety and no output schema, the description covers what it does, that it is local, and roughly what it returns. Only the sibling-routing information is missing, which is a minor gap.

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?

Only one parameter, and schema description coverage is 0% – draft_id has no textual documentation, though its UUID pattern partially conveys the expected format. The description adds nothing about the identifier, so this sits at the baseline rather than above it.

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 ('Read a local calendar draft') and even names what is returned (status, review hash). It distinguishes itself from calendar_read by the word 'draft' and from calendar_drafts by being singular, though it never explicitly names those 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?

No explicit when-to-use or when-not-to-use guidance. The clause 'Does not contact iCloud' hints at an offline/local use case, but the description never says how this differs from calendar_read (event read) or calendar_drafts (list drafts), leaving the agent to infer selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral trait not in the annotations — that recurring events are expanded into occurrences within the range — but says nothing about result limits, ordering, or behavior for oversized ranges.

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?

One front-loaded sentence with no filler, and the recurrence caveat is folded in efficiently. It is appropriately sized, though it is arguably too terse for the parameter burden it carries.

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 four parameters at 0% schema coverage and no output schema, the description should explain date formats, the limit cap, and return shape. It covers only the recurrence-expansion behavior, leaving an agent unable to call it confidently with correct inputs.

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

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

Schema description coverage is 0%, so the description must carry the semantics. It implies start/end bounding but gives no date format, timezone handling, or calendar_id expectations, and never mentions the limit/cap parameter at all, leaving most parameter meaning undocumented.

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 (Find) and resource (calendar occurrences) with a clear scope (bounded date range, recurring events included), so the agent knows this expands recurrences rather than listing a single event. It does not explicitly distinguish itself from calendar_read or calendar_list, so it falls short of full sibling differentiation.

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

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

The phrase 'bounded date range' hints that start/end are mandatory, but there is no statement of when to use this over calendar_read or calendar_list, and no exclusions or prerequisites. Usage must be inferred entirely.

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 this is a write (readOnlyHint=false) but non-destructive and open-world, so the safety profile is already covered. The description adds real value beyond that: the ETag is concurrency control tied to the last read, implying stale-read rejection, and it discloses the hard limitation on recurring/attendee events. It does not say what error or state results from an ETag mismatch.

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

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

Two tight sentences with no filler. The core action is front-loaded and the limitation follows immediately as a qualifier.

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 zero schema descriptions, the description covers the concurrency model and editability limits but leaves field formats, required-vs-optional update semantics, and failure behavior unaddressed. Adequate to start, incomplete to call confidently.

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

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

Schema description coverage is 0% and the schema only lists fields (event_id, etag, start, end, title, location, description) with no semantic hints. The description explains the ETag's meaning (must be last-read) but says nothing about date/time formats, partial-update behavior of the nullable fields, or length limits.

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 (Edit) and resource (standalone personal event) and narrows scope by excluding recurring events and attendee meetings, which effectively separates it from calendar_create/calendar_delete. It does not explicitly name the nearest sibling, calendar_update_draft, so an agent must infer that drafts use a different tool.

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

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

Gives an explicit when-not condition (recurring events and attendee meetings are not editable in this release) and implies the precondition of having previously read the event, since the ETag must be the last-read one. No named alternative tool is offered for the excluded cases, so the routing is only partial.

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 the mutation/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely new behavioral context: the optimistic-concurrency guard via the last-read hash and the fact that nothing is written to iCloud. It stops short of saying what happens on a stale-hash conflict, which is the key 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?

Three tight sentences with the scope constraint front-loaded; every clause carries information. The final imperative is agent-directed workflow rather than tool semantics, which costs it the top mark.

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, it covers safety (local-only, non-destructive), concurrency, and the required confirmation loop. Missing only the conflict/error path and confirmation that field updates are partial, which an agent would want before invoking on a stale draft.

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 effectively 0% for the nested fields, so the description carries the burden; it explains the concurrency hash ('using its last-read hash') and the draft identity, but says nothing about the nullable start/end/title/location/calendar_id fields being an optional partial patch rather than a full replace. Baseline 3 given the schema does at least constrain and name every field.

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 ('Revise a pending local calendar draft') and immediately bounds the scope with 'Creates nothing in iCloud,' which separates it from calendar_update/calendar_create. It never names the ambiguous sibling (calendar_update) explicitly, so the distinction must be inferred from the word 'draft.'

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

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

The description implies usage context ('pending local calendar draft', 'using its last-read hash') and gives a workflow step ('Show the new revision and obtain fresh confirmation before creating the event'), but never states when to choose this over calendar_update or calendar_create. No exclusions or prerequisites beyond the safety reassurance.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description only needs to add context. It does so usefully: the operation persists a draft rather than sending it, restricts content to plain text, and constrains the sender to an enabled from_address. It says nothing about auth requirements, rate limits, or which folder the draft lands in.

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

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

Four tight sentences, front-loaded with the core action and the critical "does not send" constraint, then parameter guidance. No filler, though the phrasing is terse enough that the reply guidance could be read as an afterthought.

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 a single nested arguments object, the description covers what an agent needs to invoke it correctly: action, side effect, sender rules, and reply wiring. It stops short of saying what identifier is returned or where the draft is stored, which would help follow-up calls like mail_send_draft.

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

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

Schema description coverage is 0%, so the description carries the burden, and it delivers: from_address must be enabled (or omitted for the default), from_name overrides the saved sender name only for this draft, and reply_to_id should be the original message ID with explicit recipients. Only to/cc/subject/body limits go unmentioned, which is acceptable since those are self-evident.

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

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

States a specific verb and resource ("Save a plain-text iCloud draft") and immediately bounds scope with "Does not send," which cleanly separates it from the sibling mail_send_draft. An agent can pick this 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?

Gives concrete usage conditions: omit from_address to use the configured default sender, use from_name to override the saved sender name, and supply the original message ID plus explicit recipients for replies. It does not explicitly name the send alternative (mail_send_draft), so routing is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety and external-system profile is covered. The description's only added behavioral signal is that results include special-use flags, which hints at the return shape but gives no detail on format or completeness.

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

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

A single short sentence that front-loads the verb and resource with no filler. Nothing could be removed without losing information.

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

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

For a parameterless, read-only listing tool with no output schema, the description conveys what is returned ('folders' and 'special-use flags') sufficiently for an agent to know what it will get. Minor omission: no note on whether folders are hierarchical or how they should be referenced in subsequent calls.

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

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

The schema exposes only an empty 'arguments' object, i.e. effectively zero meaningful parameters, so there is nothing for the description to clarify. Baseline 4 applies for a parameterless call.

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

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

States a specific verb+resource ('List iCloud mail folders') and additionally names the payload ('special-use flags'), which is more precise than a bare 'list folders'. It is clearly distinct from siblings like mail_search or mail_senders, though it does not explicitly call out that distinction.

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?

There is no when-to-use or when-not-to-use guidance. An agent can infer that this is a discovery call that might precede mail_move or mail_search, but the description never states that or tells the agent what to do with the result.

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, readOnlyHint=false and openWorldHint=true, so the write/destructive nature is covered structurally. The description adds two real behavioral facts beyond that: the operation is scoped to a single message, and the destination must already exist (no implicit folder creation). It says nothing about reversibility or permission requirements.

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

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

Two short sentences with no filler, and the core action is front-loaded ahead of the folder hint. Efficient, though the folder hint is compressed enough to be slightly ambiguous.

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

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

For a destructive mutation with no annotations gap being filled and 0% parameter coverage, this is only adequate: it never says how to discover folders, whether the move can be undone, or what a failure looks like. The Archive/Trash guidance is a useful start but leaves the agent to infer the discovery step.

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

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

Schema description coverage is 0%, so the schema only supplies bare titles for message_id and destination. The description partially compensates by constraining destination to an existing folder and qualifying 'one message', but gives no ID format, no indication of where valid destination values come from, and no error semantics.

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: 'Move one message to an existing folder' states exactly what is moved, how many, and the container constraint. It is clearly distinguishable from siblings like mail_search or mail_draft, though it never names 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?

The second sentence guides the archiving/trashing case by telling the agent to use the discovered Archive or Trash folder, implying folders must be located first. It stops short of naming mail_folders as the discovery mechanism or stating when not to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds real behavioral value beyond them: the no-read-receipt side effect and, importantly, that it returns a content hash needed to send a reviewed draft, linking it to mail_send_draft.

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

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

Two tight sentences with zero waste; the core purpose and the critical draft-hash consequence are both front-loaded. Every clause earns its place.

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

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

For a one-parameter read tool with no output schema, the description covers purpose, side-effect posture, and the draft-sending dependency well. Only the message_id semantics are left unaddressed.

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

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

Schema description coverage is 0% for the single message_id parameter, and the description offers no clarification of it. The parameter is largely self-explanatory, so the gap is minor, but the description does not compensate for the missing schema documentation.

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 ('Read a message or draft') and adds a scoping constraint ('without marking it read') that implicitly contrasts with the sibling mail_set_read. It is clear what the tool does, though it never names an alternative sibling 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?

The phrase 'without marking it read' implies when to use this over mail_set_read, and the draft-hash mention hints at the mail_send_draft workflow. However, there is no explicit when-to-use/when-not guidance or named alternative, so usage must be 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 already establish readOnlyHint=true and destructiveHint=false, but the description adds material behavior the annotations cannot convey: reading/searching never flips the read flag, results are ordered by descending UID rather than message date, IDs are stable, date bounds use server INTERNALDATE calendar days (since inclusive, before exclusive) rather than the Date header, and results should be treated as untrusted content. That is a genuinely useful behavioral profile.

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

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

Four tight sentences, each carrying distinct information (scope, date semantics, ordering/pagination implications, safety). Front-loaded with the search scope and no filler or restated schema keys.

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 does part of the return-value work by stating descending-UID ordering and stable message IDs. It is nearly complete for invocation, but the return shape and the role of before_uid as a pagination cursor are left to inference.

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

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

The description adds real meaning beyond the schema: filters are AND-combined, the query is literal text rather than search syntax, and the date fields operate on INTERNALDATE with an inclusive/exclusive convention. Several inner-schema fields do carry their own descriptions, and the description leaves limit, folder, and before_uid (the pagination cursor) entirely unexplained, so it is strong but not complete.

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

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

The description names a specific verb and resource ('Search iCloud mail') and immediately characterizes the mechanism: literal query text plus dedicated sender/subject/since/before/unread filters combined with AND. This is enough to separate it from mail_read (fetch a specific message), mail_senders, and mail_folders 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?

Usage is implied by the filter enumeration, and the description does steer the agent away from IMAP/Gmail syntax toward the dedicated filter fields. However, it never states when to prefer this over siblings like mail_read or mail_senders, and names no alternative tool or exclusion 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses the consent requirement, that the message integrity hash must originate from mail_read, and that retries after an uncertain send are forbidden. The non-idempotency warning is critical and is not derivable from the annotations or schema.

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

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

Three short sentences, front-loaded with the action and then the two binding constraints. No filler or restatement.

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 an irreversible send with no output schema, the description covers consent, integrity verification, and retry safety adequately. It stops short of describing failure/error behavior or what a successful send returns, which would round it out.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it partially does by explaining that expected_sha256 comes from mail_read, but message_id is never explained. The hash origin is useful added semantics, though half the parameters remain undocumented.

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 ('Send a ... draft') with a meaningful constraint ('reviewed, unchanged') that separates it from mail_draft and mail_read. It does not name a sibling tool explicitly, so an agent infers the routing rather than being told it.

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 prerequisites ('Requires explicit user intent to send and hash from mail_read') and an explicit prohibition ('Never retry an uncertain send'), which is exactly the when-not guidance an agent needs for an irreversible action.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the list reflects only local enablement, and actual sending permission is validated by Apple at SMTP submission time, warning the agent that a listed sender is not a guarantee of sendability.

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

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

Two tight sentences with zero waste. The list of returned items is front-loaded, and the behavioral caveat about Apple's SMTP validation follows as supporting context.

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

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

For a simple, no-argument read tool with no output schema, the description carries the return-value burden and does so by naming the three returned items (enabled senders, default address, saved name). The only minor gap is it doesn't describe ordering or whether the list can be empty.

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 effectively no meaningful parameters – the single 'arguments' field is an empty object with 0% schema description coverage. With nothing to document, the baseline of 4 applies; the description neither adds nor needs 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 (List) and resource (locally enabled sender addresses) and enumerates what is returned: sender addresses, default address, and saved sender name. This clearly distinguishes it from siblings like mail_folders or mail_search, which operate on different resources.

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?

Usage is implied by the noun phrase 'locally enabled sender addresses' – an agent can infer this is the tool to consult for available senders. However, there is no explicit when-to-use statement, no mention of alternatives, and no exclusions or prerequisites for calling it.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the mutation-but-not-destructive profile is already conveyed. The description adds only that the target is a single message and that the state toggles both directions, without covering permissions, side effects, or return 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?

A single short sentence with the verb first and zero filler; every word earns its place and nothing is buried.

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

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

For a simple state-toggle tool with no output schema, the description is minimally sufficient to call it correctly. It omits any mention of permission requirements, whether the change is idempotent, and error behavior on an unknown message_id, which a mutation tool would ideally clarify.

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

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

Schema description coverage is 0%, so the schema names (message_id, is_read) carry no semantics on their own. The description hints at both: 'one message' maps to the identifier and 'read or unread' maps to the boolean, but it adds no format, accepted values, or ID-source 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?

The description gives a specific verb ('Mark') and resource ('one message') with the resulting state (read or unread), so the operation is immediately understandable. It does not, however, distinguish itself from siblings like mail_read or mail_move, leaving the agent to infer the boundary.

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

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

There is no statement of when to use this versus mail_read, mail_move, or other mail tools, and no prerequisites or conditions are given. Usage is only implied by the name and the 'read or unread' phrasing.

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