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

Annotations declare the destructive/open-world profile, and the description adds substantial context beyond them: which rules are skipped and that they are reported under `skipped` with reasons, the refusal behavior for forwarding/replying/add-on rules, and the two-tier "Always block" vs "Ask me each time" flow with a pending_user_confirmation status. This is exactly the operational detail an agent needs before triggering a destructive action.

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 layered with constraints in a logical order (skip rules, refusal rules, confirmation path). Some sentences are dense with quoted UI labels, but 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?

Despite having no output schema, the description discloses the meaningful return signals (`skipped` list with reasons, pending_user_confirmation status) and the escalation path. For a destructive, non-idempotent, open-world operation, this covers everything needed to invoke it safely.

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

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

Schema coverage is 100%, so accountId and folderPath are already documented in the schema and the description adds no syntax or format detail beyond what is there. Baseline 3 applies since the schema carries the parameter burden.

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: "Run filters now on the existing messages of a folder." This clearly distinguishes it from the CRUD siblings (createFilter, updateFilter, deleteFilter, listFilters, reorderFilters), which manipulate rule definitions rather than executing them against 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?

Explains the key precondition for invocation (only enabled rules marked "Manually Run" execute) and points to listFilters as the follow-up path when confirmation is pending. It does not explicitly state exclusions like "use updateFilter to change rules first," but the trigger conditions are clear enough to act on.

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-read-only, non-idempotent, non-destructive write; the description adds real behavior on top: no duplicate detection, a silent default address book when the id is omitted, and a minimum-content constraint. It stops short of saying what comes back or whether the new contact's id is retrievable, which matters for a create with no output schema.

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

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

Three tight clauses, front-loaded with the action, then the address-book resolution, then the duplicate-check warning. No sentence is redundant and nothing is buried.

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

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

For a 12-parameter create tool with no required fields, the description covers the critical gaps: address book selection and the absence of deduplication. The remaining omission is the return value (whether the created contact or its id is returned), which is left undefined because no 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 100%, so the baseline is 3, but the description adds meaning the schema does not: where addressBookId should come from (searchContacts rows) and what happens if it is omitted. "Set at least one field" is a non-obvious constraint given that the schema declares zero required 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 description opens with a specific verb+resource ("Add a contact to an address book") and immediately scopes it against the two siblings that could be confused with it, searchContacts and updateContact. An agent can distinguish create from update from lookup 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 gives explicit routing: search first with searchContacts because there is no duplicate check, and use updateContact to change an existing contact. It also states the fallback when addressBookId is unknown (the first writable book), which is the main decision an agent faces 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 only declare it is a non-idempotent write; the description adds the genuinely non-obvious behavior: no duplicate detection, immediate insertion with an eventId, versus a deferred two-phase flow when the user's settings require Thunderbird's dialog, in which case existence is confirmed via listEvents with the reviewId. That is exactly the kind of context annotations cannot convey.

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

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

Information is front-loaded and every sentence earns its place, with routing, duplicate-check advice and return behavior packed densely. The final clause ('listEvents with the reviewId of the result tells') is slightly convoluted and 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?

For a 13-parameter mutation tool with no output schema, the description compensates by explaining that eventId (or a reviewId-based path) comes back and under what conditions. Permissions or calendar-writability caveats are left to the schema's calendarId note, a minor gap.

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

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

Schema description coverage is 100%, so all 13 parameters (including skipReview, reminders, calendarId defaults and enum semantics) are already documented in structured data. The description only indirectly touches skipReview through the settings-versus-immediate-creation explanation, 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?

States a specific verb and resource ('Create a calendar event') and immediately distinguishes it from two siblings: updateEvent for changes and createTask for to-dos. An agent can tell exactly what this tool does and what it is not 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 explicit routing rules: use updateEvent to modify, createTask for to-dos, and call listEvents first because no duplicate check is performed. These are concrete when-to-use and pre-requisite instructions rather than implied 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, but the description goes well beyond them: it discloses the server-side policy gate on sending rules, the exact refusal behavior, the pending confirmation return shape with confirmationId, and who can approve (the user alone). It also pins down the value encoding for forward and reply actions, which 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?

The core purpose is front-loaded in the first sentence, and every following clause carries substantive policy or format information rather than filler. It is dense and the parenthetical asides make sentences long, but nothing is genuinely expendable.

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 seven-parameter mutation tool with nested action/condition objects and no output schema, the description covers the risky parts: refusal policy, confirmation handoff, and action value formats. It leaves the normal success return value unspecified, which an agent might want when chaining to applyFilters or updateFilter.

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 the schema already documents every parameter, including nested actions and conditions. The description adds a little beyond it, notably that forward takes one plain address and that reply takes a Templates message URI in <folder URI>?messageId=<id>&subject=<subject> form, but this duplicates the schema's value documentation rather than introducing new semantics, keeping it at the baseline.

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

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

States a specific verb and resource: 'Create a mail filter rule on an account,' which clearly separates it from updateFilter, deleteFilter, reorderFilters, and applyFilters in the sibling list. The only reason it is not a 5 is that it never names those alternatives explicitly; separation is inferred from the verb rather than stated.

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 conditional guidance: sending rules are refused by default, the 'Ask me each time' preference turns the call into a pending_user_confirmation handoff that must be completed via listFilters with confirmation: true, and certain rule types (64, 128, 256) are always refused. That is real when-to-use and what-happens-next guidance, though it does not say when to prefer createFilter over updateFilter for an existing rule.

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, the description discloses important behavior: an existing folder name is an error, saved searches are live views with no mail moves, and on IMAP the server may finish later with a null path requiring listFolders verification. It also states the return shape, which is valuable because no output schema is provided.

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, stating the primary creation path first and then the savedSearch alternative and return/error behavior. Every clause carries useful information without unnecessary repetition.

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

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

For a non-read-only, non-destructive creation tool with a nested savedSearch object and no output schema, the description covers the key modes, duplicate-name error, return value, and IMAP async caveat. An agent has enough information to invoke it correctly and verify the result.

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

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

Schema coverage is 100%, so the schema already documents each parameter in detail. The description still adds meaningful context by identifying parentFolderPath as coming from listFolders and by clarifying that savedSearch creates a live view rather than moving mail.

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 subfolder or saved search. It distinguishes the two modes clearly and references listFolders for the parent path, so an agent can identify the operation without opening the schema.

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

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

It explains the two creation modes and clarifies that savedSearch produces a live view with no mail movement, which is useful context for choosing between them. It does not explicitly compare itself to createFilter or state when not to use this tool, but the main usage context is clear.

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

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

