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

Goes well beyond the readOnlyHint/destructiveHint annotations: discloses the 50-entry cap, the on-disk source path (~/.local/state/macos-apps-mcp), that no permission is required, that `dry_run` is resolved from the tool's default rather than the caller's override, and that `caller` is client-reported and not an identity check. These are exactly the caveats an agent needs to interpret results correctly.

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

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

Front-loads what the tool returns and the recency ordering before the caveats, and nearly every clause adds information. It is dense and runs long as one paragraph, with the parenthetical asides stacked, which costs a point on structure but not on value.

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 a single optional parameter and an output schema, the description still explains the notable per-entry fields (`dry_run`, `caller`, `session`) an agent could misread, and covers scope, cap, and storage. Nothing needed to call or interpret it 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 0% and the only parameter is an untyped anyOf string, so the description carries the full burden — it does, defining `since` as an optional ISO datetime that drops older entries and recommending `now()` as the grounding source. Without this the agent would have no idea of format or 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 and resource — 'Recent write audit entries (newest first)' — plus the value proposition (before/after pointers sufficient to reverse a change by hand). No sibling tool in the list does anything comparable, so the agent can distinguish it immediately.

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

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

Gives clear usage context: use `since` to drop older entries, and explicitly directs the agent to call `now()` to ground a relative time — a concrete routing instruction to a sibling. It also sets an expectation ceiling ('bounded to the last 50'). It does not state when not to use it, 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=true and destructiveHint=false, so safety is covered, yet the description adds real context: it requires EventKit (Calendar) access, which is an authorization prerequisite an agent needs. It also clarifies the semantic link between `id` and event folders, going beyond the annotations.

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

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

Three short sentences, front-loaded with the core action and return shape, followed by the routing hint and the access prerequisite. Every sentence 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?

The tool is simple (no params, output schema present), and the description covers purpose, return shape, the auth requirement, and the sibling to use for writing. Nothing an agent needs to call it correctly is missing, and return-value detail is appropriately delegated to the output schema.

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

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

With zero parameters, the baseline is 4, and the description does add value by defining what the returned `id` means (the folder events carry) rather than only echoing the schema. There are no input parameters to explain, so deeper parameter semantics do not apply.

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

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

The description opens with a specific verb and resource ('List calendars as pointers'), and immediately clarifies the return shape (id + name). It further distinguishes the resource by explaining that the returned `id` is the `folder` that events carry, so an agent can tell exactly what this tool yields versus sibling event 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?

It gives a concrete usage path: use a name to target writes, and 'See create_event to write,' routing the agent to the relevant sibling. It does not state explicit exclusions or when not to call it, so it falls just short of a full 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?

Goes well beyond the annotations: it discloses that a parent's subtasks remain open and are surfaced under `subtasks` in the result, names the required framework and permission (EventKit + Full Disk Access), and describes the failure mode where an unreadable store refuses the completion with no state change. That is exactly the behavioral context the destructiveHint annotation cannot convey.

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

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

Front-loads the action in the first clause and packs the subtask caveat, prerequisites, and failure semantics into a short block with no filler. The parenthetical explanation of hidden subtasks earns its place, though the sentence structure is slightly dense.

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

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

An output schema exists, yet the description still usefully flags the `subtasks` field, and it covers preconditions and refusal behavior. The only loose end is parameter-level detail for `id`, which the schema does not supply and the description only partially fills.

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 lone `id` parameter is undocumented in the schema. The description partially compensates by stating '`id` from reminders', giving the agent the provenance of the value, but it adds nothing about format or validity constraints on that string.

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 ('Mark a reminder complete') plus the keying parameter ('by id'), so the action is unambiguous. It does not explicitly distinguish itself from update_reminder, which could plausibly also flip completion state, leaving a small amount of sibling inference.

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 context is implied rather than stated: the description explains what happens on completion and what prerequisites are needed, but never says when to choose this over update_reminder or delete_reminder. An agent can infer the intent, but the routing decision is left to it.

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

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

Consistent with readOnlyHint=true and adds context annotations do not carry: matching is substring-based, results are lightweight pointers rather than full records, and Contacts requires Automation access. It stops short of noting match limits, ordering, or case sensitivity when many substring matches occur.

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 match rule, then the return shape, then the permission and sibling routing. No sentence is filler.

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

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

An output schema exists, so return-value explanation is optional and the description's one-line summary is sufficient. Permission requirement and the write alternative are covered; only behavior under many matches (truncation/paging) is left unaddressed for a lookup that can return large result sets.

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% (the single `name` property has no description), so the description must compensate, and it does: it tells the agent the value is matched as a substring rather than exactly. Case sensitivity and whether org names are also matched remain unstated.

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

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

States a specific verb (find), resource (contacts), and match semantics (substring on name), plus the shape of the return (id + name/org pointers). It also names the sibling it is not (create_contact), so an agent can distinguish it without opening any schema.

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

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

"Read-only" plus "See create_contact to write" gives an explicit read-vs-write routing rule between the two contact tools. It does not address whether this is the right choice when the agent only knows an email/phone rather than a name, which is a real limitation given name is the sole parameter.

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 adds useful context beyond annotations by stating the Automation access requirement for Contacts, though it does not mention error behavior, duplicate handling, or rate limits.

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, front-loaded sentences with no wasted words: the action and fields come first, followed by the side-effect and permission 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?

An output schema exists, so return values need not be described. For a simple create operation, the description covers the action, fields, side effect, and permission requirement; only duplicate-handling or failure semantics are missing.

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

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

Schema description coverage is 0%, so the description must compensate. It names all three parameters (given_name, family_name, organization), which is helpful, but it does not clarify that only `given_name` is required or explain field formats or 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?

Uses a specific verb and resource ("Create a contact") and names the fields it accepts (given/family name and organization). It does not explicitly distinguish itself from the sibling `contacts` tool, which likely lists contacts, 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 description implies when to use the tool by saying it creates a contact and requires Automation access for Contacts. However, it gives no explicit guidance on when not to use it or how it relates to alternatives such as `contacts`.

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?

Despite annotations already saying this is non-read-only and non-destructive, the description adds substantial behavioral context: it never sends, opens a compose window, may leave a stray autosaved draft on failure, requires Automation access, and refuses unowned sender addresses.

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

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

The core purpose and the never-sends guarantee are front-loaded, and the critical no-retry/autosave warning is prominently placed. It is long and repeats some autosave timing details, but the extra length is largely justified by the tool's non-obvious asynchronous behavior and cleanup path.

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 description covers the create flow, return locator behavior, permissions, sender ownership rules, asynchronous autosave timing, partial-failure recovery, and the correct alternative tool. With an output schema present, it does not need to fully document return structure, and it still explains the key locator 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 description coverage is 0%, so the description must carry parameter meaning. It clearly explains `to` as a recipient address and richly documents `from_address` ownership, case-insensitive matching, `Name <addr>` support, and default-account fallback; `body` and `subject` are not explicitly described but are conventional and partially implied by the return fields.

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

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

The description states a specific verb and resource: creating a Mail draft that opens for review and never sends by itself. It also distinguishes this from `mail_reply`, which is explicitly named as the threaded alternative for answering messages.

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

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

It gives explicit when-to-use guidance versus `mail_reply`, explains the autosave wait window, and warns not to retry because that creates duplicate drafts. It also names `drafts()` and `delete_draft()` for cleanup after a partial failure.

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, but the description adds substantial behavioral context: it creates an event, requires EventKit/Calendar access, refuses ambiguous calendar names, rejects certain RRULE parts, rejects timestamp offsets for all_day, caps alarms at 5, and explains DST and recurrence-mismatch behavior.

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

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

