Timbre

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

Annotations already declare destructiveHint=false and idempotentHint=false, so the safety profile is partly given. The description adds meaningful behavior beyond that: the draft is opened in Mail for user review and, critically, 'Never sends' – confirming no message reaches recipients. It does not say what happens if a draft is re-created or whether an existing draft is overwritten.

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 closed with the key guarantee. No redundant restatement of the name or title.

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 description covers modes, the review step, and the no-send guarantee. What remains thin is permission/prerequisite context and draft-collision behavior, but the core picture is sufficient for correct invocation.

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

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

Schema coverage is 71% and the schema already documents id, to, body, subject and the mode values. The description mirrors the mode list ('reply, reply-all or forward') but adds no syntax, format, or edge-case meaning for cc/bcc or the interaction between id and to beyond what the schema states.

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

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

States a specific verb and resource (write a new message / reply / reply-all / forward) plus the outcome (opens it in Mail as a draft). The 'Never sends' clause sharpens the distinction from any send-like operation, though no sibling tool is named explicitly.

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

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

Usage is implied by 'for the user to review' – this is the composing path that leaves the message in the user's hands. There is no explicit when-not guidance or reference to alternatives such as open_in_mail or read_mail, so the agent must infer the 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?

Annotations already declare non-readonly, idempotent, non-destructive, but the description adds real behavioral context the annotations cannot: creation may happen via Mail or directly on the server, and the first creation in an account triggers an OS password prompt whose credential is stored in the keychain and never exposed to the agent. The auth-prerequisite disclosure is the standout value; the vague "Mail makes it when it will" leaves the exact delegation logic fuzzy.

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 verb and resource are front-loaded, which is good, but the second sentence is a long, loosely punctuated run-on that mixes fallback logic, a password prompt, and keychain behavior. It is informative rather than padded, yet the password aside could be one tighter clause.

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 mutation with an output schema (so return values need no explanation), the description covers side effects, auth prerequisites, and path semantics. The remaining gap is duplicate-name behavior and error modes, which idempotentHint only partially implies.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description largely restates them (the "Projects/2026" nesting example mirrors the schema wording). It does reinforce the hierarchical path semantics and the account-naming convention, but adds little beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb+resource ("Make a mailbox") and immediately disambiguates what a mailbox is ("a folder, or a Gmail label"), which is genuinely useful across mail clients. It doesn't explicitly contrast with siblings like list_mailboxes or delete_mailbox, but creation versus listing/deletion is self-evident, so the gap is minor.

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

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

Usage is only implied — an agent infers you call this when you need a new folder, and the path-format example gives practical invocation guidance. There is no explicit when-not guidance, no mention of what to do if the mailbox already exists, and no pointer to list_mailboxes for verifying before creating.

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 destructiveHint=true annotation: it discloses that no Mail confirmation appears, that the first use per account triggers a macOS password prompt stored in the keychain (never visible to the agent), and that deletion is server-side and limited to server-confirmed-empty mailboxes. It stops short of stating whether the deletion itself is reversible, which matters for a destructive tool, so not a full 5.

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

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

Front-loaded with the action and constrained to one dense paragraph where every clause carries operational information. The keychain aside and the "Mail lets no app do this" framing are slightly conversational but still earn their place by explaining the auth prompt.

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 and annotations covering the destructive profile, the description still supplies everything an agent needs: emptiness precondition, auth flow, sibling tool to use first, and scope exclusions. Nothing material is missing for a 2-parameter destructive tool.

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

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

Schema coverage is 100%, so the schema already explains both parameters, including that account disambiguates names across accounts and that mailbox accepts a name or path. The description only reinforces the mailbox concept as a folder or Gmail label, adding little beyond structured fields. Baseline 3 applies.

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

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

States a specific verb and resource ("Delete an empty mailbox (a folder, or a Gmail label) on its mail server") and immediately distinguishes itself from siblings by noting Mail's own API cannot do this, so it is a server-side operation rather than a Mail-app action like move_mail.

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

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