Beyond the annotations, it discloses important behavior: no duplicate checking, immediate creation with a taskId, and an alternate path where the task exists only after the user saves it in Thunderbird's dialog. It even explains how to verify that path using listTasks and the reviewId, which is unusually transparent 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 description is short and front-loads the purpose and duplicate-check warning before explaining the conditional creation behavior. The final sentence is dense but every clause carries necessary behavioral information.

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

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

For a non-idempotent mutation with seven parameters and no output schema, the description covers the essential behavioral outcomes: immediate creation, dialog-based creation, duplicate-check absence, and result verification. Combined with the fully described schema, an agent has enough information to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents all seven parameters, including skipReview. The description adds some result semantics around taskId and reviewId but does not meaningfully deepen parameter interpretation beyond what the schema provides, so the baseline of 3 is appropriate.

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 a task (to-do)', which unambiguously distinguishes it from sibling tools such as createEvent and updateTask. It also immediately adds scope by stating there is no duplicate check and that listTasks should be used first.

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 pre-use step ('listTasks first') and explains the conditional outcome depending on user settings. It does not explicitly compare against createEvent or state when not to use this tool, but the task-vs-event distinction is strongly implied by the title and purpose.

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

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

The annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description earns credit for adding that address books have no trash or undo and that an unknown contactId errors while deleting nothing. The error-deletes-nothing behavior is consistent with the non-idempotent hint. A small gap remains: it does not say what a successful response returns (though no output schema exists).

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 permanent/no-undo warning, then the id sourcing and alternatives. 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?

For a one-parameter destructive tool with full schema coverage and annotations, the description covers irreversibility, id provenance, pre-check, and the alternative tool. No output schema exists, so nothing further is required.

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 parameter already documents itself as the contact UID from searchContacts, so the description mostly restates provenance. That repeated pointer is useful for sequencing but adds little semantic depth 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?

"Permanently delete one contact" gives a specific verb, resource, and scope (one contact, permanent), which separates it from updateContact and the bulk deleteMessages-style siblings. An agent can pick it 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 explicitly names the source of the id (searchContacts), the verification step (getContact first), and the alternative for modification (updateContact). When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: a recurring event deletes the entire series, not just one occurrence. It stops short of saying whether the deletion is permanent or lands in trash, and whether it fails on unknown 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?

Two short sentences, the identifier requirement front-loaded, and the recurring-event caveat second. Nothing is redundant or padded.

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

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

For a two-required-param destructive operation with 100% schema coverage and destructive/idempotent annotations, this is close to complete. The remaining gap is reversibility and failure behavior for an invalid or already-deleted event, which matters for a destructive call.

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

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

Schema coverage is 100% and both properties already carry '(from listEvents)', so the description mostly repeats the schema. The series-deletion sentence slightly enriches eventId semantics (a master ID implies series removal), but that is marginal beyond what the schema provides.

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 (delete) and resource (calendar event), plus the two identifiers required. This is unambiguously distinct from the sibling deletes (deleteTask, deleteContact, deleteFilter, deleteMessages), which target different resources.

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

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

The parenthetical '(from listEvents)' tells the agent the prerequisite discovery step for both IDs, which is real routing guidance. It does not say when NOT to use it, nor how to delete only one instance of a recurring event, which would be the natural alternative case.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, yet the description adds real context: indices shift up after deletion (why a second call with the same index is unsafe), and that deletion may be refused or prompt the user depending on the account's block-setting. It does not describe the failure response shape, but the operational caveats are well beyond the annotation set.

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 index source, then the mutation caveats. Dense but every clause carries information; the nested quoting in the second sentence makes it slightly harder to parse than necessary.

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

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

For a two-parameter destructive tool with no output schema, this covers the key things an agent needs: which index space to use, index invalidation, and conditional refusal. Return/error format is absent but that gap is minor given the lack of an 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?

Schema coverage is 100% and the schema already documents both accountId and filterIndex including the 'from listFilters' hint. The description adds only the shift-after-delete note, which is more behavioral than parameter-level, 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?

States a specific verb and resource ('Delete a mail filter') plus the addressing scheme ('by index (from listFilters)'), which distinguishes it cleanly from siblings like listFilters, updateFilter, and createFilter.

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 where filterIndex comes from (listFilters) and explains the conditions under which deletion succeeds or is refused ('Always block' vs 'Ask me each time'). It stops short of naming updateFilter as the alternative when the user only wants to change a filter, so it is strong but not fully routing.

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, the description discloses the two-stage deletion model (Trash first, permanent only when already in Trash), the possibility of a user confirmation prompt, and asynchronous server-side completion on IMAP that must be verified with listFolders. These are exactly the traits an agent cannot infer from annotations. It loses a point for the slightly ambiguous phrase 'possibly after asking the user', which leaves the confirmation behavior conditional and unclear.

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 action and its consequence lead the sentence, with caveats compressed into parentheses and a trailing follow-up instruction. The nested clauses (Trash / permanent / confirmation) make the middle section dense enough to require a second read, but no sentence is wasted.

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

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

For a one-parameter destructive tool with no output schema, the description covers what an agent needs: scope of deletion, staging behavior, confirmation possibility, and how to verify completion via listFolders. Nothing material is missing.

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

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

Schema coverage is 100% and the single folderPath parameter is already documented in the schema as a URI from listFolders. The description adds no further meaning about format, constraints, or failure modes for the parameter, 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 ('Delete a mail folder and all its contents') and immediately carves out an edge case (saved searches are views, no mail deleted), which tells an agent exactly what object is affected. It stops short of distinguishing itself from near-siblings such as moveFolder or renameFolder by name, so it is clear but not maximally differentiated.

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

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

Usage is implied rather than stated: the agent learns to follow up with listFolders on IMAP, and that deleting a saved search is harmless. There is no explicit when-to-use versus when-not-to-use guidance against alternatives like moveFolder or deleteMessages, and no prerequisite such as listing folders first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond that by disclosing the actual disposal path: soft delete to Trash, hard delete inside Trash itself, and hard delete on IMAP accounts configured not to move deleted mail. It does not state whether a confirmation is returned or what happens for non-existent IDs, which keeps it just short of a 5.

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

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

Two sentences, zero filler; the core operation and its scope lead, the behavioral exceptions follow, and the sibling routing closes it out. Dense but every clause carries decision-relevant 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 two-parameter destructive tool with full schema coverage and no output schema, nothing an agent needs before calling it is missing: scope, disposal semantics, and the alternative tool are all present.

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 both parameters are documented there, including provenance (folderPath comes from listFolders or searchMessages). The description adds no further parameter detail, so the schema carries the weight and 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?

