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

Annotations already declare the operation is a mutation (readOnlyHint=false, destructiveHint=false, non-idempotent, open-world), so the safety profile is covered. The description adds one genuinely useful behavioral detail, that it is a *display* alarm, but says nothing about whether existing alarms are replaced or appended, permission requirements, or error behavior on an unknown uid.

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 zero filler; the core action comes first and the critical sign convention for minutes follows immediately. Nothing could be cut 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 non-idempotent mutation with no output schema and 0% parameter coverage, the description is too sparse: it omits how the target event is identified, whether the alarm replaces or adds to existing alarms, and what happens on failure. The minutes clarification is the only real content beyond the tool name.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only clarifies one of three parameters (minutes: negative means before the event). The required uid and calendar parameters are left entirely undocumented in both schema and description, so an agent cannot tell whether uid is an event id or something else, or how calendar scopes the lookup.

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 (add a display alarm to an event), which is clearly distinct from siblings like apple_calendar_set_recurrence, apple_calendar_set_url, and apple_calendar_update_event. It does not explicitly name those siblings, but the resource is specific enough for an agent to select correctly.

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

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

Usage is only implied: you add an alarm to an existing event identified by uid/calendar. There is no explicit when-to-use vs. when-not, no mention of prerequisites (the event must already exist), and no pointer to alternatives such as updating the event itself. Adequate but thin.

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 this is a write, non-destructive, non-idempotent, open-world operation. The description adds genuinely useful context beyond that - the calendar is placed in the 'app default account' rather than a caller-specified one, which matters since no account parameter exists. It still omits duplicate-name handling and permission requirements, so it does not exceed a 3.

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 no wasted words. Appropriate length for a simple two-parameter create tool, though it is terse enough that it could have used its remaining room to cover parameters.

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 create tool with annotations covering the safety profile, the description is minimally adequate but leaves parameter semantics and the account/return behavior largely unstated, with no output schema to fill the gap. It is sufficient to invoke, not to invoke 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 description never mentions the 'name' or 'description' parameters. The intuitive field names partially rescue it, but the description fails to compensate for the documented gap, and the 10000-char description default is left unexplained.

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 (Create) and resource (Calendar.app calendar) plus the target account context, which distinguishes it from siblings like create_event, delete_calendar, or rename_calendar. It does not explicitly name a sibling to differentiate from, so it stops 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 description offers no when-to-use guidance, no prerequisites, and no comparison to alternatives such as list_calendars or rename_calendar. Usage is only implied by the verb 'Create'.

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=false, and openWorldHint=true, so the write profile is largely covered structurally. The description adds only the qualifier 'local' (implying a local Calendar.app store rather than a synced/remote calendar) but says nothing about duplicate-prevention behavior despite idempotentHint=false, nor about required permissions or what a repeated call produces.

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 no wasted words, which satisfies conciseness in size. But the brevity here reflects under-specification rather than disciplined conciseness, since key invocation-relevant detail is simply absent.

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 7 mostly-undocumented parameters, no output schema, and no parameter descriptions, the description does far too little. It does not explain the required date-time inputs, default handling for optional fields, or the resulting event identity, leaving an agent unable to call it 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 only 14% (just 'calendar'), and 7 parameters with 4 required are otherwise undocumented. The description contributes zero parameter information — nothing about the required start/end date-time format, the meaning of allDay, or how title/location/notes are handled — so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource combination ('Create a new ... event') that is unambiguous in isolation and distinct from sibling resources like create_calendar or update_event. However, it does not explicitly differentiate itself from the other calendar-event mutators (update_event, add_alarm, set_recurrence), leaving that routing to inference from the 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?

The description offers no when-to-use context, no prerequisites (e.g., that the target calendar must already exist), and no mention of alternatives such as apple_calendar_update_event or apple_calendar_create_calendar. The agent must infer everything from the tool name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered by structured data rather than the description. The description does add genuinely new behavioral context beyond annotations: the deletion cascades to all events in the calendar. It says nothing about irreversibility or confirmation, so this is a modest add on top of 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?

Two short sentences with no filler; the scope of destruction is stated first and the 'Destructive.' flag is front-loaded as a warning.

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

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

For a single-parameter delete tool whose annotations already cover the safety profile, the description is nearly sufficient, but it omits how to identify the target calendar and whether the deletion is reversible, which matters for an irreversible cascade delete.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'calendar' parameter. The word 'uniquely named' hints that the parameter is a calendar name that must be unique, which is real added meaning, but it does not clarify whether a name or identifier is expected or how to obtain 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?

The description gives a specific verb (Delete) and resource (a uniquely named writable calendar), and the phrase 'and all its events' makes clear this is not the single-event delete sibling apple_calendar_delete_event. It does not name that sibling explicitly, so it stops short of full 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?

There is no when-to-use guidance and no mention of alternatives such as apple_calendar_delete_event for removing individual events, nor any prerequisite like locating the calendar first via apple_calendar_list_calendars. The single word 'Destructive.' is a warning, not 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?

The description adds 'existing' and 'local' context beyond the annotations, which already declare destructiveHint. It explicitly states 'This is destructive,' which reinforces the annotation but does not add significant new behavioral details such as permissions or reversibility.

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

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

The description is two concise sentences, delivering the essential purpose and destructive nature without any unnecessary wording. It is well-structured and front-loaded.

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

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

For a simple delete tool, the description is adequate but lacks specifics about behavior when the event is not found, return values, or prerequisites. The annotations and schema cover some aspects, but the description could provide more context for complete understanding.

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 50%, with only 'calendar' having a description. The tool description does not explain 'uid' at all, leaving it ambiguous. Since there are only two parameters, the description should have clarified that uid is the event identifier, but it 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?

The description clearly states the tool deletes an existing local Calendar.app event, using a specific verb and resource. It distinguishes itself from sibling tools like create_event or list_events by focusing on deletion and specifying 'local Calendar.app'.

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: use this tool when you need to delete an existing local Calendar.app event. However, it does not explicitly mention when not to use it or provide alternative tool recommendations, leaving the guidance mostly implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only:' adds nothing new. What does add value is the enumeration of returned fields (notes, recurrence, URL, attendees, alarms) — meaningful disclosure given there is no output 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?

A single front-loaded sentence with no padding, and the returned-field list is compact. The 'Read-only:' prefix is a small redundancy against annotations that already state this.

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 carry the return-value burden and partially meets it by naming the fields returned. However, it omits any explanation of the two required inputs or failure behavior when an event/calendar is not found, leaving real gaps for a lookup 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?

Two required parameters (uid, calendar) with 0% schema description coverage, and the description says nothing about them. It does not clarify whether calendar is a name, ID, or path, nor what form a uid takes, so the description fails to compensate for the schema 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?

The description names a specific verb (get) and resource (event) and enumerates the payload it returns (notes, recurrence, URL, attendees, alarms). This distinguishes it from apple_calendar_list_events and the mutation siblings like create/update/delete_event, though it never explicitly names those alternatives.

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 only implied: 'get' suggests fetching a single event's details in contrast to list_events. There is no explicit when-to-use statement, no prerequisites, and no instruction on when to prefer this over reading an event via list_events.

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

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

The description explicitly labels the tool as 'Read-only,' matching the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true). It adds valuable context by specifying the output includes calendar names and writable status, which goes beyond what the annotations convey. No contradictions.

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

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

The description is a single, well-structured sentence. It front-loads the 'Read-only' behavior, states the resource and output, and gives a usage directive. Every word earns its place with zero redundancy.

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

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

Given the tool's simplicity (no parameters, no output schema), the description fully covers its purpose, output, and context. The usage note about creating/modifying events provides the needed situational context, making the tool complete for an agent to select and invoke 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?

The tool has zero parameters, so the schema fully covers any inputs (none). The description adds no parameter details, but none are needed. The baseline for 0 params is 4, and the description's mention of listing names and writable status already implies what is returned.

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

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

The description states a specific action ('list local Calendar.app calendar names') and the output detail ('whether each calendar is writable'). It also connects to sibling tools by indicating it is a precursor to creating or modifying events when the calendar name is unknown, distinguishing it from event-related tools.

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

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