Gives the explicit precondition (only a mailbox the server says is empty), the alternative to use first ("move its messages out first with move_mail, which can be undone"), and a hard exclusion list (inbox, sent mail, drafts, trash, junk, provider folders). An agent knows both when to call it and when not to.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's job is to add operational detail, which it does: results are ordered oldest-first and each message is reduced to new text with quotes stripped. It does not mention truncation behavior when max_chars_per_message cuts a message off, which is the one behavioral gap.

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

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

A single dense sentence with no filler, front-loading the resource ('the whole conversation') before the two output-shaping facts. Every clause carries information an agent would otherwise have to infer.

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 structure need not be explained, and the description covers scope, ordering, and text extraction. What remains missing is the routing decision against sibling tools (read_mail, search_mail) and what happens on truncation, which matters for a tool whose output is deliberately clipped.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, including the 25/100 limits and the 1500-char default. The description reinforces the ordering and quote-stripping semantics but adds no new parameter meaning, so the baseline of 3 applies.

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

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

The description identifies the exact resource returned: the entire conversation that a given message belongs to, distinct in scope from single-message siblings like read_mail or selected_mail. It lacks an explicit verb ('retrieve'/'fetch'), so it reads as a return-value summary rather than an action statement, but the resource is unambiguous.

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

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

Usage is only implied: 'the whole conversation' suggests this is the tool to pick when surrounding context is needed rather than one message. It never states when to prefer this over read_mail, nor any prerequisite that the id must be a valid message in an accessible mailbox.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results include message and unread counts and role classification, which hints at the data shape, but says nothing about ordering, multi-account grouping, or whether unread counts are refreshable.

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

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

A single compact sentence with no wasted words, front-loading the resource and then the returned attributes. It is a sentence fragment rather than a complete statement, which slightly weakens readability.

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

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

For a zero-parameter, read-only listing tool with an output schema present, the description covers the essentials: what is listed and what fields accompany it. The missing piece is how this list relates to downstream tools in the mail workflow, but nothing required to invoke it is absent.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and nothing to compensate for. Baseline 4 applies.

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

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

The description names the resource precisely (accounts and their mailboxes) and enumerates the mailbox roles it surfaces, so an agent can tell this is a mailbox-enumeration tool. It lacks any differentiation from siblings like selected_mail or mail_status, and it reads as a noun phrase rather than a verb+resource statement, relying on the name for the action.

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

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

There is no when-to-use guidance, no mention of alternatives such as selected_mail or mail_status, and no stated prerequisites. The agent must infer that this is a discovery step used to obtain mailbox identifiers before other mail operations.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing the contents of the status payload (index progress, read-only mode, sending state, attention hints). What it does not say is whether the status is expensive to compute or whether counts are exact or approximate.

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

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