States a specific verb (delete) and resource (messages) with explicit scope (from one folder), and names the sibling it is not (updateMessage for move/tag). The Thunderbird Delete-key analogy makes the semantic model immediately recognizable.

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 this for deletion, use updateMessage to move or tag mail. It also spells out the conditions that change the outcome (in Trash = permanent, IMAP without move-to-trash = permanent, drafts go to Trash), which is when-to-use guidance at a level most definitions never reach.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description still earns credit by disclosing what the annotations cannot: deletion happens "at once with no review dialog" and a recurring task is removed "with its whole series." Those two facts materially change an agent's risk calculus before calling a destructive 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?

Two sentences, zero filler, and the critical irreversible behavior is front-loaded right after the identifiers. Every clause carries distinct information: scope, immediacy, recurrence semantics, and two alternative routes.

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

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

For a two-parameter destructive tool with full schema coverage and no output schema, everything an agent needs is present: required identifiers, irreversibility, recurring-series consequence, and misidentification handling. 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 100% and both properties already document their provenance ("from listTasks"), so the description adds little parameter-level meaning. The one genuinely additive detail is that passing a recurring task id affects an entire series, but this is framed as behavioral scope rather than parameter format or validation, 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?

States the specific verb and resource ("Delete a task") plus the exact identifiers required (taskId + calendarId), and explicitly distinguishes the operation from its nearest siblings: "An event id is refused: use deleteEvent." An agent can tell immediately this is task deletion, not event deletion or task update.

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

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

Goes beyond naming alternatives to stating the condition that selects each one: event ids route to deleteEvent, and keeping the task as done routes to updateTask with completed: true. These are true when-to-use-otherwise instructions, not just a list of related tools.

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 idempotentHint=false, but the description explains why: "It changes the user's screen, and Thunderbird may mark the message read." That side-effect disclosure (read-state mutation) is genuinely additive context an agent could not infer from the hints. It stops short of covering failure behavior (e.g., invalid or missing messageId/folderPath), which keeps it off a 5.

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

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

Two compact sentences with the primary action and mode options front-loaded, followed by the usage rule and the side-effect caveat. Every clause carries information; there is no filler or repetition.

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

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

For a three-parameter, non-destructive display tool with full schema coverage and annotations, the description covers purpose, alternative, and side effects. The only minor gap is what happens when the message or folder cannot be found, which is a small omission given no 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 100% and the enum for displayMode already documents '3pane' as default, 'tab' and 'window'. The description only echoes the default mode and adds no format or derivation detail beyond the schema's "from searchMessages" hints, 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?

"Show a message to the user in Thunderbird" names a specific verb and resource, then immediately specifies the surfaces (3pane mail view by default, or tab/window). It also distinguishes itself from getMessage, so an agent can tell display-vs-read apart 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?

"Use it when the user should look at it; to read it yourself, getMessage" gives an explicit when-to-use rule and names the exact alternative tool with the condition that selects it. Nothing is left to inference.

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

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

Beyond the destructiveHint=true annotation, it discloses that messages skip Trash, that there is no undo, and that the response returns a per-account deleted count. This is precisely the behavioral context an agent needs before an irreversible bulk delete, though it does not cover permission requirements or partial-failure behavior.

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

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

Front-loads the destructive scope in the first clause and compresses alternatives and return value into the remainder with no filler sentences. It is dense and slightly run-on, 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 single-optional-parameter destructive tool with no output schema, it covers blast radius, irreversibility, review path, partial-delete alternative, and return value. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100% and the schema already explains that omitting accountId empties Junk for all accessible accounts, so the description largely restates it. It adds only the consequence framing ('every account MCP clients may use'), which is a mild reinforcement rather than new syntax 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 (permanently delete), resource (all messages in Junk and its subfolders) and scope (one account or all accessible accounts). It explicitly distinguishes itself from deleteMessages ('only some: deleteMessages') and implicitly from emptyTrash by naming Junk as the target folder.

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

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

Gives explicit routing: use getRecentMessages to review first, and use deleteMessages when only some messages should go. The alternative and the condition that selects it are both named, so an agent can choose correctly without opening other schemas.

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 by spelling out blast radius: folders inside Trash are removed too, omission of accountId widens the operation to every accessible account, and there is no undo. The annotations already flag destructiveHint=true and idempotentHint=false, but the description adds what actually gets destroyed and how wide the reach is. Only the per-account response shape is touched on lightly in one clause, which is why this is a 4 rather than a 5.

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

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

Front-loads the destructive action and the permanence warning, then packs the alternative routing into short fragments. Those fragments ("Only some messages: deleteMessages; spam: emptyJunk") are a bit telegraphic, though nothing is wasted or repetitive.

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 single-parameter destructive tool with no output schema, and the description covers the key risks an agent would otherwise miss: nested-folder deletion, the all-accounts default, irreversibility, and the fact that the result is a per-account status. Nothing essential to invoking it safely is missing.

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

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

Schema coverage is 100% and the schema already documents accountId, including the all-accounts fallback when it's omitted. The description echoes that same fact slightly differently ("every account MCP clients may use"), which reinforces the risk but adds little new semantic detail. Baseline 3 is appropriate when the schema carries the 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 ("Permanently delete everything in Trash") plus the exact scope: the whole container including nested folders, for one account or all accessible accounts. It is immediately distinguishable from deleteMessages and emptyJunk, which it names.

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 to alternatives with the condition that selects them: partial message deletion goes to deleteMessages, junk mail goes to emptyJunk. The accountId semantics also make the one-account-versus-all-accounts choice explicit rather than inferred.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavioral context: direct send is gated by a user-facing safety block, draft mode depends on another tool being enabled, and draft mode returns messageId + folderPath. It does not explain what the destructiveHint implies for the source message (e.g., whether anything is moved or deleted), which keeps it from a 5.

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

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

The text is compact and front-loaded, leading with what is forwarded before the mode branch, with each mode's parenthetical carrying real prerequisites rather than filler. The nested parentheses make it dense to parse, but no sentence is wasted.

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

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