The description provides an explicit usage condition: 'Use this before creating or modifying events when the exact calendar name is unknown.' This clearly tells the agent when to invoke this tool and implicitly when not (when the calendar name is known). It gives actionable context without naming alternatives, which is sufficient for the simple use case.

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 readOnly, idempotent, and non-destructive behavior, so the leading 'Read-only' prefix is largely redundant. The description adds only that scope is 'local Calendar.app', which doesn't clarify pagination, ordering, recurring events, or the limit default beyond what annotations and schema 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?

A single short, front-loaded sentence with the key verb and resource at the start. It wastes minimal space, though the 'Read-only:' prefix duplicates annotation data rather than earning 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?

With no output schema, the description carries more burden, yet it omits return shape, ordering, pagination via limit, and whether recurring events are expanded. It is minimally adequate for a read-only list tool but leaves real gaps.

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

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

Schema coverage is 75%, close to the high-coverage baseline where the schema does the heavy lifting. The description adds no parameter detail at all and notably says nothing about the undocumented limit parameter (default 50, max 100) or how calendars filtering interacts with the time range.

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), resource (Calendar.app events), and scope (a time range), which cleanly separates it from apple_calendar_get_event. However, it does not name any sibling tool or explicitly contrast with them, so it falls short of the 5 bar for 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?

No when-to-use guidance, no exclusions, and no mention of alternatives like apple_calendar_get_event or apple_calendar_list_calendars. The only contextual hint ('in a time range') is already implied by the required start/end parameters.

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 non-idempotent, so the safety profile is covered externally. The description adds the useful constraint that the target must be uniquely named and writable, hinting at an ambiguity failure mode, but says nothing about error behavior or what happens on non-unique matches.

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 short sentence, front-loaded with the verb and resource. No waste, nothing to trim.

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 output schema, the single sentence plus annotations covers the safety basics, but omits matching behavior, failure modes, and confirmation of what the rename affects. Adequate but thin for a destructive operation.

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

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

Schema coverage is 0% and neither parameter is documented in the schema. The description implies 'calendar' is a unique name and that a new name is required, but does not clarify matching semantics (exact name vs id) or name constraints, leaving real ambiguity for the caller.

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 (rename) and resource (calendar), and adds a scope qualifier ('uniquely named writable'). It is clearly distinguishable from create_calendar and delete_calendar siblings, though the qualifier is terse.

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

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

No when-to-use guidance, no prerequisites, and no reference to alternatives such as apple_calendar_create_calendar or apple_calendar_delete_calendar. The agent must infer that this is the mutating rename path from the name alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond them: that the calendar validates the rule (so it can fail) and that an empty string is the clearing sentinel rather than an error.

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

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

A single dense sentence whose clauses (example format, clear sentinel, validation note) each add distinct information, with the primary action front-loaded.

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

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

For a setter with no output schema, the description covers the semantically tricky parts (rule format, clearing, validation). It is nearly complete; only the semantics of uid/calendar selection are absent, which the bare schema also omits.

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

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

Schema description coverage is 0% across 3 required params, so the description must carry the load. It documents the 'recurrence' format and its empty-string edge case well, but 'uid' and 'calendar' receive no explanation at all, leaving the coverage gap half-filled.

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: 'Set an event recurrence rule', with a concrete RFC-5545 style example. The recurrence focus makes it reasonably distinguishable from siblings like apple_calendar_update_event or apple_calendar_add_alarm, though it doesn't explicitly name what it is not.

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?

'empty string clears recurrence' hints at when you would call it in the clear case, but there is no explicit guidance on when to use this tool versus apple_calendar_update_event, nor any prerequisites (e.g. event must already exist).

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

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

Annotations already declare destructive, idempotent, and open-world behavior, so the safety burden is largely covered. The description adds the useful fact that the operation can clear (not just set) a URL, but it does not explain that an existing URL is overwritten, what error occurs for a bad UID, or any 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?

A single short sentence with the action front-loaded and no filler. Nothing in it 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?

For a destructive mutation with zero parameter documentation and no output schema, the description is too thin. An agent cannot tell how the event is identified (calendar + uid), whether the change is reversible, or what a clear operation returns.

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

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