A single front-loaded sentence that opens with the subject (Timbre's state) and then enumerates facets. The list phrasing is dense but every item names a distinct piece of state, so nothing reads as filler.

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

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

With zero parameters, an output schema that documents the return shape, and annotations covering the safety profile, the description only needs to say what state exists, which it does. The remaining gap is the absence of explicit invocation guidance relative to the 16 sibling tools.

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 description carries no parameter burden and the baseline applies; the schema is empty and fully consistent with a no-argument status read.

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 the resource (Timbre's state) and enumerates the specific facets reported: mail store, message counts, full-text index progress, settings, and attention hints. That is enough for an agent to tell it apart from the operational siblings such as list_mailboxes or search_mail, though it never states an explicit verb like 'get' or 'report'.

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

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

Usage is only implied: the mention of 'settings (read-only mode, sending)' and 'hints when something needs the user's attention' suggests calling it before write operations or when diagnosing problems, but there is no explicit when-to-use statement and no named alternative among the 16 siblings.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the useful nuance that flagging accepts an optional colour and that the operations are paired inverses ('set or clear'), which reinforces reversibility, but it says nothing about batch failure behavior or partial application across ids.

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

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

A single front-loaded sentence with no filler; the parenthetical cleanly scopes the colour to the flag operation. Nothing is wasted or buried.

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

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

With an output schema present and annotations covering safety and idempotency, the description supplies enough to call the tool correctly. The one gap is that the 1-500 id limit and expected response shape live only in structured fields, which is acceptable given the schema richness.

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

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

Schema coverage is 100%, so all three parameters are already documented; baseline is 3. The description's only added meaning is tying colour to the flag action and signalling its optionality, which the schema largely already conveys.

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

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

Uses a specific verb ('Mark') with the resource ('messages') and enumerates all four supported states (read, unread, flag, unflag) plus the optional colour. An agent can distinguish this state-toggle tool from siblings like read_mail (reads content) or move_mail 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?

Usage is only implied: the description makes clear it is a state-changing batch tool, but it never states when to prefer it over alternatives (e.g. read_mail) or any preconditions such as ownership or folder scope. Adequate for a self-evident toggle, but no explicit when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is structured data. The description does add valuable context beyond that: the operation is never a permanent delete and yields an undo_token, and provider-specific (Gmail) behavior is disclosed. However, the tension between destructiveHint=true and "never deletes permanently" is left unqualified, and the non-idempotent nature (what happens on repeat moves) is 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 the action and destinations, then constraints; every clause carries information. The Gmail sentence is dense and reads almost telegraphically ("refused with what to do instead"), which slightly hurts scannability but does not waste space.

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 explained, yet the description still usefully flags the undo_token. Combined with the Gmail and no-archive-mailbox edge cases, the definition covers the risky paths an agent needs before invoking a destructive move.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, and the description adds only the notion of a named mailbox as a destination. It adds nothing about the 1-200 id cap or when the account parameter is needed beyond what the schema states.

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

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

States a specific verb and resource ("Move messages") and enumerates the valid destinations (archive, trash, inbox, junk, named mailbox), so the action is unambiguous. It does not contrast itself with siblings such as mark_mail or undo_move, so an agent must infer the boundary from names alone.

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

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

Encodes real when-not conditions: Gmail moves are refused except to trash/junk (and out to All Mail), with a pointer to what to do instead, plus the archive-mailbox creation fallback. What is missing is a forward pointer to undo_move for reversing the returned undo_token, and no explicit statement of when to prefer mark_mail over move.

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 phrase 'on the user's screen' usefully discloses that this triggers a visible client-side action, which explains why readOnlyHint is false despite the read-like verb. Beyond that, it says nothing about whether Mail must be running, what happens if the id is stale, or whether focus is stolen from the user's current work.

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

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

A single sentence with zero filler, and the key qualifier ('on the user's screen') is placed where it is read first. Nothing is redundant.

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

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

With one fully documented parameter and an output schema present, the tool is simple enough that the short description is close to sufficient. The remaining gap is routing: without any mention of read_mail or search_mail as the source of the id, an agent has to work out the workflow from sibling names alone.

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

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

Schema description coverage is 100%, and the id parameter already documents 'Message id from search_mail results.' The description adds no additional meaning about the identifier or its expected format, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Open a message in Mail'. An agent can tell this is a UI-launch action rather than a data fetch. It does not, however, name or contrast with the closest sibling, read_mail, which retrieves message content.

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: open a message so the user can see it on screen. There is no explicit guidance on when to prefer this over read_mail for reading content, nor any prerequisite or exclusion stated. The agent must infer that this is for user-facing presentation rather than content retrieval.

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 it is not read-only, not destructive, and idempotent, so the safety bar is lower. The description adds real context beyond them: it opens the OS Settings app and a Finder window, requires the user to drag Timbre into the list and toggle it, and notes the permission then takes effect by itself without a further tool call. It does not warn about macOS-version differences or what the call returns if the pane is already open.

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

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

Two sentences, each covering one mode, with the failure condition front-loaded before the action. The clause 'so the user only drags it into the list and switches it on' is slightly long but earns its place by setting the user's expectation of manual follow-up.

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 toggle tool with no output schema, the description covers both modes, the triggering failure, and the post-call outcome. No annotations or schema fields are left unexplained, and an agent needs nothing else to decide whether and how to call 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?

Schema coverage is 100%, so the schema already defines the single 'pane' parameter and its default. The description goes further by explaining what each value actually does — full_disk_access selects the app in Finder for dragging, automation targets the Automation pane after macOS blocked Mail control — which is meaning beyond the enum strings.

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 concrete verb and target: it opens System Settings at Full Disk Access and selects Timbre in Finder, and it distinguishes a second mode (Automation). An agent can tell this apart from every sibling tool (create_draft, read_mail, mail_status, etc.) without opening the schema, since none of them touch macOS settings.

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 triggers for both modes: 'When Timbre cannot read Mail yet' for full_disk_access and 'when macOS did not let Timbre act in Mail' for automation. What is missing is any when-NOT guidance or a named alternative to try first, so the routing is clear but not complete.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered; the description adds a genuinely useful behavioral warning that the extracted content is untrusted, which matters for prompt-injection handling. It stops short of mentioning truncation or output shape, but the output schema covers the latter.

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

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

Two sentences, front-loaded with the action and the format scope, with no redundant wording; the security note is placed last where it belongs.

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 rich annotations, full schema coverage, and an output schema, the description only needs to state scope and any special caveat, and it does both; a brief note on truncation behavior would make it complete.

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

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

Schema description coverage is 100%, so id, index, and max_chars are already fully documented including defaults and limits; the description adds only the format list, which is explanatory rather than parameter-level meaning.

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

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

States a specific verb and resource ('Extract the text of an attachment') and enumerates the supported formats, which lets an agent tell it apart from siblings like save_attachment or read_mail 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 description implies usage (call it to get attachment text) but names no alternative and gives no when-not guidance; the only routing hint, 'attachment index as listed by read_mail', lives in the schema rather than the description.

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/openWorld annotations, the description adds genuinely useful behavioral detail: hidden HTML text is stripped, sender-authenticity warnings are surfaced, and the content is flagged as untrusted. That last point is an important safety signal for downstream handling, though nothing is said about large-message truncation behavior.

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

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

Two dense sentences with no filler, front-loading the operation and then the return contents. The parenthetical about hidden HTML is the kind of qualifier that earns its place.

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

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

With annotations covering the safety profile and an output schema covering return structure, the description is nearly complete for a simple read tool. The one gap is routing guidance against get_thread and search_mail, which would help an agent choose correctly.

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

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

Schema coverage is 100%, so id, max_chars, and strip_quotes are already fully documented in the schema. The description adds no additional parameter meaning (for example, how truncation interacts with max_chars), so the baseline of 3 applies.

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

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

A specific verb and resource ('Read one message') followed by the exact contents returned: headers, sender-authenticity warnings, attachment list, and reader-visible text. The 'one message' framing implicitly contrasts with get_thread, but no sibling is named, so the differentiation is left to 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?

The single-message scope implies when this applies versus a thread reader, but there is no explicit when-to-use or when-not-to-use statement and no pointer to search_mail or get_thread as alternatives. Usage is inferable rather than stated.

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

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

Annotations already declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false), so the bar is lower, yet the description still adds real behavior: the exact destination folder and the never-overwrites guarantee, which explains why idempotentHint is false — each call produces a new file. It does not mention whether the folder is created if missing or what happens on filename collisions.

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 destination, with the no-overwrite constraint and return value following. Nothing is wasted.

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

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

Output schema exists, so the return value need not be described (though it helpfully is). The main remaining gap is that max_chars implies text extraction, yet the description never explains that saved content may be truncated by that parameter, which matters for an agent handling large attachments.

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

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

Schema description coverage is 100%, so id, index, and max_chars are already documented in the schema. The description adds no parameter-level meaning beyond that, which is acceptable at full coverage but not enriching.

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

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

States a specific verb and resource (save an attachment) plus the destination (the user's Timbre attachments folder) and a key side-effect (never overwrites). It clearly differs from the sibling read_attachment, which only reads content, though it never names that sibling explicitly.

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

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

Usage is implied: use this when you want the attachment materialized on disk rather than just read. There is no explicit statement of when to prefer save_attachment over read_attachment, nor any prerequisite such as obtaining the index from read_mail (that only appears in the schema).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds genuinely new behavioral facts: the search runs locally against the Mac's mail store, results are "ranked by relevance and recency," junk/trash are silently omitted by default, and IDs are returned for a follow-up read_mail call. These are defaults and side effects an agent cannot infer from the annotation set 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 scope statement and the sibling-routing hint are front-loaded in the first clause, and the second sentence compresses capability into one pass. It is dense and slightly run-on with semicolon-chained clauses, but every clause carries information.

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

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

For a 16-parameter search tool with an output schema, the description covers the things structured fields cannot: local-only scope, default folder exclusions, ranking behavior, and the downstream read_mail workflow. Pagination behavior is left to the schema's limit/offset descriptions, which is reasonable, though a one-line note on paging would make it airtight.

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 81%, so the schema already documents nearly every parameter, including the query operator syntax and pagination fields. The description restates the filter categories (sender, recipient, mailbox, account, dates, unread, flagged, attachments) without adding syntax or edge-case meaning beyond what the schema says, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ("Search the user's email") and immediately scopes it to "every account in Apple Mail on this Mac" searched locally, which separates it from any server-side or single-account mail tool. It also enumerates the searchable fields (subject, people, body, attachment names) so the agent knows exactly what the index covers.

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

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

It gives an explicit directive -- "use it before other mail connectors" -- which is actionable routing guidance, and it states the default exclusion (Junk and Trash skipped unless asked) plus the handoff ("Returns ids for read_mail"). It stops short of distinguishing itself from close siblings such as selected_mail or get_thread, so it falls just short of a top score.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully reveals that the result is derived from live Mail window state (implying it can be empty or change between calls), but it never states that explicitly or warns the agent about an empty selection.

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

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

A single parenthetical sentence that front-loads the resource and appends the one actionable detail. Nothing is wasted and no preamble delays the point.

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 and no input parameters, the description covers everything needed to invoke the tool. The only missing piece is the practical caveat that a selection may be empty or stale when the Mail window is unfocused.

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

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

There are zero parameters, so the baseline is 4. The description correctly adds no parameter talk, and the clause about ids being usable with read_mail gives meaning to what the tool emits rather than what it takes.

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 resource — the messages currently selected in Mail's window — rather than a vague 'selection' concept, and clarifies the payload is ids rather than full messages. It also implicitly separates itself from read_mail by saying the ids are 'usable with read_mail', so the agent knows this is a lightweight handle-fetch, not a content read.

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 clear usage path: call this to get selected message ids, then feed them to read_mail. There is no explicit 'when not to use' or mention of alternatives such as search_mail or get_thread, 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 flag this as destructive, non-idempotent, and not read-only, so the safety profile is covered. The description adds one genuinely useful behavioral detail absent from annotations: Gmail messages return to All Mail, not the inbox. However, it never explains why the tool is destructive (e.g., that it can overwrite a message's current location or labels), leaving the annotation's destructiveHint unelaborated.

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

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

Two sentences, zero waste, with the core reversal action and its sibling reference front-loaded before the Gmail-specific caveat. Each sentence earns its place.

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

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

With an output schema present, return values need no explanation, and annotations carry the safety profile. The description covers invocation modes and a non-obvious provider quirk, though it could say more about failure/expiry behavior for the undo token.

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

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

Schema coverage is 100% and the single token parameter is fully documented in the schema, including the 'omit to undo most recent' default. The description's 'by undo_token, or the latest move' largely restates that, adding no syntax or format detail beyond the schema.

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

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

The description uses a specific verb ('move messages back') tied to a named sibling ('before a move_mail call'), so an agent can immediately distinguish this reversal tool from move_mail itself. The parenthetical clarifies both invocation modes (token or latest).

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 clearly frames usage as undoing a prior move_mail and explains the two selection modes (explicit undo_token vs. latest move). What's missing is any exclusion guidance, such as what happens if no prior move exists or when a token has expired.

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