For an 11-parameter tool with no output schema, the description covers the decision-critical parts: default mode, per-mode requirements, the safety gate on sending, and the draft-mode return values. Remaining details such as window-mode behavior are low-risk and adequately implied by 'compose window for review' plus 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 coverage is 100%, so the baseline is 3, but the description adds mode-conditional meaning the schema only states tersely: 'to' is optional in draft mode, required in send mode, and skipReview is framed as the legacy switch tied to the review safety block. The attachment parameter's additive nature ('original content and attachments') is only indirectly clarified, leaving a small 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 ('Forward with the original content and attachments'), so the agent immediately knows this forwards an existing message rather than composing a new one. It does not explicitly contrast with replyToMessage or sendMail, but the forwarding semantics are unambiguous enough to distinguish it from 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 spells out the three modes and the condition that selects each: window for review (the default), draft to persist and return messageId + folderPath (requiring the saveDraft tool to be enabled), and send requiring to/from while being blocked unless the user disables the skipReview safety block. That is explicit when-to-use, when-not, and dependency guidance rather than implied usage.

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 read-only, idempotent, non-destructive and closed-world, so the description only needs to add context. It does so by disclosing that the value is read-only by design regardless of tool inventory and by describing the shape of the returned setting.

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

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

Two tight sentences: the reported content comes first, the immutability constraint second. No filler or restatement of the name.

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

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

With no output schema, the description carries the return-value burden and does so by naming 'mode' and the account fields (id, name, type). Combined with the explicit immutability note, 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?

The tool takes no parameters and the schema is empty, so there is nothing for the description to disambiguate; the baseline for zero-param tools applies. The description correctly implies no inputs are needed.

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

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

The description gives a specific verb ('Report') and resource ('the account access setting') and enumerates the returned fields (mode all/restricted, accounts with id, name, type). It implicitly separates itself from listAccounts by scoping the accounts to those 'MCP clients may use', 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?

It clearly states the negative case: the setting cannot be changed by any tool, only by the user in the Options page, which prevents an agent from hunting for a write counterpart. It does not, however, say when to prefer this over listAccounts for enumerating accounts.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered by structured data. The description's real contribution is the field inventory it returns, which matters because there is no output schema. It says nothing about behavior when the id is invalid or whether the contact is fetched live versus cached.

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 followed by a colon and a terse field list — no filler. The list-of-fields tail is dense but readable; minor deduction for the slightly telegraphic style rather than full sentences.

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

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

With one parameter, no nested objects, and no output schema, the definition covers what the agent needs: how to obtain the id and what comes back. Only the absence of error/empty-result behavior keeps it from being fully complete.

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

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

Schema description coverage is 100%, and the schema already labels contactId as the "Contact UID (from searchContacts results)". The description restates the same provenance hint without adding format, validation, or example values, so it neither helps nor hurts beyond baseline.

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

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

"Read one contact by id" gives a specific verb (read), a specific cardinality (one), and the resource (contact), which cleanly separates it from searchContacts and the list* siblings. It also enumerates the returned fields (emails, name, phones, addresses, organization, title, note, birthday), so the agent knows exactly what it gets.

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?

"(from searchContacts)" tells the agent the intended workflow: resolve an id via searchContacts, then fetch the full record here. That is clear context, though it stops short of stating any negative case (e.g. not for browsing all contacts, no fallback when the id is unknown).

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 annotations: the message is 'Not marked read', writes occur only via saveAttachments with copies placed in <OS temp dir>/commonpost-mcp/<messageId>/, and long bodies truncate with bodyTruncated/nextBodyOffset. This actually explains why readOnlyHint=false for a read tool and notes the authentication results are 'unverified'. It stops short of describing rate limits or error conditions, so a 4.

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 core purpose, then uses compact clauses for alternatives, truncation, and side effects. The telegraphic style (colons, semicolons, parentheticals like '(authentication; unverified)') packs a lot per sentence, but nearly every clause carries actionable information; 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 9-parameter tool with no output schema, the description covers what comes back, the truncation protocol, the attachment-write destination, and the <email-content> prompt-injection boundary. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description adds cross-parameter meaning: maxBodyChars pairs with bodyTruncated/nextBodyOffset and bodyOffset continues the truncation, while saveAttachments yields a filePath per attachment. It also frames bodyFormat's markdown default and the rawSource exclusion for inline images. These inter-parameter relationships go beyond individual schema entries.

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?

Names a specific verb and resource ('Read one message in full') and enumerates the returned parts: headers, tags, body, attachments, and SPF/DKIM/DMARC results. It explicitly contrasts with the siblings getMessages (several) and displayMessage (show to the user), so an agent can distinguish it 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 between alternatives: 'For several messages use getMessages; to show one to the user, displayMessage.' It also states the pagination procedure ('call again with bodyOffset') and the condition under which disk writes happen ('only saveAttachments writes').

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

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

Adds real behavior beyond the annotations: partial-failure semantics (an unreadable message gets an error entry while the others still come back) and the return envelope { messages, requested, succeeded, failed }, which is valuable since no output schema exists. It does not, however, surface the disk-write side effect of saveAttachments — the one plausible reason the annotations set readOnlyHint=false on a tool described as "Read" — leaving that tension unexplained in prose.

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: capability and limit first, the getMessage substitution rule second, return shape and error behavior last. Every clause carries information an agent needs, and the most decision-relevant fact (batching instead of repeated calls) is front-loaded.

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

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

For a 7-parameter tool with no output schema, explaining the return envelope and partial-failure behavior is exactly the right compensation. Remaining gaps are the saveAttachments write-to-disk consequence and when to prefer getMessage — useful but not fatal, since the schema describes each parameter fully.

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 documents messages, rawSource, bodyFormat, headersOnly, rawEncoding, maxBodyChars and saveAttachments in detail. The description reinforces only the headersOnly threshold (10 vs 200) and otherwise defers to the schema; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Read up to 10 messages in one call") plus the batching scope, and distinguishes itself from the sibling getMessage by saying output is "each as getMessage returns it" and that it replaces repeated getMessage calls. An agent can pick it over getMessage/getRecentMessages without opening any schema.

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

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

Gives an explicit selection rule: use this instead of repeated getMessage calls, and switch to headersOnly when you need up to 200 messages rather than 10. It names the alternative (getMessage) but leaves the converse unsaid — nothing tells the agent to fall back to getMessage for a single message or when a full body beyond 10 items is needed.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description still adds real context beyond them: Trash and Junk are skipped unless included, results come newest-first, and the response envelope matches searchMessages. It does not mention pagination or hasMore explicitly, which keeps it from a 5.

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

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

Two sentences with zero waste; the scope and ordering are front-loaded, and the sibling routing follows immediately. Nothing is repeated or padding.

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

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