Schema description coverage is 0%, so the description must compensate. It hints that url is an HTTP/HTTPS value and that empty clears it, partially explaining the anyOf empty-string branch, but it says nothing about the calendar or uid identifiers that are required to locate the event.

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 pair (set/clear) and a specific resource (an event's HTTP/HTTPS URL), which is distinct from calendar siblings like set_recurrence or add_alarm. It does not, however, explicitly differentiate itself from apple_calendar_update_event, which plausibly could also touch a URL.

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 tool versus update_event or the other calendar mutation tools, no prerequisites, and no indication of what happens on failure. Usage must be inferred entirely from the name and event-URL semantics.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, so the safety profile is covered and the description's 'Modify' is consistent with it. The description adds the uid-sourcing workflow but says nothing about whether omitted fields are preserved, whether this is a partial or full replacement, or what the destructive aspect actually destroys.

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, front-loaded with the action and immediately followed by the one prerequisite the agent needs. 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 destructive, 8-parameter mutation with no output schema, the description is far too thin: it does not explain partial-update semantics, field replacement behavior, or what the destructive hint applies to. An agent has almost no guidance beyond the tool name.

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 13% (only 'calendar' is documented) across 8 parameters, so the description carries the compensation burden and does not meet it. It clarifies where uid comes from but adds no meaning for start/end, title, notes, location, or allDay, nor whether they are optional partial updates.

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 (Modify) and resource (an existing local Calendar.app event), and 'existing' implicitly distinguishes it from apple_calendar_create_event and apple_calendar_delete_event. It does not, however, distinguish it from the other calendar mutators (set_recurrence, add_alarm, set_url).

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 one concrete prerequisite – obtain the uid from apple_calendar_list_events – which is a real workflow pointer. It never says when to use this tool versus the narrower siblings that mutate a single aspect of an event (add_alarm, set_recurrence, set_url), so usage is implied 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 this is a non-readonly, idempotent, non-destructive, open-world mutation, so the safety profile is covered. The description adds 'and save Contacts changes', clarifying that the change is persisted immediately with no separate save step. It does not cover failure modes such as a missing contact or 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?

A single efficient sentence that front-loads the action and adds the persistence detail without any wasted words.

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

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

For a simple two-parameter mutation with annotations covering safety and no output schema, the description is adequate but leaves gaps: no mention of what happens on an invalid contactId or groupId, no idempotency restatement beyond annotations, and no parameter format detail.

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

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

Schema coverage is 0%, so the two required parameters (contactId, groupId) have no structured documentation. The description only obliquely implies the parameters refer to a contact and a group, without specifying identifier format, whether names are accepted, or whether the group must pre-exist.

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+resource pair ('add an existing contact to a group'), which is unambiguous and clearly distinct from the sibling apple_contacts_remove_from_group. It does not explicitly name siblings, but the action is self-evident from the name and text.

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 guidance on when to use this tool versus alternatives such as apple_contacts_update or apple_contacts_remove_from_group, and no stated prerequisites (e.g., that both the contact and group must already exist). The only implicit signal is 'existing contact'.

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 non-read-only, non-destructive, non-idempotent, open-world, so the safety profile is covered. The description adds one genuinely non-obvious behavior — it refuses to run while Contacts has unsaved edits — but omits permissions requirements, duplicate-contact handling, and whether a newly created contact is returned.

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 front-loaded and the exceptional precondition second. Every clause adds 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 7-parameter mutation tool with no output schema, the description plus annotations cover the essentials (it writes, it is not idempotent/destructive, it may fail on unsaved edits). However, with zero schema description coverage, an agent still lacks guidance on which fields matter and what happens on success or on duplicate creation.

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 only addresses labeled emails and phones, leaving firstName (the sole required field), lastName, note, jobTitle, and organization unmentioned, even though the schema structure itself (required, formats, defaults) is reasonably self-explanatory.

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 and save a contact') and indicates the optional payload shape (labeled emails and phone numbers). It is distinguishable from apple_contacts_search/get/update by the create verb, but it never names or contrasts with the closest sibling, apple_contacts_update.

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 guidance on when to use create vs apple_contacts_update or apple_contacts_add_to_group, and no alternatives are named. The only conditional statement is an operational precondition (unsaved edits), not a selection hint.

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 write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the safety burden is largely carried. The description adds a genuinely non-obvious behavioral trait: the call will fail if there are pending unsaved Contacts edits, which an agent cannot infer from 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?

Two short sentences with zero filler; the core action is front-loaded and the caveat follows immediately. Nothing could be cut 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 simple single-parameter create tool with annotations covering the safety profile and no output schema, the description is minimally adequate. It omits name-related constraints (e.g., uniqueness/duplication behavior) and does not mention what happens on success, leaving gaps an agent might want filled.

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 would need to compensate for the single 'name' parameter, and it says nothing about it. The parameter is self-evident from its name and the schema enforces minLength/maxLength, so the gap is minor, but the description adds no meaning 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?

The description states a specific verb ('Create and save') and resource ('a Contacts group'), which inherently separates it from apple_contacts_create (a person) and apple_contacts_add_to_group (existing group). It stops short of naming any sibling or scope constraints, so it is clear but not fully differentiated.

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 tool versus alternatives such as apple_contacts_create or apple_contacts_add_to_group. The only contextual sentence is a precondition ('Refuses pending unsaved Contacts edits'), which is a constraint rather than usage routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only:' in the description is largely redundant. The phrase 'bounded notes' adds a small amount of value by hinting that note content may be truncated, but no truncation rule, not-found behavior, or permission requirement is given.

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 no filler; the returned-field list is the most useful part and comes early. The leading 'Read-only:' clause is the one element that duplicates annotation data rather than adding 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 usefully enumerates the returned fields, which is the right move. However, it omits how contactId is sourced, how maxChars affects output, and what happens when no contact matches, leaving gaps for a two-parameter read tool.

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

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

Schema description coverage is 0% for two parameters, so the description carries the burden and does not meet it. It never explains what contactId is, how to obtain it, or what maxChars controls, beyond the vague 'bounded notes' phrase that loosely gestures at the truncation limit.

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') and enumerates the returned fields (names, organization, emails, phones, notes). The singular 'one contact' implicitly distinguishes it from apple_contacts_search and apple_contacts_list_group_members, but no sibling is 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?

Usage is only implied: fetching a single contact is contrasted with list/search by the word 'one'. There is no statement of when to prefer this over apple_contacts_search or what prerequisite (a known contactId) is needed.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, and the description's 'Read-only:' prefix largely restates that. The only added behavioral signal is 'summaries,' implying a reduced field set. Pagination behavior, ordering, and what happens when a group is empty or the offset exceeds the member count are not disclosed.

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 scope front-loaded and no filler; it is easy to scan. It loses a point only because the 'Read-only:' clause duplicates information already carried by the annotations rather than earning 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?

There is no output schema, so the description need not explain return values, and the annotations cover the safety profile. However, for a paginated list tool with a default page size of 20 and zero schema documentation, the absence of any pagination or result-size guidance leaves a real gap 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 description coverage is 0% across three parameters, so the description carries the full burden — yet it only implies groupId via 'one Contacts group' and says nothing about limit or offset. The default limit of 20 means results are silently truncated, and the description gives no hint of that or of how to page through members.

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 (list) and a precisely scoped resource (summaries of people in one Contacts group), which separates it from siblings like apple_contacts_list_groups and apple_contacts_add_to_group. The word 'summaries' also hints that only lightweight fields are returned. It stops short of naming the alternatives an agent might confuse it with, so it is clear but not sibling-routing.

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 only implied: the 'one Contacts group' scope tells the agent a groupId is required, but there is no explicit when-to-use versus apple_contacts_search, apple_contacts_get, or apple_contacts_list_groups. No prerequisites, exclusions, or alternative-routing guidance are 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, idempotentHint=true, and destructiveHint=false, so 'Read-only:' simply restates structured data and adds no new behavioral context. With annotations covering the safety profile, the description could still add value about pagination or return shape but does not.

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 no waste and the key operation front-loaded. It is efficient, though the brevity tips into under-specification rather than disciplined concision.

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

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

The tool is simple (no output schema, no nested objects, two optional params), so expectations are low, but the undocumented pagination behavior on a list endpoint is a real omission. Without a mention of limit/offset defaults or paging, the description is only minimally 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?

Both parameters (limit, offset) have 0% schema description coverage, and the description never mentions them or their pagination semantics. Since the schema does none of the heavy lifting here, the description was obligated 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 and resource ('list Contacts groups'), so an agent knows exactly what the tool returns. It does not, however, differentiate itself from nearby siblings such as apple_contacts_list_group_members or apple_contacts_list_accounts, leaving the agent to infer scope from the name alone.

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 guidance, no stated prerequisites, and no mention of alternatives despite several plausible siblings (list_group_members, search, get). The agent gets no routing help beyond the tool name.

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 full safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), so the bar is lower. The description adds real context — that changes persist to Contacts ("saves Contacts changes") and that the contact itself is preserved — though it does not touch error handling (e.g., contact not in group) or auth. The mutation/persistence framing sits fine alongside the destructiveHint.

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

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

A single front-loaded sentence: verb+resource first, then two tight clarifying clauses separated by a semicolon. No filler, 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 two-required-parameter mutation with no output schema and annotations already covering the safety profile, the description covers intent, persistence, and scope (contact preserved). Only edge-case behavior and return-value expectations are unaddressed, which is minor here.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only weakly does: "a contact" and "a group" map to the two self-explanatory names contactId/groupId but no ID format, source, or constraint detail is added. Self-evident parameter names keep this at a minimum-viable 3 rather than lower.

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 (remove a contact from a group) and immediately scopes it by clarifying the contact survives ("without deleting the contact"). This lets an agent distinguish it from a destructive contact delete without opening any schema, which is exactly the disambiguation needed against siblings like apple_contacts_add_to_group and any delete-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?

Usage is only implied: the phrasing "without deleting the contact" hints that this is the lighter-weight alternative to contact deletion, but no explicit when-to-use, when-not, or named alternative tool is given. Adequate but leaves routing inference to the agent.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so 'Read-only' is largely redundant. However, 'Returns summaries, not all contact details' is genuinely valuable behavioral context given there is no output schema, and it warns the agent that full details require another call.

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 waste, and the safety/scope note is front-loaded ahead of the return-shape caveat.

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 read-only search tool with rich annotations and no output schema, the description covers scope and return shape adequately. The remaining gap is pagination behavior for limit/offset, which the description does not address.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It explains only 'query' (substring match against name/organization); limit and offset are left completely undocumented in both schema and description.

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 ('find'), resource ('contacts'), and the matching semantics ('by name or organization substring'). This clearly distinguishes it from apple_contacts_get (fetch one contact) and apple_contacts_list_groups.

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 substring-matching search phrasing, but there is no explicit statement of when to prefer this over apple_contacts_get or when not to use it. No prerequisites or alternatives are named.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false. The description adds genuinely new context on top: which field collections are preserved (phone/email) and that the call refuses while unsaved Contacts edits are pending. That state-dependent refusal is the kind of behavior annotations cannot express.

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, no filler, with the scope of the write front-loaded and the constraints (unchanged collections, refusal condition) following immediately. Every sentence carries distinct 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, so the description is not obliged to describe returns, and the mutation/precondition facts are present. Still missing for a 6-param update tool: where contactId comes from, and confirmation that unmentioned fields beyond phone/email are left untouched. Adequate but with visible gaps.

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

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

Schema description coverage is 0%, so the description carries the burden, and it names four of the five payload fields (name covering firstName/lastName, organization, jobTitle, note). The required contactId is never explained — no hint on format or how to obtain it — and there is no statement of what happens to omitted optional fields. Partial compensation only.

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+resource ('Update and save selected name, organization, job title, or note fields') and enumerates exactly which fields are in scope, so an agent knows this is a contact-field mutation rather than a general contact write. It never names a sibling tool (e.g. apple_contacts_create or apple_contacts_get) to route against, which keeps it 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?

'Refuses pending unsaved Contacts edits' is a useful precondition, and 'Leaves phone and email collections unchanged' delimits scope. However, there is no explicit when-to-use guidance versus alternatives (apple_contacts_create, apple_contacts_get) and no statement of what to do when the refusal fires. Usage is implied 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 mark this as a non-readOnly, non-destructive, non-idempotent, open-world write. The description adds genuinely new behavior: it never overwrites a destination, and copying is constrained to allowed roots. That is meaningful context beyond the annotation set, though it omits what happens on collision (error vs skip).

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 the operation front-loaded and the key constraint (no overwrite) second. 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?