The description is front-loaded with its core purpose and then packs in necessary edge-case detail. It is dense and somewhat run-on, but nearly every sentence adds useful invocation or validation information.

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

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

Given the tool's complexity, the lack of schema descriptions, and the presence of an output schema, the description is largely complete: it covers creation, auth needs, calendar targeting, recurrence constraints, and alarm semantics. Minor gaps remain around simple fields like notes and location.

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

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

With 0% schema description coverage across 9 parameters, the description carries most of the semantic burden. It thoroughly explains the complex parameters start/end, recurrence, all_day, alarms, and calendar, though it does not explicitly mention notes, location, or title beyond their self-evident meanings.

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

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

The description opens with a specific verb and resource: 'Create an event.' That clearly identifies the operation. It does not explicitly distinguish this tool from siblings such as update_event or events, so it falls short of a 5.

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

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

The description gives operational guidance such as calling now() first for naive datetimes and targeting a calendar via name or Pointer id. However, it does not explicitly state when to use create_event versus update_event, delete_event, or events. Usage is therefore implied more than fully guided.

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

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

Goes well beyond the readOnlyHint=false/destructiveHint=false annotations: it discloses missing-parent auto-creation, the '%' rejection rule, Gmail label behavior and the move_mail refusal (#291), that reads show the new label empty, and the required Automation plus Full Disk Access permissions for 'On My Mac'.

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?

Purpose and the required-account rule are front-loaded, then return shape, token semantics, and caveats. It is dense but nearly every clause carries operational information; the Gmail-label parenthetical is the only passage that verges on over-long.

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 an output schema, the description still names the return fields and, critically, explains that the returned 'folder' token works immediately while mail_overview reports a different spelling later — a non-obvious detail an agent would otherwise get wrong. Permissions and platform caveats are covered.

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

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

Schema coverage is 0% with two required, undescribed string parameters, so the description must carry the load and does: 'name' supports '/' nesting and rejects '%'; 'account' accepts a display name, a UUID, or 'On My Mac'. That is exactly the disambiguation an agent needs to construct a valid call.

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

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

States a specific verb and resource ('Create a Mail mailbox (folder) under one account') and clarifies the folder concept, distinguishing it from message-creation siblings like create_draft. The scope ('under one account') and nesting semantics are 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?

Gives concrete usage conditions: 'account' is REQUIRED and why, the 'folder' token is what to pass to move_mail/mail_search, and it explicitly closes off the wrong expectation with 'There is no delete counterpart... do it in Mail.' No competing creation tool exists to disambiguate against, so no explicit alternative routing 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?

Beyond annotations, the description discloses the write side effect, required Automation access for Notes, Full Disk Access for verify read-back with Automation fallback, and that writes are verified after creation. It also states unknown or ambiguous folder names are refused, which is meaningful behavioral context for a mutation tool.

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

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

The purpose and stable-ID return are front-loaded, followed by parameter and behavior details in a compact paragraph. It is appropriately sized, though dense parentheticals and the issue reference '#49' make it slightly less clean than ideal.

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 creation tool with an output schema, the description covers the essential creation behavior, folder constraints, authentication requirements, verification behavior, and uniqueness/return-ID details. An agent has enough context to invoke it correctly and understand the write side effect.

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 explains that title/body are plaintext with markup escaped and inert, and gives detailed folder semantics including cross-account lookup, default omission, and refusal of unknown/ambiguous names. The title parameter is only lightly explained beyond being plaintext, keeping this from a 5.

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

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

The description states a specific verb and resource: create a note, and immediately explains it returns a stable x-coredata id usable with note_bodies. This clearly differentiates creation from sibling tools like notes, notes_all, update_note, and delete_note without requiring the agent to inspect schemas.

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

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

The description gives clear creation context and details folder selection rules: an existing folder name across accounts or omit for default, with unknown/ambiguous names refused. It does not explicitly compare to update_note or state when not to use it, so it falls short of the explicit when/when-not/alternatives bar for 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?

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds the substantive traits: it creates (side effect), requires EventKit/Reminders access, cannot set tags or subtasks due to API limits, and refuses ambiguous list names while listing candidate ids. This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the action, then parameter rules, then side-effect/constraint notes. Dense but every clause carries information; the recurrence allow/deny list is long but prevents a whole class of failed calls.

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?

Output schema exists so return values need no explanation, and the mutation, permission and targeting behaviors are all covered. The only untouched parameters are title and notes, which are self-evident from the schema.

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 has to carry the load and it does: due/start are ISO datetimes where naive means local time, priority is 0–9, recurrence is an RRULE with an explicit allowed subset (FREQ, INTERVAL, COUNT, UNTIL, BYDAY with ordinals, BYMONTHDAY, BYMONTH, BYYEARDAY, BYSETPOS) and refused parts (BYWEEKNO, BYHOUR, BYMINUTE, BYSECOND, WKST), and list_name accepts a name or Pointer id.

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

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

Opens with a specific verb+resource ('Create a reminder') and immediately scopes what is excluded (tags, subtasks). An agent can distinguish it from update_reminder, complete_reminder and create_reminder_list without opening any schema.

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

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

Gives concrete preconditions for use: call now() first for naive datetimes, target a list via list_name or a Pointer id from reminder_lists, and note that ambiguous names are refused rather than guessed. It does not explicitly state when to use create_reminder vs update_reminder, but the sibling names make that inference safe.

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 readOnlyHint=false annotation, it discloses the mutation side effect explicitly, the exact-name uniqueness rule and why it exists, the return payload (pointer with id and name), and the EventKit permission requirement. That is the full behavioral profile an agent needs.

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

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

Three short sentences, front-loaded with the action, then the constraint, then the return value and permission note. No filler.

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

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

For a single-parameter creation tool with an output schema already present, the description covers creation scope, duplicate behavior, return shape, and auth dependency. Nothing needed to invoke it correctly is missing.

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

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

Only one parameter and the schema coverage is 0%, so the description must carry the load; it conveys that the name must be unique and that the returned id is what later tools expect, but it says nothing about naming format, length, or case sensitivity of the duplicate check.

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 reminder list') plus the scope ('in the default Reminders account'), which cleanly separates it from create_reminder (a reminder, not a list) and from reminder_lists (read-only listing).

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

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

Tells the agent what to do with the result ('use the id as `list_name=`'), which is real chaining guidance, and flags the duplicate-name precondition. It never names an alternative tool or an explicit when-not, so it stops 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 mark the tool as destructive and not read-only, and the description adds important context beyond them: dry_run defaults to true and performs a non-mutating preview, while dry_run=false causes deletion. It also clarifies that deletion is local, unsent-draft-only, and requires Automation access for Mail.

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

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

The description is compact and front-loaded with the core action and scope. The dry_run default is emphasized early, and the final safety note about local deletion and permissions is brief and useful.

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

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

Given the output schema exists, the description does not need to explain return values. It covers the destructive nature, preview behavior, identifier source, and permission requirement, leaving no important operational gap for an agent calling this tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does: it explains that id comes from drafts() and gives precise semantics for dry_run, including its default and the behavioral difference between true and false.

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

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

The description states a specific verb and resource: 'Delete one Mail draft by its message-id'. It clearly distinguishes itself from sibling draft tools like create_draft or update_mail_status by naming the exact operation and identifier source.

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 explains how to select the target ('by its message-id (from drafts())') and how dry_run controls preview versus actual deletion. It does not explicitly name alternative tools or when not to use this one, but the operational context is clear enough for correct invocation.

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, but the description adds genuinely new behavior: dry_run defaults to true and performs no mutation, `span` is silently ignored for non-recurring events, and EventKit/Calendar access is required. Those are exactly the surprises that would otherwise cause an accidental deletion.

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

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

Front-loaded with the action, then clauses ordered by risk (span, then the dry_run default, then permissions). Every sentence adds a fact; nothing is restated from the schema.

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

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

A destructive mutation tool with an output schema that needn't be explained. The description covers the safety default, the recurrence branch, permissions, and id provenance — the full set of things an agent must know before acting.

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 gives no enum for `span`, so the description fully carries the load: it supplies the accepted values 'this-event' and 'future-events' and their meaning, the null/single-event behavior, and the default-true semantics of `dry_run`. All three parameters are covered with meaning beyond type.

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: 'Delete a calendar event by id.' Among siblings like delete_reminder, delete_note, and delete_draft, the 'calendar event' qualifier makes the target 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?

Explicit conditional rules: `span` is required only for recurring targets and ignored for single events, and `dry_run` defaults to true so the agent knows the default call is a preview. It also routes the agent to `events` for obtaining the id. It doesn't distinguish itself from `update_event` for edge cases like moving a single occurrence, 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 mark it destructive, but the description adds critical details beyond them: the delete is recoverable for about 30 days, dry_run defaults to true and performs no mutation, expect_title verifies the target, and Automation access is required. This is strong behavioral disclosure with no contradiction.

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

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

The description is dense but carefully front-loaded, starting with the action and effect, then safety checks, dry_run semantics, permissions, and id source. Every sentence adds operational value, and the formatting makes the default dry_run behavior easy to spot.

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 destructive delete operation, three parameters, existing annotations, and an output schema, the description is complete enough for correct invocation. It covers recovery behavior, preview defaults, target verification, auth requirements, and where ids come from.

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 does: id is sourced from notes/notes_all, dry_run defaults to true with preview semantics, and expect_title verifies the target before deletion. All three parameters are explained with behavior beyond their types.

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: "Delete a note by id" and clarifies the effect by noting it moves to Recently Deleted. This clearly separates it from create_note, update_note, and other delete_* siblings by resource.

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

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

Gives clear operational context: use the id from notes/notes_all, verify with expect_title before deleting, and preview with dry_run because it defaults to true. It does not explicitly name when to avoid this tool versus update_note or other alternatives, so it is not a full 5.

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

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

Beyond the destructiveHint annotation it discloses concrete behavioral traits: the default is a non-mutating preview pointer, parent deletion cascades to subtasks and is refused without an explicit flag, EventKit and Full Disk Access are required because the subtask check reads the Reminders store, and a just-indented subtask may not yet be visible. This is exactly the context an agent needs before an irreversible 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?

The critical dry_run default is front-loaded in caps, and each subsequent sentence adds a distinct operational fact. It is dense but nearly every clause earns its place, with only the clipped 'id' from reminders' phrasing reading as slightly terse.

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 three-parameter mutation with an output schema, the description covers safety default, refusal conditions, cascade semantics, permission requirements, and a consistency caveat. Return values need not be explained since an output schema exists.

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%, but the description documents all three parameters: id's source ('from reminders'), dry_run's default and effect, and with_subtasks' role in bypassing the parent refusal. Nothing about parameter meaning is left to inference.

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

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

The opening sentence gives a specific verb ('Delete') and resource ('a reminder') scoped by identifier, which cleanly separates it from siblings such as update_reminder and complete_reminder. The following sentences define exactly what deletion means in the parent/subtask case.

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 states clearly when the tool previews versus deletes (dry_run defaults true, pass false to actually delete) and when a parent deletion is permitted (with_subtasks=true). It never explicitly contrasts with alternatives like complete_reminder or update_reminder, but the operational guidance for the tool itself is unambiguous.

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

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

Annotations only declare readOnly/destructive, but the description adds the crucial side-effect disclosure that `request=True` triggers EventKit consent dialogs and per-app Automation probes — behavior an agent could not infer from the schema. It does not contradict readOnlyHint (no data is mutated), but it does flag a hidden user-visible effect, which is exactly the kind of context annotations cannot carry.

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

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

Three short sentences, front-loaded with the purpose and then the safety-relevant default. Every sentence adds information the agent needs; nothing is redundant with the schema or annotations.

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

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

With an output schema present, return values need no explanation, and the description covers the one parameter and the prompt side effect. Minor gap: "per-surface" is never defined, so the agent doesn't know which surfaces/domains are diagnosed.

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

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

Schema description coverage is 0%, so the description must carry the only parameter — and it does, explaining what `request=True` actually does (permission prompts, EventKit consent, Automation probes) and the recommended cadence ("once to grant"). Without this text the boolean would be opaque.

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

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

The description names a specific verb and resource combination ("Diagnose per-surface macOS permissions + health") and adds the value proposition of "exact remediation." It is clearly distinct from the sibling action tools (mail, notes, reminders) and from the lighter `ping`/`usage` utilities, though it never explicitly names those siblings.

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

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

It gives explicit guidance for the parameter's two modes: default is "Read-only and prompt-free," and `request=True` should be used "once to grant" permissions. What is not covered is when to reach for this tool rather than a sibling diagnostic like `ping`, `usage`, or `audit`.

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

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

Annotations already declare read-only and non-destructive, but the description adds substantial context beyond them: the 25-record truncation cap and its `truncated` flag, newest-first ordering, the shape of each record, that the id is an RFC822 message-id, the ~10-15s autosave visibility lag with an explicit 'do not retry' instruction, and the Automation access requirement. That is exactly the operational detail 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?

Front-loads the action and the return shape, then layers in the identifier contract and the caveat. Dense and mostly earned, though the explanation of why field comparison beats substring-matching on the summary is slightly long-winded for the value it adds.

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

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

An output schema exists, yet the description still surfaces the two things an agent must know before calling: the truncation cap and the autosave delay. Combined with the id→delete_draft/send_mail handoff and the permissions note, nothing needed for correct invocation is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly spends no words on parameter semantics and instead invests in return-value and identifier meaning.

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

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

Opens with a specific verb and resource plus ordering semantics ("List Mail drafts, newest mailbox order"), which immediately distinguishes it from mailbox-wide siblings like mail, mail_search, and mail_overview. It also clarifies the record type (citable pointer with folder = "drafts") so there's no ambiguity about scope.

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

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

Gives concrete downstream routing: pass the id to delete_draft or send_mail(draft_id=…) for a human-approved draft, and explicitly says to wait rather than retry a create for an un-autosaved compose window. It stops short of naming a sibling to use instead when the agent actually wants to search drafts by content, which is the one remaining gap.

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 it read-only, yet the description still adds real context: EventKit (Calendar) permission is required, results are pointers rather than full records, and each result carries its own occurrence start so a series' extra first occurrence is invisible to reads. That last caveat about a known limitation is exactly the kind of behavior an agent cannot infer 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, each earning its place, front-loaded with the core action before the chaining and caveat details. The parenthetical about occurrence starts is dense but necessary and kept short.

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

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

With an output schema present, return values needn't be enumerated, and the description correctly focuses on the pointer shape and `folder` semantics that matter for chaining. Permission requirements and the read-versus-create asymmetry caveat round it out; only explicit non-use guidance is missing.

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

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

Schema description coverage is 0%, so the description carries the burden and does: `when` accepts today | week | YYYY-MM-DD, which is effectively an enum the schema lacks. The `folder` output field is also explained for chaining purposes, though the default value is left to 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?

"List calendar events as pointers" gives a clear verb and resource, and the surrounding sibling set (create_event, update_event, delete_event) makes the read-only listing role obvious. "As pointers" is slightly cryptic on its own but is unpacked in the following sentence about the `folder` field.

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 wires the tool into the workflow explicitly: pass each result's `folder` to `free_busy(calendars=…)` or as `calendar=`, which tells the agent when this tool is the prerequisite for others. It does not state exclusions (e.g., use `free_busy` instead when you only need availability), so it stops short of a full when/when-not pair.

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

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

Goes well beyond the annotations: discloses that it reads at rest and never launches Mail or needs Automation, requires Full Disk Access, refuses paths outside the allowed root, derives filenames on a never-overwrite basis, and aborts the whole batch before writing if a name collides. It also explains partial-fidelity attachment loss and per-id 'absent' handling — exactly the behavioral context an agent needs before a write.

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

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

Front-loaded with the core action, then constraints, then return shape — a logical order with almost no filler. It is dense and multi-paragraph for a 2-param tool, so slightly heavier than strictly necessary, but each sentence adds operational value.

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

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

Covers the failure semantics (batch refusal, per-id absent, partial fidelity) that matter for a batch write, and an output schema already exists so return values are doubly covered. Minor gap: it does not state what happens on a mid-batch I/O error beyond the 'files already written' note, or whether there is rate limiting on Full Disk Access reads.

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 description fully compensates: `ids` is documented as comma-separated RFC822 message-ids (from a mail read) capped at 25, and `dest_dir` as being constrained to the allowed root, defaulting to ~/Downloads, relocatable via MACOS_APPS_FILE_ROOT, and auto-created. This is strictly more information than the bare string-typed schema carries.

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 — 'Write messages out as importable .eml files' — and immediately distinguishes itself from the sibling mail_body ('mail_body already covers "give me the text"'). An agent can tell exactly what this produces 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?

Explicitly routes the text-only case to mail_body and frames this as the archival/export path, plus notes the max-25 batch limit and the allowed-root requirement. It stops short of naming other export siblings (export_photo, save_mail_attachment) as alternatives, so selection against the full sibling set is slightly under-specified.

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 readOnly=false/destructive=false; the description adds substantial context beyond that: Full Disk Access requirement, no Photos launch or Automation needed, no overwrites, 250 MiB cap, path-root enforcement, and status values for refusal cases. This is exactly the extra behavioral detail the annotations cannot convey.

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

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

Front-loaded with the action, then parameters/constraints, then return shape — a logical progression with no filler sentences. It is on the long side, but each constraint (iCloud, videos, Live Photos, hidden) maps to a distinct failure mode an agent must anticipate.

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 an output schema existing, the description also states the return shape ({id, status, path, bytes, edited, dest_dir}) plus the non-written statuses, and covers permissions, filesystem limits, and library-state edge cases. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: `id` is a Photos photo id with the legacy `<UUID>/L0/001` form accepted, and `dest_dir` must be inside an allowed root (~/Downloads default, MACOS_APPS_FILE_ROOT override), is auto-created, and is REFUSED if outside. Every parameter gets meaning, defaults, and failure 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?

Opens with a specific verb+resource: 'Write one photo out as a still image file'. It also clarifies the edited-vs-original semantic, which no sibling (photos, photo_info) handles, so an agent can distinguish export from listing/inspection without opening schemas.

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

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

Rich conditional routing: videos refused, Live Photos export still only, hidden/Recently Deleted refused, iCloud-only photos return 'absent'. It does not explicitly name a sibling alternative (e.g. use photo_info first to verify), but the refusal conditions effectively define when this tool won't work.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that: intervals are merged, no event details are returned, and it 'needs EventKit' (a platform/permission precondition the schema does not 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?

Front-loaded with the core purpose, then parameter notes, then return shape and precondition — every clause earns its place. Slightly dense/compressed prose costs it the top mark.

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

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

Covers inputs, output shape ('{busy: [...], free: [...]} of {start, end}'), what is deliberately omitted ('no event details'), and the EventKit dependency. Nothing an agent needs to invoke it correctly is missing despite the output schema existing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: `start`/`end` are ISO-8601 naive local datetimes with a concrete example, and `calendars` is defined as optional Pointer ids sourced from the `calendars` tool, defaulting to all. That is meaning the schema alone cannot convey.

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 ('Availability in a window') and immediately names the two outputs it computes ('merged busy intervals + free gaps'), which distinguishes it from sibling `events` (raw event listing). An agent can tell exactly what it produces without opening the schema.

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

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

It explains the scoping option ('calendars optional Pointer ids... else all') and the read-only nature, which implies 'use this when you want free/busy rather than event details.' But it never explicitly says when to prefer this over `events` or names the alternative.

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 it read-only and non-destructive, and the description still adds meaningfully: it requires Automation access for Mail, bodies are never fetched, results are capped at 25 with a `truncated` flag signaling more may exist. It also discloses the inbox-only scan scope, which is a behavioral limit not visible in any structured field.

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

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

Front-loaded with the action, then a compact "Pointers:" list mapping field names to meanings, then scope/limit and a sibling recommendation. Every clause carries information, though the pointer enumeration makes it denser than strictly necessary for a one-parameter tool.

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

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

For a one-parameter search tool it covers everything an agent needs: matching semantics, inbox-only scope, output field meanings, the truncation cap, the auth prerequisite, and the routing decision to `mail_search`. An output schema exists, yet the description still clarifies the one field (`truncated`) whose meaning matters operationally.

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 `query` parameter has 0% schema description coverage, so the description must carry it — and it does, explaining that matching is a subject OR sender substring. It does not specify case sensitivity, whitespace handling, or whether multiple terms are ANDed, which keeps it below a 5.

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

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

States a specific verb and resource ("Search the Mail inbox") and narrows the matching semantics to subject OR sender substring. It also explicitly separates itself from `mail_search`, which reaches every mailbox, so an agent can pick between the two without opening schemas.

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

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

Gives an explicit preference rule: "Prefer `mail_search`, which reaches every mailbox and reports the account," which is precisely the condition that selects the sibling over this tool. It also tells the caller to forward the returned `folder` value straight to `mail_body`, closing the follow-up loop.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond them: bounded mailbox scans, truncation, empty-query listing behavior, Full Disk Access resolution for message_id, and the unsaved-draft edge case where id is empty and deeplink is absent.

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 front-loaded and dense with useful distinctions, but it is long and parenthetical-heavy. It also explains the return shape despite an output schema existing, which is somewhat redundant, though the return semantics around actionable rows and unsaved drafts still add value.

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

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

Given the output schema and read-only annotations, the description is complete enough for correct invocation: it covers all parameters, alternatives, required input combinations, scan limits, and key edge cases. Nothing essential for selecting or calling the tool appears missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for all three parameters. It explains mailbox as an opaque imap token or canonical system mailbox, query as an optional subject substring with special empty-query behavior, and message_id as a single-message selector that ignores query and can resolve without mailbox.

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

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

The opening sentence uses a specific verb and resource: 'List attachments' on messages in a Mail mailbox or on one message. It distinguishes mailbox scanning from single-message lookup, and references related tools like mail_search, mail/get_pointers, and drafts to disambiguate usage.

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 explicit routing guidance: use mailbox for a folder scan or message_id for one known message, prefer message_id because scans stop at 25 records, query is ignored when message_id resolves on its own, and either mailbox or message_id is required. It also states a concrete use case: confirming an attachment landed on a draft before saving.

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

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

Goes well beyond the readOnlyHint annotation: threading via In-Reply-To/References, group sends cleared on any reply, a hard 25-result cap surfaced as `truncated`, and the operational prerequisites (Full Disk Access fast path vs. SLOW AppleScript fallback). This is exactly the context an agent needs before committing.

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

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

Front-loaded with the core definition, then scope, then operational caveats — every sentence adds information. It is dense with parentheticals and backticked identifiers, which costs a little readability.

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

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

Covers filter semantics, ordering, scope, result cap, output-flag meaning, downstream tool compatibility, and access requirements. Even without relying on the output schema, an agent knows what it will get and what it costs.

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 load — it supplies the meaning of `days` (sent more than N days ago) plus the 1–365 range and default, none of which the schema encodes. Only a small gap remains (no note on invalid values).

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 resource (messages you sent) with a precise filter (no reply, older than `days`, oldest-first) and even the reason label `awaiting-reply`. An agent can distinguish it from mail_needs_response and mail_search without opening any schema.

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

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

It clarifies the account-spanning scope versus mail_needs_response and says pointers are ready for mail_body/reply_all, which orients the agent in a workflow. It never states an explicit 'use this instead of X when...' exclusion, so it stops short of full routing guidance.

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

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

Goes well beyond readOnlyHint/destructiveHint=false: discloses that unreadable ids land in `missing` rather than returning empty bodies, that bodies are truncated with an explicit marker, that oversized batches REFUSE with output_overflow, that it reads files at rest without launching Mail, and that Full Disk Access is required. That is a rich behavioral profile; a 5 would need detail on the actual per-body budget size.

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

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

Front-loads the verb, resource and batch limit, then layers failure modes and storage semantics in short, scannable clauses. Dense but nearly every sentence earns its place; the parenthetical about 'the sender wrote nothing' and the FTS-index comparison slightly pad an already-long block.

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

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

Covers what an agent needs to call correctly and recover from failure: batch cap, truncation, overflow refusal with a remedy ('ask for fewer ids'), missing-id semantics, permission prerequisite, and freshness versus the index. An output schema exists, so the extra return-shape prose is surplus but harmless.

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 single `ids` array is undocumented in the schema, so the description carries the burden — it supplies the meaningful constraint (up to 20 ids) and defines what happens to invalid/unreadable ids. It does not say what id format is expected (RFC message-id vs Mail's internal id), which leaves one real 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 ('Plaintext bodies for up to 20 message ids in ONE call') with an explicit scope limit and a use-case gloss ('the bulk read behind "catch me up on this thread"'). The batch framing plus the mail_body sibling name differentiates it from the single-message reader 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?

Prescribes the exact call path (mail_search -> mail_thread -> mail_bodies) and notes the shorter path via mail_thread(snippets=True), plus the opt-in/bounded framing. It also contrasts itself against the mail_search(body=) FTS index, telling the agent which source is fresher.

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

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

Adds substantial behavior beyond the readOnly/destructive annotations: bounded and truncation-marked output, id resolution independent of mailbox, Automation-only path with mailbox, and index/Full Disk Access fallback without it. These details give the agent a clear behavioral model without contradicting 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?

Front-loads the purpose and then parameter rules, with no obvious fluff. It is dense and longer than typical, but the length is largely justified by the zero schema coverage; minor tightening is possible.

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

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

With an output schema present, the description appropriately focuses on input semantics and behavior. It covers id sourcing, mailbox token handling, error behavior, and access paths, leaving little needed before 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%, so the description carries the full burden and does so: id is a message-id that resolves on its own, and mailbox is an optional disambiguator that must be passed verbatim as an opaque imap:// token or canonical name. It also explains the consequence of including or omitting mailbox.

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

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

Opens with a specific verb and resource ('Full plaintext body of one message by id') and adds scope ('bounded + truncation-marked'). It does not explicitly differentiate from sibling body tools such as mail_bodies or message_body, so the one-message-vs-many distinction is left 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?

Explains where the id comes from (mail/mail_search, stored citations) and the two modes for the optional mailbox parameter, including that an id absent from the mailbox raises. It lacks an explicit comparison to sibling tools, so it stops short of full when-to-use 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?

Adds substantial context beyond the readOnly/destructive annotations: index freshness lag, no Mail launch, Full Disk Access requirement, cross-account counting, output shape, and the inability to delete. These details materially affect correct invocation and user guidance.

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 opening sentence front-loads the purpose and read-only nature, and most follow-up detail is useful. It is somewhat long and repeats read-only information already in annotations, but the density is justified for a report tool with cleanup guidance.

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?

Complete for this tool: it covers purpose, output fields, read-only behavior, freshness, permissions, cross-account semantics, and the correct cleanup path. The output schema exists, but the prose still gives enough context for an agent to use and explain 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?

The single optional `limit` parameter has 0% schema description coverage and is never mentioned in the description. It is unclear whether `limit` caps mailboxes, worst-message entries, or rows, so the description does not compensate for the missing schema documentation.

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

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

States a specific resource and report action: it shows where Mail physically stores redundant duplicate copies. It also explicitly distinguishes this report from read tools like mail_search/mail_thread/mail_overview, which already hide duplicates.

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

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

Explains exactly when to use it: when the agent needs to see remaining physical duplicates that normal read tools hide. It also states what not to do by clarifying this tool cannot delete and directing cleanup to the external dedupe-mail command.

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 contradicts the readOnlyHint=true annotation: it says the tool builds/refreshes an index and explicitly writes the server's own FTS sidecar. Even though it clarifies that Mail's data is not modified and that Full Disk Access is required, the tool-level readOnly annotation is inconsistent with the disclosed sidecar write.

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 front-loaded and information-dense, but it is long and includes some repetition around resumability and safe re-runs. Most sentences add real value, though the prose could be tightened 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?

It covers permissions (Full Disk Access, not Automation), write scope (Mail untouched, FTS sidecar written), resumability and size caps, partial .emlx handling, residual unsearchable tail, and return-shape context. This is highly complete for a complex indexing 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%, but the description fully explains the only parameter: rebuild=True re-indexes from scratch, while normal runs resume where they left off. That is exactly the semantic detail an agent needs beyond the bare boolean schema.

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

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

The description states a specific verb and resource: build/refresh the opt-in FTS body index used by mail_search(body=…). It clearly scopes what is indexed and how it relates to a sibling consumer tool, leaving little ambiguity about the tool's purpose.

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 explains resumability, safe re-runs, and when rebuild=True applies, and it routes the question 'is body search usable?' to mail_search(body=…). It does not explicitly compare against other index-related siblings such as mail_index_ids, but the operational guidance is otherwise 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?

The description says it builds/refreshes a sidecar and that rebuild=True starts from scratch, which implies persistent writes to server-side storage. This conflicts with the annotation readOnlyHint=true, even though the description limits read-only behavior to Mail's data specifically.

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 purpose is front-loaded and the information is dense and useful, including auth and performance context. It is somewhat overlong and redundantly lists return fields despite an output schema, but most sentences still carry meaningful 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?

Covers the key operational context: macOS applicability, Full Disk Access versus Automation, safety for Mail, re-run semantics, performance expectations, and coverage interpretation. Given the output schema, the remaining return-field explanation is extra rather than 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?

Although the schema provides 0% parameter description coverage, the description fully explains the single rebuild boolean: default re-runs harvest only missing data, while rebuild=True starts from scratch. This adds the exact semantics an agent needs.

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: build/refresh a Message-ID sidecar for the sqlite mail plane on macOS 15 and earlier. It also explains the OS boundary where it is unnecessary, so an agent can distinguish it from related mail-index 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?

Explicitly says when the tool is needed (macOS 15 and earlier without native Message-ID storage) and when it is unnecessary (macOS 26+). It also clarifies re-run behavior and the effect of rebuild=True, giving clear invocation 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?

Far exceeds what annotations cover: discloses the heuristic basis (headers + message properties, no body read), the 25-result cap and the meaning of truncated, and the Automation permission requirement. These are exactly the behaviors an agent needs before calling, none of them stated by readOnlyHint/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?

Front-loaded with purpose and reasons, then constraints, then output shape and permissions — well ordered with no filler. It is dense and slightly crammed (reason codes, folder contract, cap, auth in one block), but every sentence carries operational value.

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

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

Although an output schema exists, the description still clarifies the important return semantics (truncated = 25 cap reached) and the reason taxonomy. Combined with permission requirements, the fixed folder contract, and the zero-param rationale, an agent has everything needed to call and interpret it.

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

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

With zero parameters the baseline is 4, but the description explains the implicit design decisions that a schema cannot: why there is no account argument (unified inbox, owner genuinely unknown) and the fixed folder='inbox' that makes returned ids directly reusable. That is real added meaning, not schema repetition.

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 ('Inbox messages that likely need your response') plus the ranking signal (reason codes flagged/unread-direct/unanswered-direct), and explicitly names a sibling (mail_search) it is not. An agent can distinguish this from mail_awaiting_reply or mail_overview 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 an explicit routing rule: use mail_search when the owning account matters, since this tool spans the unified inbox so account is unknown. It also states the ids are directly usable in mail_body/mail_reply, removing a lookup step. It does not, however, contrast with the similarly named mail_awaiting_reply sibling, leaving one ambiguous boundary.

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 readOnly/non-destructive annotations, it discloses that the tool contacts and may launch Mail, that counts remain correct without Mail, the fallback UUID-as-name behavior, the '(account not in Mail)' sentinel, the always-shown 'On My Mac' store, live vs. stale counting, double-filing dedupe, and both required permissions (Full Disk Access, Automation). That is unusually rich behavioral context for a read-only tool.

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

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

Purpose and the triage use case are front-loaded, and nearly every sentence carries operational information the agent needs (uuid mapping, folder round-trip, permission needs). It is dense and includes a small amount of overlap with the annotations ('Fast and read-only'), which keeps it just below a 5.

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

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

For a zero-param read-only tool with an output schema, the description is complete: it covers what is returned, edge cases (unlisted account, On My Mac, unreachable Mail), counting correctness, and permission prerequisites. Nothing an agent needs to call it safely and interpret results is missing.

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

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

The tool takes zero parameters, so there is no parameter meaning to add and baseline is 4. The description instead specifies the row shape and field semantics ({account, account_id, mailbox, folder, total, unread}), which is value-add even if it belongs more to output semantics than parameters.

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

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

The opening sentence names the verb, the resource, the scope (every mailbox), and the differentiator ('unread-first'), and frames it as the triage entry point. An agent can tell immediately this is a survey/count tool rather than a search or body-fetch 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 clearly implied with 'triage entry point ("what's unread where?")' and the concrete follow-on workflow into `mail_search`/`mail_body` via the round-tripping `folder` url. It stops short of explicitly distinguishing itself from siblings like `mail_stats` or naming when not to use it, so it is clear context without exclusions.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds far more: threading headers are set natively, an async ~10-15 second autosave window applies, and retrying produces duplicate drafts. These are exactly the non-obvious traits an agent cannot infer from structured fields.

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

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

Front-loaded and well-sectioned: purpose first, then parameter guidance, then the autosave caveat. It is dense and the autosave paragraph runs long with emphasis formatting, but nearly every sentence carries operationally necessary information, so little 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?

An output schema exists, so return values need not be spelled out, yet the description still notes it returns a locator dict and how drafts() resolves it. Combined with the send-path exclusion and the retry hazard, an agent has everything needed to call and chain this 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?

With 0% schema description coverage, the description carries the burden and mostly does: message_id is defined as the RFC822 id from a mail read, and mailbox is explained in detail (REQUIRED, the `folder` value from the same search result, verbatim opaque imap:// token, canonical names also accepted), plus include_quote appends the quoted original. reply_body is left to the parameter name, a minor but real 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 opens with a specific verb and resource ('Reply to a message, opening a threaded draft for review') and immediately adds the key differentiator 'NEVER sends'. An agent can distinguish this from create_draft (new draft) or a send operation without inspecting any schema.

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

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

It gives explicit when-not rules: do NOT retry if the draft does not appear, and the resulting draft cannot be delivered via send_mail(draft_id=…) because that call refuses and redirects to reply_all(dry_run=False). It also names the correct follow-up (save to Drafts, then drafts()) and the required waiting window.

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 extensive behavior beyond the readOnlyHint and destructiveHint annotations: Full Disk Access and Automation requirements, AppleScript inbox fallback on missing access or schema drift, mailbox typos raising errors, body-index coverage limits, and account-name resolution potentially launching Mail. It also explains result fields such as truncated, plane, and coverage so the agent can interpret partial or degraded outcomes.

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

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

Despite being long, the length is justified by the tool's 12 parameters and complex fallback/permission behavior. The purpose and core filters are front-loaded, and the remaining sentences each add operational meaning rather than repeating schema or annotations.

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 annotations, an output schema, and 12 undocumented parameters, this description covers the missing context an agent needs to call the tool correctly. It explains permissions, fallback behavior, best-effort body search, error conditions, truncation, and how to interpret the returned coverage and plane fields.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so thoroughly for all 12 parameters. It defines substring semantics for subject/from_/to, mailbox-name matching rules, epoch-second date filters, unread/flagged flags, body-index best-effort behavior, has_attachments document semantics, account display-name versus UUID behavior, and limit via the 25-max truncation note.

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

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

The description opens with a specific verb and resource: indexed search across ALL mailboxes via Mail's Envelope Index, fast and read-only. It clearly distinguishes this tool from siblings by naming mail_overview and mail_index_bodies where their roles matter, and by explaining scope such as all mailboxes and optional ANDed filters.

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

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

It explicitly states conditions: at least one filter is required, body search requires mail_index_bodies first and is best-effort, mailbox names must match mail_overview output, and account-name lookups launch Mail while UUID lookups stay pure sqlite. It also tells the agent not to treat a truncated result as exhaustive, which is a usage constraint beyond basic invocation.

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/destructiveHint, and the description adds genuinely new behavioral facts: it reads the Envelope Index only and never launches Mail, it counts DISTINCT messages (raw rows overcount up to 3.6x), and output is deliberately token-bounded with top-N instead of per-day series. The trailing 'Read-only.' merely repeats the annotation, but the surrounding disclosures are substantive.

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

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

Front-loaded with the one-line purpose, then progressively adds constraints and output shape; the deduplication warning and the account-UUID caveat each earn their space. The enumerated return-key list is somewhat verbose given an output schema exists, though it doubles as guidance on what is and isn't included (top-N, no per-day series).

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 read-only aggregate with an output schema and clear annotations, nothing material is missing: prerequisite access, counting semantics, parameter format, output shape and the follow-up call to resolve account UUIDs are all covered. An agent could call this correctly without inspecting anything else.

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 burden and largely does: `days` is defined as the lookback window, and `account` is explicitly described as a raw account UUID — the same UUID carried by mail Pointer and mail_overview rows — not a display name. That is exactly the disambiguation an agent needs; only the default values/edge behavior are left to the schema.

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

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

States a specific resource and metric set ('Mail volume, read ratio and top senders over the last `days`') and frames the scope as an aggregate over the whole store, which cleanly separates it from per-message siblings like mail_search and mail_thread. The parenthetical '(Full Disk Access)' and the 'never launches Mail' clause further pin down what kind of tool this is.

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 clear trigger context (summary statistics over a day window rather than message listing) and an explicit follow-up path: 'map the uuid to a name with one `mail_overview` call.' It also states the Full Disk Access prerequisite. It stops short of naming an explicit alternative tool and when-not-to-use condition, so it is strong but not complete 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 only cover safety (readOnly, non-destructive); the description adds substantial context beyond them: dedupe behavior, truncation direction (oldest dropped) and its `truncated` signal, empty results for unknown ids, snippet read off disk with no Mail launch, and the Full Disk Access prerequisite. It even specifies that an unreadable body yields an absent `snippet` key rather than an empty one.

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

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

Front-loaded with the core purpose and structured around the snippets decision, so it reads well. Minor redundancy — 'no Mail launch' is asserted twice ('no Mail launch and no extra calls' and 'Fast, read-only, no Mail launch') — keeps it just short of a 5.

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

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

For a 3-parameter read tool with an output schema, the description covers everything an agent needs: return shape, truncation direction, unknown-id behavior, snippet opt-in cost, and the FDA permission requirement. Nothing material is left to inference.

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

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

Schema coverage is 0%, so the description must carry the load — and it does: `id` identifies the conversation, `limit` controls truncation with the oldest messages dropped when exceeded, and `snippets=True` toggles a ~200-char body preview with explicit absent-key semantics. All three parameters gain meaning beyond their bare types.

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: every message in the conversation containing `id`, oldest-first, including messages the user sent, with dedupe across mailboxes. An agent can immediately distinguish this from mail_bodies, mail_body, or mail_search without opening a schema.

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

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

Explicitly routes the agent: use `snippets=True` to see who spoke last, then `mail_bodies(ids)` for the few worth hydrating; leave snippets off for a long thread you only need to enumerate. Both the when and the when-not are stated alongside the named alternative.

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

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

Annotations declare destructiveHint=true, and the description adds substantial context beyond that: the undo is itself backed up, logged, verified, and yields its own receipt (an undo can be undone); it discloses permissions required (Automation for Mail, Full Disk Access) and multiple failure modes with recovery guidance. This is unusually rich disclosure for a mutation tool.

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

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

Front-loaded with the verb and identifier, then proceeds in escalating edge cases. The batch Message-ID caveat is dense but material; a couple of sentences (e.g., the 'unknown' timeout replay) could be tightened, keeping this below a perfect score.

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

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

An output schema exists so return shape needn't be described, yet the description still notes that the call returns its own receipt. Combined with the dry-run workflow, permission requirements, and named failure modes, nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description carries the full burden, and it does: 'receipt' is defined via its producers (move_mail result, audit), and 'dry_run' has its default, purpose (preview which messages would be restored), and override instruction spelled out. No ambiguity remains for either 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?

Opens with a specific verb+resource ('Undo one recoverable Mail operation') and names the identifier source ('receipt' from move_mail's result or from audit). An agent can immediately tell this apart from move_mail, trash_mail, and audit.

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?

States exactly where to obtain the receipt, warns that dry_run defaults to true and must be set to False to act, and enumerates the cases where undo cannot be replayed (no destination mailbox, Gmail label folder, unified mailbox name). The routing to move_mail as the producer of the receipt is 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?

Beyond the read-only annotations, the description discloses that it reads chat.db, decodes attributedBody typedstream when message.text is NULL, returns an empty string for a message with no text, and requires Full Disk Access. These are meaningful behavioral and operational details an agent would not get from annotations alone.

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 purpose is front-loaded in the first clause, followed by the decoding edge case, auth requirement, and parameter source. Every sentence adds useful information with no repetition or filler.

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

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

Given a single required parameter and an output schema, the description covers the key gaps: parameter provenance, NULL-text decoding behavior, empty-string return, and Full Disk Access. Nothing essential for correctly calling and interpreting this tool is missing.

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

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

Schema description coverage is 0%, so the description must carry the parameter explanation. It does so by defining `id` as a message guid obtained from messages_search or messages_with, which is sufficient for correct invocation, though it omits format details such as guid shape.

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: retrieve the full text of one Message by id from chat.db. It clearly distinguishes this from messages_search and messages_with by identifying them as the source of the guid rather than the tools that return the body.

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 tells the agent where the `id` comes from, naming messages_search and messages_with as the upstream tools, which implies this is a follow-up lookup. It does not explicitly state when not to use it or name alternatives for retrieving message text, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description needn't restate safety; it instead discloses two non-obvious traits: the response carries no message content, and the tool requires Automation permission to be granted in Messages. It does not mention limits, pagination, or ordering of the returned conversations.

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 clauses, each carrying distinct information: what it returns, what it does not do, and what permission it needs. Nothing is repeated from the annotations or schema, and the scope statement leads.

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 listing tool with an output schema, the description covers scope, exclusions, and the auth prerequisite. The only remaining gap is volume/ordering behavior (how many conversations come back), which matters for an agent deciding whether to page or narrow 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly describes the output fields ('id + name'), which is a bonus rather than a substitute for 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?

States a specific verb and resource ('List Messages conversations') and bounds the payload ('id + name'), which is enough to separate it from content-fetching siblings like message_body. It does not name the alternative tools (messages_search, messages_with) explicitly, so it stops 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 content; sending isn't supported' sets clear boundaries and implies this is a discovery/enumeration step rather than a search or send operation. It adds the precondition 'needs Automation access for Messages', which is actionable guidance an agent must have before calling.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavior: newest-first ordering, a hard Full Disk Access requirement with a typed error on failure, and an explicit 'sending isn't supported' limitation. It stops short of covering result caps or pagination, but the extension beyond annotations is substantial.

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

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

Three short sentences, all front-loaded: scope and ordering first, then result-shape pointers, then the access prerequisite and the text-only constraint. No filler and nothing buried at the end.

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

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

With annotations covering safety, an output schema covering return values, and the description covering the auth prerequisite, ordering, and capability limits, an agent has nearly everything needed to call it correctly. The only real omission is any guidance on the 'limit' parameter or result-size ceilings.

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. 'Search by text content' implies how 'query' is matched, but 'limit' is never mentioned in either the schema or the description, and the return pointer note (id/summary format) explains output rather than inputs.

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 ('Search Messages by text content') plus the backing store (chat.db) and ordering (newest first). It implicitly separates itself from messages_chats and messages_with, but it never names those siblings outright, so an agent must infer the boundary rather than read it.

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

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

The description gives conditions ('Text-only for now; sending isn't supported') and a prerequisite (Full Disk Access), which frames when the tool is applicable. It does not, however, tell the agent when to pick this over messages_with or message_body for similar-looking lookups, leaving that comparison 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the data source (chat.db), ordering (newest-first), the Full Disk Access requirement, and the typed error raised when access is missing. It does not cover pagination or rate-limit behavior, but adds meaningful operational context.

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

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

The description is compact and front-loaded: the resource, source, ordering, contact/country semantics, and access requirement are all presented without filler. Every sentence adds useful information.

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

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

Given an output schema exists, return formatting is not needed. The description covers the key behavioral constraint (Full Disk Access), source and ordering, and two of three parameters. The missing limit semantics and lack of sibling routing guidance are the only notable 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 must carry parameter meaning. It explains contact as a phone number or email and country as an optional calling code or 2-letter region with a locale-derived default, but it omits the limit parameter entirely, leaving one of three parameters undocumented.

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

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

The description states a specific verb/resource: recent messages by phone or email, read-only from chat.db, newest-first. It is clear enough to distinguish from general message search, but it does not explicitly name or contrast with siblings such as messages_search or messages_chats.

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 by 'Recent Messages by phone or email.' The description does not say when this should be used instead of messages_search, messages_chats, or message_body, and it provides no explicit exclusions or routing guidance.

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

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

Annotations already declare destructiveHint=true, and the description aligns with them ('DESTRUCTIVE but recoverable') while adding genuine depth: bytes are backed up and the source logged before anything moves, the 25-id cap is not overridable, cross-account moves leave one copy while label moves are refused, and Automation plus Full Disk Access are required. The only miss is that permission/keychain failure modes beyond the timeout path are not described.

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

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

Front-loaded with purpose and destructiveness, and almost every sentence carries an operational constraint that would otherwise cause a failed call. It is nonetheless a dense wall of text with mild redundancy between the Gmail-label-refusal sentence and the later restatement, which costs it the top mark.

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

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

Output schema exists so return values need not be explained, yet the description still lists them and tells the agent to keep `receipt` for undo, plus documents per-id `status`, the timeout/receipt recovery path, and the required system permissions. Nothing an agent needs to invoke this safely and 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 0%, so the description must carry the full burden and does: `ids` are RFC822 message-ids, comma-separated, max 25; `dry_run` defaults true; `from_mailbox` must be the verbatim opaque imap:// token from the originating read and a canonical name is refused; `to_mailbox` accepts canonical accessors with a documented On My Mac and Gmail-label refusal. That is far more than the bare types in the schema.

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

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

Opens with a specific verb and resource ('Move messages between Mail mailboxes — archive, file, or refile') and immediately distinguishes itself from siblings by noting 'there is no separate archive tool' and pointing at mail_undo as the reversal path. An agent can tell this apart from trash_mail or delete_draft without opening a schema.

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

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

Explicit about when this is the right tool (archiving by moving into an 'Archive' mailbox), about the default preview behavior ('dry_run DEFAULTS TO TRUE … Pass dry_run=False to move'), when to consult mail_overview, and when to re-run vs. call mail_undo after a timeout. Refusal cases are enumerated rather than left to discovery.

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

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

Beyond the annotations, it explicitly discloses that the change is 'additive, reversible player-state change', that macOS Automation permission is required, and that the response is the resulting now-playing state. This is exactly the kind of safety, prerequisite, and side-effect context annotations alone cannot convey, and it is consistent with destructiveHint=false.

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

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

Two dense sentences with zero filler: scope and action set first, then side-effect/permission/return semantics. Nothing to trim and nothing front-loaded incorrectly.

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 tool with an output schema and non-destructive annotations, the description covers purpose, legal values, side-effect profile, permission prerequisite, and response shape. An agent has everything needed to call it correctly.

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

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

With 0% schema description coverage and no enum declared in the schema, the description compensates by fully enumerating the legal values for the single `action` parameter. It stops short of explaining each action's edge behavior (e.g. what 'previous' does at track start), which keeps it from a 5.

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

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

States a specific verb and resource ('Control Music playback') and enumerates the exact action set (play|pause|playpause|next|previous), which cleanly separates it from read-only siblings like now_playing and from playlist/volume tools (play_playlist, set_volume, music_search). An agent can identify what this does without opening the schema.

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

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

The action enumeration implies when each mode applies, and the parenthetical 'needs Automation access for Music' hints at a prerequisite. However, it never routes the agent to alternatives (now_playing for a read-only query, play_playlist for playing a named playlist, set_volume for loudness), nor states when not to use this tool.

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

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

Beyond readOnlyHint/destructiveHint, the description adds real behavioral context: results are bounded, an Automation permission is required for Music, and the tool returns persistent IDs rather than playing audio. These are exactly the facts that change how an agent calls it.

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, each front-loading the most decision-relevant information first (what it searches, how to filter, what it returns). No filler.

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

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

An output schema exists so return values need no explanation, and the description still flags the pointer/persistent-ID shape and the permission prerequisite. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: query is optional, matches name/artist/album substrings, and an empty value enumerates all results bounded. That is more than the schema's bare string type communicates.

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 (Music library + playlists) and immediately delimits the output as 'pointers'. The clause 'no audio plays' separates it from playback siblings such as music_control, play_playlist, and now_playing without naming them.

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

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

'Empty lists all, bounded' plus 'no audio plays' tells the agent both how to enumerate and when this is the wrong tool for playback. It stops short of explicitly naming music_control as the alternative, which keeps it from 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?

Goes well past the readOnlyHint annotations: discloses the hard cap of 50 ids, that unknown ids are silently skipped (a real failure-mode detail), the return shape, and the Automation-access requirement for Notes. That is precisely the context annotations cannot carry.

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

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

Four tight clauses, no filler. The core action is front-loaded, and the operational caveats (cap, silent skip, permissions, id source) follow in descending order of importance.

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

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

An output schema exists so return values need not be described, yet the description still sketches the [{id, body}] payload; combined with the cap, skip behavior, and auth requirement, an agent has everything needed to call this correctly on the first try.

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% for the single 'ids' parameter, so the description must compensate — and it does, establishing the max of 50, the silent-skip behavior for unrecognized ids, and the upstream source of valid ids. It stops short of stating format/syntax of an individual id, keeping it at 4.

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

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

States a specific verb and resource ('hydrate plaintext bodies for note ids') and immediately distinguishes itself from the pointer-only siblings notes / notes_all. An agent can tell exactly what it gets back (plaintext bodies) versus what the list tools return.

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

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

Explicitly names where the ids come from ('Get ids from notes / notes_all') and frames the tool as an opt-in second step after pointer-only search. It does not spell out a when-not-to-use case, but the two-step workflow is unambiguous.

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

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

Goes well beyond readOnlyHint by disclosing return shape and ordering, CJK tokenization limitations, fast-path NoteStore.sqlite access requiring Full Disk Access, in-memory body search, locked-note skipping, and fallback behavior. This is unusually 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?

Front-loads the purpose and return shape, then moves into access and behavior details. It is dense but mostly earns its place; 'Read-only' duplicates the annotation and 'Automation access is the floor' is slightly cryptic.

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 search tool with an output schema and non-trivial access paths, the description covers return shape, degraded mode, and body-search limitations. It still leaves title-query semantics and sibling choice under-specified, but is largely complete 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?

The single parameter title has 0% schema description coverage. The description usefully says search covers title, snippet, and body and explains body tokenization, but it never explicitly defines title as the query string, match type, or exactly how the parameter drives those searches.

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: search Notes by title, snippet, and note body. It names notes_all and note_bodies, but does not explicitly say how this search tool differs from them, 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?

Provides useful access context: the fast path requires Full Disk Access, otherwise it degrades to an Automation title search. It also points to notes_all and note_bodies, but never states when to choose this tool over those alternatives or when not to use it.

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

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

Well beyond the readOnlyHint annotation it already has: it discloses the full-disk-access requirement for the SQLite fast path, the fallback to Automation enumeration, the osascript timeout risk on very large libraries, and that the fallback is all-or-nothing. This is exactly the operational context an agent needs to interpret partial failure.

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

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

Front-loaded with purpose, scope, and exclusions in the first clause, then layered operational detail. It is dense with jargon (NoteStore.sqlite, osascript) but each clause carries distinct information, so little could be cut without losing behavioral signal.

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?

Though an output schema exists, the description still previews the pointer fields, and it covers permissions, degradation, and failure modes for a tool whose behavior varies by environment. Nothing needed to call it correctly or interpret results is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly describes a parameterless call and adds no misleading guidance about filters or options.

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