For a ten-parameter read tool with no output schema, the description supplies the important context: default Trash/Junk exclusion, ordering, folder scoping, and a pointer to searchMessages for the row/envelope format. Only pagination behavior is left implicit, a minor gap.

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

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

Schema description coverage is 100%, so every one of the ten parameters is already documented in the schema. The description only reinforces the folder scope and the Trash/Junk exclusion default, adding little syntax or constraint detail beyond what the schema provides; baseline 3 is correct.

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

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

The description uses a specific verb and resource ('Recent messages newest-first from all folders of all accounts ... or from one folder') and immediately distinguishes itself from searchMessages by stating it runs 'with no query'. An agent can tell exactly what this tool returns and how it differs from the query-based sibling.

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 selection rule: use this tool for unfiltered recency, and 'to filter by words, sender or dates, use searchMessages.' That names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds the non-obvious exclusion rule that user-hidden accounts are omitted and points to getAccountAccess. It does not discuss ordering or whether the result set is ever empty, but the substantive behavioral facts are present.

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 the key scoping constraint first. It is dense with nested parentheticals — 'identities (id, email, name, isDefault: the from of compose tools)' requires re-reading — but 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 no output schema and no parameters, the description carries the return-shape burden and does so by listing each field and its cross-tool meaning. What remains unstated (ordering, count limits) is minor for an account-list tool.

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

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

Zero parameters, so the baseline is 4. The description instead spends its words on return-value semantics (accountId linkage, isDefault as the compose 'from'), which is the correct use of space for a no-arg tool.

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

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

States a specific verb (list) and resource (accounts), and immediately scopes it: accounts the MCP client may use. It also enumerates the returned fields (id, name, type, identities), so an agent knows exactly what it gets back and can distinguish this from getAccountAccess.

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?

Implied usage is clear — this is the entry point for discovering account IDs before calling other tools, and the description ties `id` to 'the accountId of other tools'. The parenthetical reference to getAccountAccess signals where to go for hidden accounts, but the when/when-not routing is implicit rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: a disabled calendar lists nothing and blocks createEvent/createTask until the user enables it, which is a downstream consequence the agent could not infer from 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?

Three short sentences with zero filler: the field list first, then the id's downstream use, then the disabled-calendar caveat. The most actionable information (the id) is front and center.

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

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

There is no output schema, so the description carries the burden of describing return values, and it does so by naming every field. Combined with the explanation of what 'disabled' means operationally, an agent has everything needed to call this and use the result correctly.

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

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

The tool takes no parameters, so the baseline is 4 and there is no parameter surface the description needed to explain. Instead it spends its words on output-field meaning, which is the useful place for them.

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 calendars') and immediately enumerates the returned fields (id, name, readOnly, disabled, supportsEvents, supportsTasks), so the agent knows exactly what it gets. No sibling tool lists calendars, but the description also cross-references the event/task tools that consume the id, making its role 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?

Implies the primary use case explicitly: 'The id is the calendarId of the event and task tools,' which tells the agent to call this before createEvent/createTask. It also names the precondition that a disabled calendar causes createEvent/createTask to refuse. It stops short of an explicit when-not-to-use statement, but no competing calendar-listing alternative exists.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: the source of truth is Thunderbird preferences and the returned names are case-sensitive. It does not say whether the result is an array of strings or how empty/preferences-less cases behave, and there is no output schema to cover that gap.

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

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

Two tight sentences: the action and data source first, then the workflow guidance. Every clause earns its place and the important constraint (case-sensitivity) is included without padding.

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

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

For a zero-parameter read-only tool with full annotation coverage, the description supplies everything needed to call it correctly, including the case-sensitivity caveat. The only missing piece is the return shape (a list of names), which is a small gap given there is no 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no inputs are needed, and there is nothing further to document.

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

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

States a specific verb and resource: 'Return all calendar category names defined in Thunderbird preferences.' The mention of 'category names' distinguishes it from the sibling listCalendars, which returns calendars rather than categories, so an agent can route 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?

Gives clear when-to-use guidance: call it before creating tasks or events to obtain exact category names. It does not name an alternative tool or state when not to call it, which keeps it short of a 5, but the intended workflow context 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, and the description adds real substance beyond them: recurring events are returned as occurrences sharing the series id with a recurrenceId, there is a hard cap with no paging, and all-day end dates mean the last day. It omits timezone handling, which matters a lot for a date-range event query.

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 range and source, then recurrence, then the cap, then row fields — a sensible order with no filler sentences. The trailing 'Rows:' enumeration is long but earns its place because there is no output schema to document the return shape.

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-required-parameter read tool with no output schema, the description covers defaults, ordering, recurrence representation, result capping, and the returned fields — everything an agent needs to call it and interpret the result. Timezone behavior is the only notable omission and is minor relative to what is covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that the range defaults to the next 30 days, that an all-day 'end' is the last day, and that maxResults is a hard ceiling rather than a page size. It also implicitly maps 'all calendars or one' to calendarId, though reviewId is left entirely 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 verb and resource ('List events'), the scope ('in a date range (default: next 30 days)'), the source ('from all calendars or one'), and the ordering ('by start time'). An agent can distinguish this read/list operation from siblings like updateEvent, deleteEvent, and listCalendars without opening the schema.

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

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

Gives clear operating context: defaults to the next 30 days when no range is supplied, and explicitly instructs 'no paging: narrow the range for more' when results exceed maxResults. It does not name an alternative sibling for cases this tool cannot serve, but no obvious competing event-search tool exists here, so the gap is small.

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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it explains that the confirmation mode changes nothing, enumerates the five possible states including that 'accepted' means written, 'refused' means dialog closed, 'expired' means no answer in 10 minutes, and 'failed' means nothing was written. It also discloses operational limits (one pending confirmation, five dialogs per hour) and the client-side restriction, which are exactly the behaviors 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?

The purpose is front-loaded in the first sentence, but the second sentence is a long run-on with nested parentheticals and five enumerated states, making it hard to parse at speed. Nearly all content earns its place, but the delivery is denser than necessary and could be split into separate labeled sentences.

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

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

With no output schema, the description usefully characterizes what both modes return, including the state vocabulary and what 'conditions and actions' means for filter records. Given the tool's low complexity and full schema coverage, this is close to complete; only per-filter field detail is left implicit.

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

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

Schema description coverage is 100%, so all three parameters are already documented and the baseline is 3. The description restates the confirmation/confirmationId relationship rather than adding syntax or format detail beyond the schema, and its extra material concerns returned states rather than parameter 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 and resource ('List the mail filters (rules) of one account or all, with conditions and actions'), which is unmistakably distinct from siblings like updateFilter, createFilter, applyFilters and reorderFilters. It then explicitly names the second mode (confirmation: true) and what it returns, so an agent can tell both behaviors apart without opening the schema.

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

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