Annotations cover the safety profile and there is no output schema to explain, but with two fully undocumented parameters and no failure semantics, the definition leaves real gaps for a file-mutation tool operating in a sandboxed root set.

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% and neither 'source' nor 'destination' is described anywhere. The description does not state path format, whether paths are absolute or relative, or whether the destination is a file path versus a directory, leaving both parameters underspecified.

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 (copy) and resource (one regular file) with a scope qualifier ('within allowed roots'), which separates it from siblings like apple_files_write_text or apple_files_trash. It stops short of naming an alternative, but the operation is unambiguous.

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 guidance on when to choose copy over other file operations, no prerequisites, and no mention of failure behavior when the destination exists (despite stating it never overwrites). An agent must infer usage from the name alone.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description usefully adds that only one folder is created and that it must sit under an already-allowed parent (no parent auto-creation, sandbox concept), but it does not describe failure/error behavior or permission requirements in 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?

One tight sentence with the resource and its key constraint front-loaded and no filler. Appropriately sized for a single-parameter tool, though it could add a few words of value without becoming bloated.

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 one-parameter mutation tool with annotations covering the safety profile, the definition is minimally viable. It omits parameter format and any note on the 'allowed folder' concept or error behavior, leaving gaps an agent would have to guess at.

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 single 'path' parameter has 0% schema description coverage, and the description never explains it (full path vs relative, format, whether it includes the folder name). With coverage well below 50%, the description fails to compensate for the schema gap.

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

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

States a specific verb (Create) and resource (folder) with a clear constraint that it makes exactly 'one new folder' under 'an existing allowed folder.' An agent can distinguish this from read/list/search siblings, though it doesn't explicitly differentiate from the similarly named apple_notes_create_folder.

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 'under an existing allowed folder' implies a prerequisite (the parent must already exist and be within the allowed set), giving implicit usage context. However, there is no explicit when-to-use, when-not-to-use, or named alternative, so guidance remains inferential.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the meaningful constraint 'within allowed roots,' but does not disclose error behavior, permission requirements, or output characteristics beyond that.

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

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

The description is a single, front-loaded sentence fragment with no wasted words. It is efficient, though its extreme brevity contributes to gaps captured in other dimensions.

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 one-parameter tool with no output schema, the description is too sparse: it does not explain what metadata is returned or how the path parameter behaves. Annotations cover safety, but the description leaves important operational context 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 single 'path' parameter has 0% schema description coverage and the description does not explain its format, whether it must be absolute or relative, or how allowed roots are resolved. 'Within allowed roots' gives a partial constraint but fails to compensate for the missing parameter 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?

The description states a specific operation ('file/folder metadata') and a scope ('within allowed roots'), making it clear this is a read-only metadata retrieval tool. It does not explicitly differentiate from siblings like apple_files_list or apple_files_read_text, but the resource and read-only framing are clear.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention conditions, exclusions, or sibling tools such as apple_files_list or apple_files_read_text, leaving usage entirely 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine extra behavior: the listing is non-recursive, spans only one allowed folder, is bounded, and hides dotfiles by default — all traits the annotations do not convey.

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

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

A single tight sentence with the safety qualifier front-loaded ahead of the scope details; every clause earns its place. Slightly too terse given the 0% schema coverage, but no wasted words.

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

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

For a read-only list tool with no output schema, the description covers safety, scope and defaults adequately, but leaves the allowed-folder restriction and the limit/hidden parameters undocumented for an agent to discover. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description carries the burden for all three params. It gestures at each one ('one allowed folder' for path, 'bounded' for limit, 'hidden entries excluded by default' for includeHidden) but never names them, gives no limit range, and does not explain the allowed-folder sandbox constraint.

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 one allowed folder') and adds the distinguishing scope constraint that it is bounded and non-recursive, which separates it from recursive traversal or the sibling apple_files_search substring search. It does not name that sibling explicitly, so it stops 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 description implies the use case (enumerate entries in a single directory) and its non-recursive scope rules out tree walking, but it never states when to prefer this over apple_files_search, apple_files_info, or apple_files_read_text. No explicit when-to-use or 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds two genuinely useful facts not in annotations: reads are 'bounded' (implying truncation via maxBytes) and only 'allowed regular files' are accepted (implying a path allowlist / non-directory constraint). It does not say what happens on encoding failure, unreadable paths, or oversized files, so it stops short of rich behavioral disclosure.

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 tightly written sentences, no filler, with the read-only/bounded contract front-loaded and the format exclusion second. 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?

There is no output schema, so the description should clarify what a caller receives; 'read bounded UTF-8 text' implies a string result but omits whether truncation is signaled, how errors surface, and path resolution rules. Adequate for a simple idempotent read, but the parameter and return-shape gaps leave an agent to guess.

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 both parameters, so the description carries the burden. 'Bounded' loosely gestures at maxBytes but never explains truncation behavior, the default, or the upper bound, and 'allowed regular file' hints at path validation without stating expected path form (absolute, ~ expansion) or the allowed root. Two undocumented parameters with only oblique hints warrants a 2.

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 ('read bounded UTF-8 text') and explicitly carves out what it is not for ('Does not parse Pages, PDF, or other binary formats'), which distinguishes it from siblings like apple_pages_read_text and the TextEdit readers. An agent can classify this as a raw plain-text file reader 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?

The exclusion of Pages/PDF/binary formats implies when this tool applies versus format-aware readers, but the description never names an alternative tool or states a positive use condition beyond 'allowed regular file'. Usage is inferable rather than explicit.

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 safety (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds a genuinely useful caveat: results depend on local Spotlight indexing, meaning misses are possible. 'Read-only' duplicates the annotation, but the indexing caveat and the single-folder constraint are real added behavioral context.

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

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

Two short sentences, front-loaded with the read-only nature and the operation, with the indexing caveat immediately after. No wasted words.

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

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

For a 3-parameter tool with no output schema, the description covers the core operation and dispatch-relevant caveat, but omits any mention of the limit parameter or result shape (names vs. full paths, pagination). It is adequate but 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 0% for 3 parameters. The description clarifies the 'path' parameter (one allowed folder) and the 'query' parameter (filename matching, not content), which is meaningful beyond the schema. However, 'limit' is completely unaddressed and no format guidance for the query string is given, so compensation is only partial.

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 ('Spotlight filename search') plus scope ('within one allowed folder'), which cleanly separates it from siblings like apple_files_list (enumeration) and apple_files_read_text (content read). The keyword 'filename' even clarifies that it matches names rather than file contents.

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 'within one allowed folder' scope implies the path must be a permitted directory, which is useful context, but there is no explicit when-to-use vs. when-not guidance and no named alternative (e.g., apple_files_list) for agents that want unfiltered enumeration.

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 destructiveHint/openWorldHint annotations, it discloses genuinely useful behaviors: symbolic links are refused (and why), deletions may propagate through iCloud, and it stops short of emptying Trash. These are safety-relevant facts not derivable 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?

Four short sentences, front-loaded with the core action and followed by constraints and side effects. No filler; each sentence carries distinct 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 destructive mutation with annotations already declaring reversibility-relevant hints, the description covers behavior and side effects well. The one soft spot is the unexplained "allowed" qualifier, but overall it is sufficient to call the tool 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 0% and the schema only documents the path string's bounds. The description adds constraints on the target: it may be a file or folder, must be "allowed," and must not be a symlink, which meaningfully enriches the parameter's 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?

States a specific verb ("Move") and resource ("file or folder") with the destination ("Finder Trash"), which cleanly separates it from sibling tools like apple_files_copy, apple_files_write_text, and apple_files_read_text.

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 verb and clarified by the boundary "Never empties Trash," but there is no explicit when-to-use condition or named alternative sibling. Since no other sibling performs deletion, routing risk is low, but the guidance is not 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=false and destructiveHint=true, so the safety profile is covered. The description adds a meaningful behavioral detail (existing files need overwrite=true), but omits what happens on failure, what 'allowed folder' means, and any 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, zero waste, with the core action front-loaded and the overwrite caveat following. Nothing redundant.

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

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

For a destructive write tool with no output schema and no annotated description, it covers the essentials (create, UTF-8, allowed-folder scope, overwrite gate). It leaves the concept of 'allowed folder', error behavior, and return format 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 coverage is 0% with 3 parameters, so the description carries the burden. It explains overwrite's role and behavior, but path and text are left to their names and constraints (maxLength, minLength) are undocumented anywhere.

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 UTF-8 file') plus a scoping constraint ('in an allowed folder'), which clearly separates it from read-only siblings like apple_files_read_text. It stops short of naming alternatives explicitly, but the action is unambiguous.

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 note 'Existing files require overwrite=true' gives a usage rule for the overwrite case, but there is no when-to-use vs alternatives guidance (e.g., versus apple_textedit_create or apple_files_copy). Usage is only implied.

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 and destructiveHint=false, so the safety profile is covered. The description's only added behavioral detail is the constraint that only 'allowed' paths can be revealed, which is useful but leaves open what happens on success (Finder window opens? item selected?) and on a disallowed path.

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

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

A single front-loaded sentence with no filler. It is efficient, though the extreme brevity leaves room for one more clause of operational detail.

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 tool with no output schema and no parameter documentation, the description should carry more: what 'reveal' does concretely, what the response contains, and what the 'allowed' restriction means. Annotations cover safety but not behavior, so gaps remain.

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 'path' parameter, and the description only says it is a 'file or folder' path. It does not clarify whether the path must be absolute, POSIX-style, tilde-expanded, or relative to an allowed root.

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 ('reveal') and resource ('file or folder in Finder'), and the word 'allowed' hints at a permission scope. It is clear enough for an agent, though it does not fully distinguish itself from nearby siblings like apple_finder_selection or apple_files_info.

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 guidance on when to use this versus alternatives such as apple_files_info (inspect metadata) or opening the file in its app. The agent must infer the use case from the verb alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds value by disclosing the return shape (names and URLs) and the 'does not read contents' limitation. It omits pagination/limit behavior, which is the only remaining gap.

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

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

Two short sentences, front-loaded with the read-only nature and the return payload. Every clause earns its place 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 simple read-only tool with no output schema, the description adequately conveys what is returned and what is not read. The only incompleteness is the undocumented limit parameter and resulting pagination behavior.

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 single parameter 'limit' (default 100, max 500) is never mentioned in the description. The description does not compensate for the coverage gap, leaving bounds and paging semantics unexplained.

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 ('get') and resource ('selected Finder items') with an explicit scope of what is returned ('names and URLs'). It is clearly distinguishable from siblings like apple_finder_reveal and apple_files_list, though it doesn't name an alternative to route against.

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?

'Does not read contents' implies a boundary and hints at when to use a different tool (e.g. apple_files_read_text), but no alternative is named and no explicit when-to-use condition is given. Usage is implied 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 readOnly=false, idempotent=false, destructive=false and openWorld=true, so the safety profile is covered. The description adds one genuinely new behavioral fact — 'Changes may autosave and sync' — but says nothing about failure modes, invalid layout names, or where the slide lands relative to the required document.

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, front-loaded with the action, with no filler. The second sentence about autosave is short and earns its place by flagging a side effect.

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 6-parameter mutation with no output schema, the definition omits the most consequential detail: what it returns and how the agent identifies the newly appended slide for a later apple_keynote_update_slide call. The documentName prerequisite (document must exist/open) is also left implicit.

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

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

Schema coverage is only 17% (documentName alone), so the description must carry the rest; it names every remaining parameter and adds real meaning — layoutName must be an *exact* master-slide layout name, and title/body are *default* (placeholder) values that can be changed later. It stops short of saying how to discover valid layout names or how 'skipped' behaves in presentation mode.

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 ('Append a Keynote slide') plus the fields it can set, so an agent can distinguish it from apple_keynote_update_slide and apple_keynote_create. It does not explicitly name the sibling it differs from, so it falls short of the top band.

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

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

No when-to-use guidance, no prerequisites (e.g. must the document already be open, does documentName refer to an open doc?), and no routing against the obvious alternative apple_keynote_update_slide. The only conditional hint is the word 'optionally' attached to layoutName.

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

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

Annotations only say this is a destructive, non-idempotent, non-read-only operation; the description goes further by disclosing the two refusal conditions (unsaved changes, no saved path) and the discardChanges override, which tells the agent exactly what is at risk. This is exactly the 'what gets destroyed' context that annotations cannot express.

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 the core action front-loaded and the constraints following; every clause carries information (verb, refusal conditions, override, alternative). The semicolon-joined second sentence is slightly compressed but not padded.

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

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

For a two-parameter destructive tool with no output schema, this covers the essential decisions: how to identify the document, what blocks the close, how to force it, and how to preserve changes. It stops short of describing post-close state (e.g., whether the app or window remains open), but nothing critical for invoking 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 50%: documentName is documented in-schema with the list_documents lookup guidance, while discardChanges has no schema description. The description compensates for that gap by explaining discardChanges:true as the override that forces the close past the unsaved-changes refusal, adding meaning beyond the bare boolean default.

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 ('Close one Keynote document'), and implicitly separates itself from apple_keynote_save by noting that saving must happen separately. It is clear and unambiguous, but it never names the sibling tools that an agent might confuse it with (save, export), 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?

Gives a real decision rule: if you want to keep changes, call save first rather than closing, and discardChanges:true is the escape hatch for unsaved work. It lacks an explicit 'when not to use' clause or any mention of documents that were never saved to disk from the user's perspective, but the routing to the save path is clear.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, open-world behavior. The description adds genuinely useful context beyond that: the document is unsaved, a window may appear (a UI side effect), and the caller must save explicitly. It does not cover failure modes such as permission prompts.

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 core action, then side effects, then the follow-up requirement. 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 usefully notes that a name is returned and must be reused, which is the key piece of missing structured information. It leaves the theme parameter and any permission behavior unexplained, but covers what an agent needs to call and continue the workflow.

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 (themeName) with 0% schema description coverage, and the description never mentions themes, defaults, or valid values. Since the schema does none of the work here, the description should have compensated 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?

The description states a specific verb and resource ('Create an unsaved Keynote document'), and the qualifier 'unsaved' implicitly separates it from apple_keynote_open, which opens existing files. It is clear but does not explicitly name the sibling it differs from.

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 workflow guidance ('Use the returned name for subsequent operations; save explicitly'), which tells the agent what to do next, but never says when to prefer create over apple_keynote_open or when not to call it. Usage context is implied 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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds concrete behavioral context beyond them: the overwrite gate for existing destinations and the warning that large exports can exceed the automation timeout. It does not say what happens to a partially written file on timeout, which is the one remaining gap.

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

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

Three front-loaded sentences covering output formats, prerequisites, and the failure mode, with no filler. The most actionable constraint (parent directory must exist) comes before the timeout caveat.

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, non-idempotent export tool with no output schema and only 25% schema coverage, the description covers formats, destination preconditions, overwrite behavior, and timeout risk. It stops short of stating where the exported artifact lands or any permission requirements.

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

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

Schema coverage is only 25% (documentName alone is described), so the description must compensate and largely does: it explains the parent-directory precondition for path and the semantics of overwrite (needed when the destination already exists). format is only covered indirectly by naming PDF and Microsoft Office output.

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 (Export) and resource (Keynote) and enumerates the output formats (PDF or supported Microsoft Office format), which matches the schema's pdf/pptx enum. An agent can immediately distinguish this from apple_keynote_save or apple_keynote_close.

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

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

The description gives real prerequisites (parent directory must exist, overwrite:true for existing destinations) but never states when to choose this over siblings like apple_pages_export/apple_numbers_export or over a plain save. Usage is implied by the export purpose rather than routed explicitly.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and idempotency profile is fully covered by structured data. The description adds one genuinely non-obvious lifecycle fact (it will not start a stopped app), but says nothing about pagination, result limits, or behavior when no documents are open.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the behavioral caveat immediately after. Every sentence earns its place.

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

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

For a no-argument list tool with rich annotations but no output schema, the definition covers what it does and one important caveat. It is missing pagination guidance (why offset up to 100000 exists), what fields a listed document returns, and how an empty result should be interpreted — real gaps for an agent assembling a workflow.

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 no information about 'limit' or 'offset'. Their conventional names and explicit ranges/defaults in the schema make them largely self-explanatory, which justifies the baseline-leaning 3 rather than a lower score, but the description fails to state that these control pagination of the returned document list.

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 open Keynote documents') and the 'open' qualifier scopes it meaningfully against siblings like apple_keynote_list_slides or apple_pages_list_documents. It does not explicitly name a sibling to contrast with, so an agent must infer the distinction, but the operation itself is unambiguous.

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 clause 'Does not launch a stopped application' implicitly tells the agent when this tool will not work and that apple_keynote_open may be needed first, which is useful implied guidance. However, no alternative tool is named and there is no explicit when-to-use / when-not-to-use statement.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the returned text is bounded, and which content types are NOT surfaced. It does not discuss permissions or failure modes, so it is not a full 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 short sentences with zero filler; the positive capability statement comes first, followed by the scope exclusion and the bounding note. Every sentence 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 partially compensates by naming the returned fields (indexes, default title/body text, notes, skipped status). But the pagination parameters and how the bounded text is truncated are unaddressed, leaving gaps for a list-type tool with 3 parameters.

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 33%: only documentName is documented ("Exact name returned by list_documents; ambiguous duplicate names are rejected"). The limit and offset parameters, which control pagination, are undocumented in both the schema and the description, so the agent gets no guidance on paging through slides.

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?

"Read slide indexes, default title/body text, presenter notes and skipped status" states a specific verb and resource and enumerates exactly what is returned, which an agent can distinguish from write-side siblings like apple_keynote_add_slide or apple_keynote_update_slide. It doesn't explicitly name or contrast an alternative sibling, so it stops short of 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 negative scope clause ("Does not extract other text boxes, charts, images, or media") tells the agent when this tool is insufficient, which is useful. However, there is no explicit guidance on when to choose this over apple_keynote_open or a generic read tool, so usage is largely implied.

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, openWorldHint=true, and idempotentHint=false, but the description adds genuinely new behavioral context beyond them: the app is launched and a window or import dialogs may appear. That side-effect disclosure is exactly what an agent needs to anticipate UI disruption from this non-idempotent operation.

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, front-loaded with the action and followed by the side-effect warning. No wasted words.

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

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

For a single-parameter open tool with no output schema, the definition covers what the tool does and the notable side effects. Only the missing path-format detail and when-to-use context keep it from being fully 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?

One required parameter with 0% schema description coverage, so the schema alone does not explain 'path'. The description partially compensates by implying it is a path to a local Keynote document, but adds no format, extension, or relative-vs-absolute guidance.

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 ('Open a local Keynote document') with a 'local' scope qualifier that separates it from remote/web document operations. It is easily distinguished from sibling mutations like apple_keynote_create or apple_keynote_close, though it never names a 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?

No guidance on when to open vs. create, save, or export, and no prerequisites or preconditions (e.g., document must exist locally). Usage is only implied by the verb.

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, idempotentHint=false and openWorldHint=true, so safety is covered; the description adds real behavior beyond that by specifying the overwrite gate for existing paths, the parent-directory requirement, and the absence of implicit format conversion. It does not state what happens to the prior file content on overwrite or any 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?

Three tight sentences with the core constraint front-loaded. The trailing 'TextEdit saves RTF; no implicit format conversion' is useful for format routing but is slightly off-topic for a save tool and could read as a sibling note.

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 annotations that already convey the destructive/idempotency profile, the description covers the key decision points an agent needs (overwrite gate, directory prerequisite, format behavior). Return-value behavior after saving is not addressed, 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?

Schema coverage is low (33%), so the description has to carry the load, and it does: it explains that overwrite is mandatory for existing/current paths and that path must point to a .key file under an existing parent. documentName's meaning lives in the schema, so the description's contribution is partial but substantive.

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 Keynote to a .key path') and pins the format, which distinguishes it from apple_keynote_export and the parallel pages/numbers/textedit save tools. An agent can identify the operation without opening the schema.

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

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

Gives clear preconditions: an existing parent directory, and overwrite:true for any existing path including the current document path. It implies but never names the alternative for other formats (export), so routing guidance is strong but not fully explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so mutation risk is covered structurally. The description adds real value beyond that by disclosing that changes "may autosave and sync" and that the target is addressed by a fragile current 1-based index, both of which are behavioral facts the annotations do not convey.

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

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

Two tight sentences: the action and scope are front-loaded, and the sequencing caveat follows. Every clause carries 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 non-idempotent mutation tool with no output schema, the description covers purpose, prerequisite, and side effects (autosave/sync). It omits return behavior, out-of-range index handling, and any permission/authorization context, so it is adequate but not fully 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 only 17% (just documentName), so the description must compensate. It does name the updatable fields (title, body, presenter notes, skipped) and clarifies that slideIndex is 1-based, but it adds no format or constraint detail for the four undocumented parameters, leaving the coverage gap only partially closed.

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 (Update) plus resource (Keynote slide) and enumerates the mutable fields: default title/body, presenter notes, skipped status. This distinguishes it from apple_keynote_add_slide and apple_keynote_list_slides by name semantics, though it does not explicitly name those siblings as alternatives.

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?

"List slides immediately before modifying" gives a concrete workflow prerequisite pointing at apple_keynote_list_slides, which is genuinely useful. However, it gives no when-not-to-use conditions and does not explicitly frame the alternative tools, so usage is only implied.

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=false, openWorldHint=true and destructiveHint=false. The description goes beyond them usefully by disclosing that the draft becomes *visible* in the Mail UI and that persistence is managed by Mail rather than the agent — meaningful context for a non-idempotent create tool. It stops short of saying where the draft lands or what identifier comes back.

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, no filler, with the core action and the most important constraint (it does not send) 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?

There is no output schema and no return-value description, so the agent cannot tell whether a draft identifier or location is returned for later use. The key behavioral caveat about persistence is covered, but for a six-parameter create tool with zero schema documentation and no output schema, the definition is only minimally adequate.

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?

Six parameters (to, cc, bcc, body, account, subject) have 0% schema description coverage, so the description carries the full burden — and it contributes nothing about any of them. Notably, the non-obvious "account" parameter defaults to "iCloud" and is never mentioned, nor is the 100-recipient cap or body/subject 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 and resource ("Create a visible outgoing Mail draft") and immediately clarifies the scope boundary with "Does not send," which separates it from the sibling apple_mail_send without the agent needing to open either schema.

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

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

The "Does not send" clause implies the compose-without-sending use case, so an agent can infer when this is appropriate. But there is no explicit when-to-use guidance, no mention of prerequisites (e.g. which account is written to), and no named alternative such as apple_mail_send for the actual send path.

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=false, and openWorldHint=true, covering the safety profile. The description adds nothing beyond that — no note on behavior when a mailbox name already exists, whether creation requires prompting, or what happens across multiple accounts.

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 no filler, which is appropriate for a simple create operation. It is efficient but perhaps too terse given the undocumented parameters.

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 0% parameter coverage, the description is far too thin: it omits required-vs-optional parameters, defaults, and error behavior (e.g., duplicate names). The annotations cover safety, but functional context is missing.

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

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

Schema description coverage is 0% for two parameters, so the description carries the full burden — yet it does not explain that 'name' is required, that 'account' defaults to 'iCloud', or the 1–1024 character constraints. It only vaguely alludes to an account without connecting it to the parameter.

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

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

States a specific verb (Create) and resource (mailbox) scoped to the Mail account, which distinguishes it from siblings like apple_mail_create_draft. However, it says 'the selected Mail account' while the schema exposes an explicit account parameter defaulting to 'iCloud', so the phrasing is slightly imprecise about how the target account is determined.

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 guidance on when to create a mailbox versus using an existing one, no mention of prerequisites (e.g., checking accounts via apple_mail_list_accounts), and no exclusions or alternative tools named. Usage must be inferred entirely from the name.

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 readOnlyHint=false. The description adds useful context that deletion follows Mail.app's behavior (e.g., moving to Trash), and specifies it applies to local messages. This goes beyond the annotations without 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?

Two concise sentences deliver the essential action, destructive warning, and behavioral nuance. No filler or redundant information.

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

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

For a delete operation with three parameters and no output schema, the description covers the core behavior, destructive nature, and Mail.app-specific handling. It could mention prerequisites (e.g., mailId from apple_mail_list) but the schema already documents that.

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

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

Schema description coverage is 100%, so parameter meanings are fully documented in the schema. The description itself doesn't add parameter-specific detail, but doesn't need to given the schema's completeness.

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

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

The description clearly states the action ('Delete a local Apple Mail message') and the resource (Apple Mail message). It distinguishes from sibling tools like apple_mail_move and apple_mail_update_status by specifying deletion behavior.

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 indicates when to use this tool—for deleting a local Apple Mail message—and notes the destructive nature. It doesn't explicitly name alternatives or when-not conditions, but the purpose is clear and context is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the behavioral detail that the body is included and that the id is local, but does not describe return format or error behavior. This is acceptable given the annotation coverage.

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

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

The description is two sentences with no redundant content. It front-loads the core purpose and then provides the key usage step, making it efficient and well-structured.

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

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

Despite lacking an output schema, the description clearly states the message body is included, which is the most important return detail. It also gives the prerequisite workflow. A minor gap is the lack of detail on other returned message fields, but the description remains sufficient for a simple read tool.

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

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

Schema description coverage is 100% with clear parameter descriptions for mailId, account, and mailbox. The description does not add extra parameter-specific meaning beyond referring to the local id, so it relies on the schema as expected.

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

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

The description explicitly states the action (read), the resource (one local Apple Mail message), and the scope (including its body). It differentiates from sibling tools by being read-only and focusing on a single message, making the purpose unambiguous.

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

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

The description provides clear usage context by instructing to call apple_mail_list first to obtain the local mail id. It implies the appropriate workflow but does not explicitly exclude alternative tools such as send or delete, so it stops short of full 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 read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond these: it lists exact metadata fields returned, clarifies that message bodies are not accessed, and scopes to 'local Apple Mail metadata'. This transparency helps an agent understand side effects (none) and output granularity.

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

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

The description is two sentences, with the primary action and scope front-loaded ('Read-only: list local Apple Mail metadata'). The second sentence adds return fields and an explicit exclusion (no bodies). Every word earns its place with no redundancy.

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

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

With no output schema, the description compensates by listing the returned fields and clarifying body exclusion. It also covers the local scope. Minor gaps exist (e.g., no mention of ordering, pagination, or default mailbox) but the schema provides defaults for account and mailbox, and the simplicity of the tool reduces the need for more detail.

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

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

Schema description coverage is 100%, as each parameter (limit, account, mailbox) has a clear description. The tool description adds no additional parameter-specific detail beyond the schema, so a baseline score of 3 is appropriate; the schema carries the semantic load.

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 uses a specific verb ('list'), names the resource ('local Apple Mail metadata'), and enumerates return fields (message ID, sender, subject, received time, read/flag status). It clearly distinguishes from siblings like apple_mail_get (which reads bodies) and apple_mail_send/delete/move (which mutate mail).

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 establishes clear context: it is a read-only listing operation and explicitly states it does not read message bodies, which implies use apple_mail_get when bodies are needed. It does not explicitly name alternatives or provide when-not-to-use instructions, but the context is sufficiently clear for safe 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying exactly what data is returned (account names, sender addresses, mailbox names), which helps the agent anticipate the output. No destructive behavior is implied, consistent 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 two sentences: the first declares the read-only function, the second provides usage guidance. Every word earns its place, and it front-loads the key information. No redundant content.

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

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

For a zero-parameter, read-only discovery tool with no output schema, the description is complete: it states the function and usage context, and lists the returned data. An agent can confidently invoke this tool before other Mail tools without needing more details.

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

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

The tool has zero parameters and the schema coverage is 100% (empty properties). With no parameters to document, the baseline is 4 per the rubric. The description adds value by implying the tool takes no input and lists all local accounts, which is sufficient.

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 uses a specific verb and resource: 'list local Apple Mail account names, sender addresses, and mailbox names.' It clearly distinguishes itself from sibling tools like apple_mail_list (which likely lists emails) by focusing on account-level metadata and is labeled 'read-only.'

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

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

The description provides explicit timing: 'Use this before other Mail tools when the exact names are unknown.' This gives clear context for when to use the tool, though it does not mention when not to use it or alternative tools. This is strong guidance but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read-only' prefix is redundant. The genuinely additive term is 'metadata', which signals the tool returns attachment descriptors rather than downloading files. Beyond that, no auth, pagination, or return-shape context is given.

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 filler. It is efficient, though its brevity is partly under-specification rather than pure conciseness.

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?

This is a low-complexity list tool and annotations cover the safety profile, so the description need not do much. However, with no output schema and 0% param coverage, an agent still lacks the attachment fields returned and how account/mailbox scope the lookup.

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, but it only implies that a single message is targeted. The 'account' and 'mailbox' parameters with their iCloud/INBOX defaults are left entirely unexplained. This does not compensate for the coverage gap.

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

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

States a specific verb (list) and resource (attachment metadata) scoped to one message. The word 'metadata' distinguishes it from apple_mail_save_attachment, which presumably retrieves actual content. It does not name a sibling explicitly, 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?

No explicit when-to-use guidance, no exclusions, and no named alternative. The phrase 'for one message' implies a mailId is required but does not tell the agent how this relates to apple_mail_get or apple_mail_save_attachment. Only the implicit 'metadata vs content' framing offers any 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?

Annotations already mark this as destructive (destructiveHint=true) and non-read-only. The description adds the constraint that the operation works only within the same account and that it concerns local messages, which is useful. It does not elaborate on side effects or error conditions, but the annotation covers the primary behavioral concern.

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 no extraneous words. The verb appears first, followed by the object and constraints.

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

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

The tool is simple and the description covers the essential action and scope, but it leaves ambiguity about the mailbox parameter's relationship to the source mailbox and does not mention return values. Given the lack of an output schema, a bit more detail about expected behavior would improve completeness.

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 provides descriptions for three of four parameters; targetMailbox is left undocumented. The description does not clarify the role of the source mailbox parameter (mailbox) or the format for targetMailbox, relying mostly on parameter names. It adds the 'same account' context but little else 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?

The description clearly states the action (move), the resource (a local Apple Mail message), and the destination (another mailbox in the same account). This distinguishes it from sibling tools like delete, send, or update.

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 makes it evident when to use: to relocate a message within the same account. However, it does not offer explicit guidance on when not to use it or mention alternatives such as apple_mail_delete or apple_mail_update_status for related operations.

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

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

Annotations already declare a non-readonly, non-destructive, non-idempotent write. The description adds two traits the annotations cannot express: writes are confined to APPLE_MCP_FILE_ROOTS and existing paths are refused (no overwrite). It does not describe permissions, what happens on partial failure, or the response, so it is useful but not rich.

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 action front-loaded and the refusal constraint immediately after. Nothing can be trimmed without losing meaning.

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 five-parameter write operation with 0% schema coverage and no output schema, the description leaves the agent guessing at how mailId/index/account/mailbox combine and what a valid path looks like. It covers the destination root and overwrite policy but not enough to invoke 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% across five parameters, so the description carries the full burden. It only obliquely maps to 'path' (existing paths refused) and implies 'index' selects the attachment, saying nothing about mailId, account, or mailbox or the expected path format.

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+resource ('Save one attachment to a new file') and constrains the destination ('under APPLE_MCP_FILE_ROOTS'), which separates it from apple_mail_list_attachments. It does not explicitly name that sibling as the way to obtain the index, so sibling differentiation is only implicit.

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 rule 'Existing paths are refused' tells the agent when a call will fail, which is genuine usage guidance, but there is no explicit when-to-use vs alternatives, no mention of using list_attachments to find the index, and no prerequisites 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, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds real context: results are bounded and carry metadata only, no message bodies. That tells the agent what it will and will not receive, which the annotations do not.

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 that covers scope, method, and return shape with no filler. 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?

The lack of an output schema is partly offset by the description stating the return shape (bounded metadata, no bodies). However, for a 5-parameter tool with zero schema descriptions, the missing account/mailbox/limit semantics leave an agent under-informed about how 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 0% across 5 parameters. The description only conveys the `field` semantics (subject/sender) and implies `query`; the `account`, `mailbox`, and `limit` parameters, including their defaults and the limit ceiling, are undocumented in both schema and description, so the compensation is partial at best.

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 (search) and resource (mailbox) plus the searchable fields (subject or sender), which maps directly to the `field` enum and separates it from list/get siblings. It stops short of naming an alternative tool explicitly, so it is clear but not sibling-differentiating in the strongest sense.

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 only implied: an agent can infer 'search' rather than 'list' (apple_mail_list) or 'fetch one' (apple_mail_get), but there is no explicit when-to-use, when-not-to-use, or named alternative. Adequate but leaves routing 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=false, idempotentHint=false and openWorldHint=true, so the mutation/irreversibility profile is largely covered. The description adds the useful nuance that dispatch is immediate (i.e. not queued, not undoable), but says nothing about account selection behavior, send failures, or what happens if the account is unavailable. With annotations carrying the safety profile, this is adequate but not rich.

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, front-loaded with the action and followed by the most decision-relevant consequence (immediate send). No filler, though the second sentence partially restates the first.

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

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

A six-parameter mutation tool with 33% schema coverage, no output schema, and no parameter elaboration in the description leaves the agent under-informed about subject/body/cc/bcc and about the account parameter versus the 'selected local account' phrasing. For this complexity level the description should do considerably more.

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 only 33% – only 'to' and 'account' are documented, and the description adds no field-level meaning for subject, body, cc, or bcc. With low coverage the description is expected to compensate, and it does not; it also introduces a mild ambiguity by saying 'the selected local account' while a separate account parameter exists.

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 ('Send an Apple Mail message') and identifies the originating account, which is enough to distinguish it from read-only siblings like apple_mail_list or apple_mail_get. It does not explicitly name the nearest alternative (apple_mail_create_draft), 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 'immediately sends email' implies this is the direct-dispatch path rather than the draft path, giving implied usage guidance. However, it never states when to prefer apple_mail_create_draft over sending, nor any prerequisite conditions, so the guidance is inferred 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?

The description adds useful context by specifying the message is 'local' and by naming the exact status fields that can be modified. However, it does not disclose additional behavioral traits such as side effects, return values, or how partial updates behave. The annotations already provide destructiveHint and idempotentHint, so the description adds limited transparency beyond those.

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

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

The description is a single, front-loaded sentence of 14 words. It contains no filler and directly states the tool's purpose. Every word contributes to understanding the function.

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

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

The tool has 5 parameters, annotations, and no output schema. The description is sufficient to grasp the basic operation, but it lacks usage context, alternative guidance, and any indication of what the tool returns (e.g., updated message or success status). Given the mutation nature and absence of an output schema, the description is adequate but has clear gaps, making it minimally viable.

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 input schema describes 3 of 5 parameters (mailId, account, mailbox) but leaves isRead and isFlagged without descriptions. The tool description partially compensates by mentioning 'read/unread and/or flagged status', but it does not clarify boolean semantics (e.g., true means read) or that omitted fields leave status unchanged. It adds some meaning but not enough to fully cover the gaps.

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

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

The description uses the specific verb 'Modify' and identifies the resource ('local Apple Mail message') along with the affected attributes ('read/unread and/or flagged status'). This clearly differentiates it from sibling tools like apple_mail_list, apple_mail_get, apple_mail_send, apple_mail_move, and apple_mail_delete.

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 for updating a message's status but provides no explicit when-to-use guidance, alternatives, or exclusions. It does not mention prerequisites like listing messages first to obtain a valid mailId, which the schema hints at but the description omits.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the 'Read-only:' prefix is redundant and earns no credit. The one genuinely additive detail is the edge case that serviceType is null when macOS does not expose it, which tells the agent not to treat null as an error.

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, front-loaded with the operation and its returned fields, with no padding. The only waste is the 'Read-only:' prefix that merely repeats the annotation.

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 usefully names the returned fields and flags the nullable serviceType, which is good for a list tool. However it omits pagination semantics for the limit/offset pair and gives no hint about typical account counts or ordering, leaving an agent to guess at paging.

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 description never mentions limit or offset, so neither parameter's meaning (page size, pagination offset) nor the pagination behavior is explained anywhere beyond the raw min/max/default values. With two undocumented params the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('list Messages accounts') and even enumerates the returned fields (IDs, service types, connection states), so an agent immediately knows what it gets. It never names a sibling or contrasts itself with apple_mail_list_accounts / apple_reminders_list_accounts, so it falls just 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?

No when-to-use guidance, no prerequisites, and no mention of the near-identical account-listing tools for Mail and Reminders. An agent has to infer from the tool name alone that this is Messages-specific and should be called before addressing chats or sending messages.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the hard platform limitation that message bodies/history are unavailable, which prevents an agent from mis-planning a follow-up read.

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, front-loaded with the read-only posture and the returned resource, with no filler. The limitation caveat is placed immediately after the purpose so it is read before the agent commits.

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 reasonably well by naming the returned fields, and it covers the key capability limit. It still omits pagination behavior (limit default 20, max 100) and the meaning of accountId, which an agent needs to page or scope 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 0% for all three parameters, so limit, offset, and accountId are undocumented in both places. The description never mentions pagination or what accountId refers to (presumably an id from apple_messages_list_accounts), leaving the schema gap entirely uncompensated.

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 Messages chats) and enumerates what is returned: chat metadata and participant handles. It also distinguishes itself from apple_messages_send and apple_messages_list_accounts by scoping to chats rather than sending or accounts.

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 sentence 'Apple scripting does not expose message history' implicitly tells the agent this is the ceiling of what Messages data is reachable, which is useful routing context. However, it never names a sibling alternative or states when to prefer this over apple_messages_list_accounts, so usage is only implied.

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=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds traits beyond that: 'Immediately' signals no delay/undo, and 'success means submitted, not delivered' clarifies the ambiguous success semantics of a real send. It stops short of stating auth requirements or failure 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?