Gives clear conditional guidance: omit accountId for all accounts, use confirmation: true to read confirmation state, use confirmationId to narrow to one request, and no confirmationId to see pending plus recent requests and limits. It also draws a capability boundary ('MCP clients cannot accept, refuse or cancel a confirmation'), which steers the agent away from a futile action. It does not name sibling tools as alternatives, so it falls short of an explicit when/when-not rubric.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds detail beyond them: refresh fetches new mail first, waits up to 20 seconds, returns { refresh, folders }, and the listing is flat. Those are meaningful behavioral and output-shape details an agent would not get from the 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 description is dense but front-loaded and every clause carries information: output fields, routing guidance, and refresh behavior. There is no filler and the semicolon-separated structure keeps the key usage rule easy to find.

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

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

With no output schema, the description compensates by naming the returned fields and explaining the refresh return shape. Combined with annotations covering safety and a fully documented schema, it gives an agent enough context to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful connections: the returned path is the URI that folderPath accepts, and refresh is only meaningful with folderPath. It also gives examples for the folder type field, though most parameter details are already 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?

The description gives a specific verb and resource (list mail folders), states the flat output shape, and enumerates the returned fields (name, path, type, accountId, counts, depth, isFavorite). It also explicitly distinguishes the tool from message-reading siblings by naming searchMessages and getRecentMessages.

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 the primary use case: find a folderPath. It also routes message retrieval to searchMessages or getRecentMessages, and explains that refresh must be combined with folderPath. This gives explicit when-to-use guidance and clear alternatives for a common adjacent task.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond that: due-date sorting with undated last, no paging, and the exact row fields including priority encoding.

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 front-loaded: sorting, result cap, returned row fields, and sibling routing are packed into three semicolon-separated clauses without filler.

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

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

There is no output schema, so the description supplies the return shape via the row field list and priority mapping, and it also discloses sorting and no-paging behavior. This is complete for a read-only list tool.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the maxResults cap and all-calendars scope but does not add per-parameter meaning for completed, dueBefore, format, or reviewId beyond what the schema provides.

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 ('List tasks (to-dos)'), states the scope ('from all task calendars or one'), and clearly distinguishes this read operation from updateTask and listEvents.

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 that omitting calendarId covers all calendars, that results are capped at maxResults with no paging, and explicitly routes modifications to updateTask and events to listEvents.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false. The description adds genuinely new behavioral context beyond them: that on IMAP accounts server-side completion is asynchronous and must be verified with listFolders. It doesn't say whether the operation fails or merges on a name collision, but the async caveat is the most important thing 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?

Two sentences, the core action first and the operational caveat second, with no redundant restatement of the title or parameters. 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?

With two fully documented parameters, complete annotations, and no output schema, the description covers what an agent needs to invoke the tool and to know that IMAP results are eventually consistent. A note on name-collision behavior or failure modes would close the last gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the note to source URIs from listFolders. The description adds no further meaning about formats, path semantics, or edge cases, 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 uses a specific verb and resource ('Move a mail folder to a new parent folder') and constrains scope with 'within the same account'. It doesn't explicitly distinguish itself from renameFolder or createFolder, so an agent must infer that moving differs from renaming.

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 same-account restriction and the advice to verify with listFolders on IMAP give some implied usage context. However, there is no explicit guidance on when to choose this over renameFolder, or what to do if the destination already contains a folder with the same name.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: server-side completion on IMAP is asynchronous, so a caller must poll listFolders to confirm the rename. That is non-obvious and goes beyond structured data, though it says nothing about permission requirements or what happens if the new name collides.

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 followed by a single operational caveat. No filler and nothing redundant.

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

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

For a two-parameter rename with no output schema and rich annotations, the description covers the essential risk (asynchronous IMAP completion). It could be slightly fuller on error/collision behavior, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100% and both parameters are documented in-schema, including that folderPath comes from listFolders. The description adds no meaning beyond the schema, 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 opens with a specific verb+resource ('Rename an existing mail folder'), so an agent immediately knows the operation. It is not explicitly distinguished from siblings like moveFolder or createFolder, but the resource specificity makes selection 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?

It supplies a post-condition workflow for IMAP accounts (verify with listFolders), which is useful implied guidance. However, it gives no when-to-use vs. alternative guidance (e.g., moveFolder for relocating) and no stated prerequisites or failure conditions.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description goes meaningfully beyond them by disclosing a refusal path: in a list containing a mail-sending rule the move is rejected under "Always block". It also explains the confirmation mode returning status pending_user_confirmation, which an agent needs in order to handle the call 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?

Two compact sentences with the core action front-loaded and the edge-case behavior second; nothing is padded. The second sentence is slightly compressed ("In a list that holds a rule sending mail this is refused") but remains readable.

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 three-parameter mutation with full schema coverage and annotations covering the safety profile, the description supplies the two things structured fields cannot: the refusal condition and the pending-confirmation return status. It omits what happens to the indices of adjacent filters, which is a minor residual gap.

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

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

Schema description coverage is 100% (accountId, fromIndex, toIndex are all documented, including "0 = highest priority"), so the baseline is 3. The description's phrase "execution order" reinforces the meaning of the indices but adds no syntax, bounds, or shift behavior beyond the schema.

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

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

States a specific verb and resource ("Move a filter") plus the dimension being changed ("position in the execution order"), which implicitly separates it from updateFilter and createFilter/deleteFilter. It stops short of naming a sibling or stating what it does not do, so it is clear but not fully differentiated in the text itself.

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 mention of "execution order" implies the context in which the tool applies, but there is no explicit when-to-use versus updateFilter guidance and no stated prerequisites (permissions, whether filters must exist at both indices). Usage must largely be inferred from the verb.

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

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

Goes well beyond the annotations by disclosing the recipient-computation logic in draft mode (Reply-To, Mail-Followup-To, mailing lists, identity auto Cc/Bcc), the return values (messageId, folderPath), and the skipReview safety gate. The annotations already flag destructiveHint and openWorldHint, and the description adds the operational prerequisites that make those hints actionable.

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 action is front-loaded and no clause is filler, but the entire definition is a single run-on sentence with deeply nested parentheticals, which makes the mode semantics harder to scan than a short bulleted breakdown would be.

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 13-parameter mutation tool with no output schema, the description covers the risky parts: mode selection, send prerequisites, the safety block, and draft-mode return shape. It leaves the attachment and replyAll behaviors entirely to the schema, which is acceptable given full schema coverage but is the remaining gap.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters, which sets the baseline at 3. The description does add real meaning for mode and skipReview (legacy alias for send), but says nothing about attachments, replyAll, isHtml, or latestInThread 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 ('Reply with quoted original text') and immediately scopes the three execution modes. It implicitly distinguishes itself from forwardMessage and sendMail by framing everything as a reply to an existing messageId, but it never names a sibling outright, so an agent must infer the boundary.

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

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