Two tight sentences with zero filler. The core action and scope are front-loaded, and the second sentence adds the highest-value caveat about delivery semantics.

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 coverage of the safety profile via annotations, the description smartly supplies the one piece an agent most needs: that submission is not delivery, so it cannot confirm receipt. Missing only accountId acquisition and error/failure behavior, which are minor for a 3-param 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 carries the full burden, and it effectively maps all three params: 'text' to the body, 'phone number or email' to recipient, and 'selected connected Messages account' to accountId. It does not explain the accountId format or where to source one, which is the remaining gap.

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

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

States a specific verb (send) and resource (text) with precise scope: 'one explicit phone number or email through a selected connected Messages account.' An agent can distinguish this from apple_mail_send (different channel) and apple_mail_create_draft (drafts, not send) without opening either schema.

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

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

The description implies usage constraints ('one explicit' recipient, 'selected connected' account) but names no alternative and gives no explicit when/when-not guidance. It does not, for example, route the agent to apple_messages_list_accounts to obtain an accountId or contrast itself with a draft-first workflow.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior, so the duplicate warning largely restates idempotentHint=false. The description does add genuine context not in annotations: the copy (not move) semantic, and the rejection of smart/special playlists, which explains the real failure mode. It says nothing about partial-failure behavior or the track-count limit.

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, the core action front-loaded, followed by the constraint and the caution. No filler and nothing misplaced.

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

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