Gives concrete when-to-use guidance per mode: window is the default compose-for-review, draft requires saveDraft to be enabled, send requires to and from and is blocked unless the user disables the skipReview safety block. That is strong conditional guidance, though it offers no explicit 'use X instead' routing to forwardMessage or sendMail.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world; the description adds substantive behavior on top: nothing is sent, no compose UI opens, messageId and folderPath are returned, and editing a draft disposes of the prior version while preserving omitted fields. It does not cover auth or identity-resolution requirements, keeping it below the top score.

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 core action and then the draftId variant, with no padding or restatement of the name. The clause 'without sending or opening a compose window, as the compose window does' is mildly redundant in its phrasing but still carries disambiguation 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?

For a 12-parameter tool with no output schema, the description covers the return shape (messageId + folderPath), the create-versus-edit mode split, and merge semantics on edit. Remaining detail — attachment count limits, folderPath fallback search, isHtml interaction — is already documented at 100% schema coverage, so nothing critical is missing.

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

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

Schema coverage is 100%, so field-level meanings are already covered, but the description adds cross-parameter semantics the schema cannot express: passed fields replace while omitted ones (body, recipients, attachments, reply headers) are kept, and the old version is removed. That merge-versus-replace rule is the single most important thing an agent needs and it comes from the description, not the schema.

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

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

States a specific verb and resource (save a composed message to the Drafts folder) plus the negative scope that distinguishes it from sending and from the compose window, and names the return values. The second sentence carves out the distinct edit mode with draftId, so an agent can tell both modes apart from sendMail 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?

Provides clear usage context — save for review and send later, and use draftId when rewriting an existing draft rather than creating a new one. It stops short of naming the sibling alternative explicitly (e.g. 'use sendMail when the user wants it delivered now'), so the routing is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavior beyond that: result rows carry id and addressBookId, and truncated result sets set hasMore, telling the agent to refine the query rather than assume an exhaustive answer.

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

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

Front-loads the purpose, then workflow, then return shape in three compact clauses with no wasted wording. The clause 'A cut list sets hasMore: refine the query' is telegraphic enough to read slightly awkwardly, but it is not padded.

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

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

No output schema exists, so the description carries the return-shape burden; it names the key row fields and the pagination signal, which is what an agent needs to continue. It omits the remaining contact fields returned per row, a minor gap for a search tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it by tying truncation (hasMore) to the result cap and clarifying that the returned id is the contactId used by the contact tools. It adds little on 'format' beyond the schema's own enum documentation.

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

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

States a specific verb+resource ('Find contacts') plus the matching semantics (words matching email, name or organization) and can be told apart from getContact (id lookup) and createContact (creation) without opening any schema.

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

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

Gives an explicit use case with an alternative: 'Search before createContact to avoid duplicates.' It does not say when to prefer getContact or another listing tool, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that: the default exclusion of Trash/Junk and the exact response envelope { messages, totalMatches, offset, limit, hasMore } with the per-row id + folderPath needed for follow-up calls, which is not stated in any annotation.

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 compact sentences, front-loaded with purpose, then the alternative, then the return shape, then the follow-up tools and recipe. It is dense with parenthetical shorthand but nothing is redundant; it could be slightly more scannable as a list, but every sentence carries information.

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

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

For a 21-parameter search tool with no output schema, the description supplies the missing piece — the return envelope and row shape — and routes to getRecentMessages for the common no-query case. Gaps are minor, e.g. pagination via offset/hasMore is only implied by naming hasMore, and pagination size limits live only in 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 100% with 21 richly documented parameters, so the schema already carries the parameter burden and baseline is 3. The description's only added parameter meaning is the pairing of 'participant:@domain' with groupBy for company-wide searches, which is a useful but modest increment over what the query and groupBy descriptions already say.

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 message headers across accounts') plus the scope constraint that Trash/Junk are skipped by default. It explicitly names the sibling it is not (getRecentMessages) and explains how the returned rows feed into getMessage/getMessages, 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?

Gives an explicit routing rule: for the latest mail with no query, use getRecentMessages instead. It also supplies a concrete usage recipe ('participant:@domain' with groupBy) and the follow-up path to getMessage/getMessages. It stops short of covering when to prefer query-only search vs the schema's searchBody full-text mode, so it is strong but not fully exhaustive.

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 openWorldHint=true, but the description adds the critical operational trait: the default call opens a compose window and the result does NOT mean the mail was sent. It also discloses that skipReview is refused while the default-on block is active, which explains the destructive path's safeguard.

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 dense sentences, front-loaded with the action and the sibling routing, then the behavioral caveat, then the two override flags. Parenthetical sibling list is efficient rather than wasteful.

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

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

For a 10-parameter, non-idempotent, outward-facing tool with no output schema, the description covers the safety-critical behavior and defaults well. It stops short of describing what a dryRun or skipReview call actually returns, though the schema's field docs partially fill that gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by explaining how skipReview and dryRun interact with the default compose-window flow rather than restating their field docs. It does not add anything about attachments, cc/bcc, or isHtml beyond the schema.

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

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

States a specific verb and resource ('Write a new email') and immediately routes the three adjacent intents to siblings (replyToMessage, forwardMessage, saveDraft). An agent can distinguish this from the other compose-family tools without opening any schema.

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

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

Gives explicit alternative routing (replies/forwards/unsent to specific sibling tools) plus the condition for each mode: default compose-window flow, skipReview only when the user disabled the block, dryRun for check-only. This is the when/when-not guidance the dimension rewards.

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, the description discloses the two distinct mutation semantics agents most often get wrong: additive/partial field updates and wholesale list replacement for emails, phones and addresses. That explains the destructiveHint=true annotation rather than contradicting it; it stops short of covering failure modes or permission requirements.

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

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

A single sentence with two clauses, the identifying key first and the destructive replacement caveat second. Nothing is redundant or padded.

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

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