For a two-required-parameter append operation with annotations covering safety and no output schema, the essentials are present: what is copied, which playlist types are valid, and retry risk. Missing only the batch-size limit and partial-success semantics.

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 the parameter meaning. It does add useful semantics — tracks must already exist in the library, and playlistId must reference a regular user playlist — but leaves the 1-20 maxItems cap and ID formats entirely to the schema's structural constraints.

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

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

States a specific verb (copy) and resources (library tracks into a regular user playlist), which cleanly separates it from the sibling create_playlist and from track listing tools. It does not name an explicit alternative, but the resource pairing is precise enough to select on.

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?

"Rejects smart and special playlists" gives an explicit when-not condition, and "Repeating may add duplicates" warns against naive retries. There is no explicit pointer to an alternative tool for the rejected cases, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is known. The description adds only 'May sync through the music library' — a vague side-effect hint with no detail on what syncing means, whether it can create duplicates, or what permissions are needed. This is thin for a create operation.

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 the action front-loaded; nothing is padded. The second sentence is the weakest link because 'may sync' is hedged and imprecise, but overall the text is tight.

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 create tool with no output schema, the description should say something about what is returned (e.g., the new playlist identifier) or whether the playlist is created empty. None of that is present, and the 'may sync' hedge leaves the agent uncertain about the outcome of the call.

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 required parameter 'name', and the description never mentions how the name is used, any length constraint (500 chars), or whether duplicate names are allowed. With one documented-by-name-only param, the description fails to 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?

The description states a specific verb and resource ('Create a new user playlist in Music'), which is enough to separate it from sibling read tools like apple_music_list_playlists and from apple_music_add_tracks_to_playlist. It stops short of explicitly naming or contrasting those siblings, so it lands at 4 rather than 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?

There is no statement of when to use this tool versus alternatives such as apple_music_add_tracks_to_playlist, nor any prerequisites (e.g., Music app running, library access). The only contextual note is 'May sync through the music library,' which is a side-effect remark, not usage guidance.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the leading 'Read-only:' label adds nothing new. The description does not say what happens when Music is stopped or not running, nor whether it requires the app to be open, so beyond the safety profile it is largely silent.

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