For a destructive mutation with a rich, fully described schema, the description covers the essential contract: what identifies the target and how field values are applied. Error behavior and whether omitted lists are preserved versus the empty-array clear are only inferable, keeping it from a 5.

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 per-property descriptions already state 'replacing the list' and '[] clears it', so the description's list-replacement clause largely restates structured data. Baseline 3 is appropriate for a fully documented 12-parameter schema.

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

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

States a specific verb and resource plus the keying strategy ('Update a contact by id'), which separates it from searchContacts/getContact/createContact well enough to act on. It does not explicitly name any sibling, but the mutation verb makes the distinction obvious.

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?

'only passed fields change' clarifies the partial-update contract, which is useful context, but there is no explicit guidance on when to use this versus createContact/deleteContact or what to do if the contact does not exist. Usage is implied rather than stated.

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

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

Goes well past the annotations (destructiveHint=true, idempotentHint=false) by explaining *why* it is consequential: changes are saved immediately with no review dialog, and a recurring event changes the entire series rather than one occurrence. That series-wide side effect is the single most important behavioral fact and is not derivable from the schema or 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 compact sentences ordered by importance: what it does, how it behaves destructively, then routing to alternatives. Every clause carries information; there is no filler or restatement of the 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?

For a 12-parameter mutation with no output schema, the description covers the critical risks (immediate save, whole-series propagation) and the identifier source. It stops short of saying whether a single occurrence of a recurring event can be edited at all, which is the one ambiguity an agent might still hit.

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 the parameters are already self-documenting (including the null/[] clearing semantics for showAs, reminders, and categories). The description's only parameter-adjacent contribution, that eventId and calendarId come from listEvents, merely restates what the schema fields already say. 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 plus resource ("Change an existing event in place") and immediately scopes it with "only the fields passed change." It explicitly names the sibling operations it is not (createEvent for new, deleteEvent for removal), so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use (modify an existing event) and names both adjacent alternatives with their conditions: "New event: createEvent; removal: deleteEvent." It also tells the agent where the two keys come from (listEvents), which is the prerequisite for invoking it at all.

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 destructive/non-idempotent/open-world; the description adds the substantive policy layer — which edits are blocked by default, which are permanently refused, and that the call can return {status: "pending_user_confirmation", confirmationId} instead of applying. That outcome-shape disclosure is exactly the behavior an agent cannot infer from the hints.

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

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

The core action is front-loaded in the first clause and every subsequent sentence carries refusal or confirmation information that earns its place. The second sentence is densely nested with parentheses and quoted policy names, costing some parseability.

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

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

For a 7-parameter destructive mutation with full schema descriptions and no output schema, the description supplies the missing decision-critical context: refusal policy, confirmation return shape, and the permanently blocked filter types. Nothing needed to call it safely is absent.

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

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

Schema coverage is 100% so the baseline is 3, but the description earns more by giving meaning to the otherwise bare `type` bitmask (64, 128, 256 = outgoing, archiving, periodic) and by tying `enabled` edits to the refusal rules. It does not clarify that omitted fields are left untouched rather than reset, which is the main semantic ambiguity remaining.

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?

"Change an existing filter's properties, conditions or actions" gives a specific verb plus the exact resources being mutated, which cleanly separates it from createFilter, deleteFilter and reorderFilters in the sibling set. An agent can pick this tool without opening any schema.

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

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

It spells out when the call will be refused (forward/reply actions, editing a list holding a sending rule, types 64/128/256) and what to do on the "Ask me each time" path, which is real routing guidance. It never explicitly contrasts createFilter for new filters, and the instructed follow-up ("listFilters, confirmation: true") names a tool that does not expose a confirmation parameter, leaving the retry path ambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the risk profile is covered; the description adds context beyond them — the IMAP tag-plus-move race and the instruction to split into two calls — which is genuinely non-obvious behavior. It does not state whether existing tags are preserved on a read/flag update, nor whether partial failures across bulk messageIds are atomic, leaving some mutation semantics undisclosed.

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

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

Three sentences, front-loaded with the primary capability, then tag vocabulary, then the IMAP caveat — each sentence carries distinct information with no restatement of the title or schema. Nothing could be cut without losing meaning.

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

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

For a nine-parameter destructive mutation with no output schema, the description covers the operation set, target cardinality, tag vocabulary, and the key platform caveat, which is enough to call it correctly. It leaves open what the tool returns and how bulk operations report per-message failures, a modest gap given no output schema exists to answer that.

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

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

Schema description coverage is 100%, including the moveTo/trash mutual exclusion and built-in keyword labels, so the schema already does the heavy lifting and a 3 is the correct baseline. The description adds only the framing that tags are 'Thunderbird keywords (see addTags)', which is a useful cross-reference but not additive detail about parameter behavior.

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 concrete verb ('Set') and enumerates the exact mutable attributes (read, flagged, tags) plus the two move modes, so the agent knows precisely what the tool mutates. It differentiates the singular/plural targeting (messageId vs messageIds) in the same sentence. It stops short of naming sibling tools it supersedes (e.g. deleteMessages, addTags) as explicit alternatives, which keeps it from 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?

It gives a real operational rule for when to split work: 'On IMAP, tags set in the same call as a move may not reach the moved copy: use two calls.' It also routes the agent to addTags for tag semantics. What's missing is guidance on choosing this tool over deleteMessages for removal, or what to do when neither messageId nor messageIds is supplied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety bar is lower; the description still adds real behavior — atomic save with no review dialog, partial-update semantics, and the side effect that completed:true also stamps 100% and the completion date. It does not explain what the response looks like or what happens on an invalid taskId, which is a moderate gap for a mutation tool that is flagged destructive.

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 compact sentences plus short routing fragments, with the core semantics (in-place change, only passed fields, immediate save) front-loaded. No filler or repetition of 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?

Covers patch semantics, identifier sourcing, the completed cascade, and sibling routing for an 8-parameter mutation with no output schema. Remaining gaps are the response/confirmation behavior and error handling for unknown taskId or calendarId.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it by explaining that 'completed: true' cascades to percentComplete and sets the completion date — a cross-field effect the schema only hints at. It does not add detail for title, description, priority, or dueDate, which the schema already documents well.

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

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

States a specific verb and resource ('Change an existing task in place') and immediately pins down the patch semantics: only the fields passed change. It names the sibling tools (createTask, deleteTask) for adjacent intents, so an agent can distinguish this from create/delete 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 to createTask for new tasks and deleteTask for removal, and tells the agent where the required identifiers come from (taskId and calendarId from listTasks). That is concrete when-to-use and when-not-to-use guidance rather than inference.

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