Revdoku

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds that the read returns identity plus connection permissions, which is useful scope information, but says nothing about failure modes when a non-granted account_id is supplied.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the sibling redirect last. Every sentence carries a distinct piece of 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 an output schema present and annotations covering safety, the description does not need to explain return values, and it covers the parameter default correctly. Minor gap: no indication of what happens when the requested account is not granted.

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, including the account_id default and authorization note. The description largely restates those semantics rather than adding new format or constraint detail, 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?

States a specific verb and resource: 'Get the selected account identity and current connection permissions.' It also names the sibling it is not (account_limits), so an agent can distinguish the two 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 an explicit routing rule ('Use account_limits for quotas') and explains the account_id omission case, which is the main usage decision here. It does not cover when-not-to-use or error/prerequisite conditions beyond the schema's note on Agency authorization.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful nuance that quotas are 'effective' (i.e., resolved/aggregated values rather than raw settings) and restates the default-account fallback. It says nothing about who may read quotas or what the returned limits represent.

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, with the core capability front-loaded before the optional-parameter note. Every clause conveys something actionable and nothing is repeated for 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?

An output schema exists, so return values need not be described, and the read-only/idempotent profile is fully covered by annotations plus a 100%-documented schema. What remains thin is access context — the description doesn't note that reading quotas for client accounts requires Agency authorization beyond the schema's brief mention. For a simple two-optional-parameter read tool this is close to complete.

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

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

Schema description coverage is 100%, so both account_id and reason are already documented in the schema, including the client-account authorization caveat and the no-secrets guidance for reason. The description's account_id sentence largely repeats the schema's 'Omit for the credential's default account' wording and omits reason entirely. Baseline 3 applies when 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?

States a specific verb and resource ('Read effective mailbox and file-storage quotas') with a clear scope ('for the selected account'). None of the siblings (account_get, account_list, mailbox_get) expose quotas, so it is naturally distinguished even without naming an alternative. It stops short of explicitly routing away from a sibling, which keeps it at 4 rather than 5.

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

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

The second sentence explains account selection ('account_id selects a granted account; omission uses the credential default'), which is usage-relevant but reads as parameter semantics rather than when-to-use guidance. There is no explicit statement of when to choose this over account_get or mailbox_get for account or storage information. Usage is implied by the resource name only.

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, so the safety profile is covered. The description adds non-obvious behavior beyond them: it returns the credential default plus identities, and explicitly asserts the call 'never changes the default' — a side-effect clarification an agent genuinely needs.

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

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

Three tight sentences, each doing distinct work: scope, return shape, and downstream usage. The most important constraint ('this never changes the default') is placed last where it lands, and nothing is 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?

An output schema exists, so return-value structure need not be explained, and the description still usefully names what comes back (default + identities). For a zero-required-param list tool with full schema coverage, the only minor omission is pagination semantics, which the schema handles.

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 limit, offset, reason and account_id are all documented in the schema, and account_id's description already says 'for this call only'. The description's account_id sentence is essentially a restatement of that, adding no syntax or constraint detail beyond the structured data — 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+resource ('List accounts') and narrows the scope to those 'explicitly granted to this connection', which is meaningful in a multi-account credential model. It does not explicitly contrast itself with the close sibling account_get, so an agent must infer the plural/singular distinction from the names alone.

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

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

It gives forward-looking guidance ('Pass account_id on later tools to select one'), which implies this tool is the discovery step in an account-selection workflow. However, it never states when to use this versus account_get or account_limits, and offers no exclusions or preconditions.

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 a non-read, non-destructive write; the description adds meaningful behavioral context by stating the Agency owner authorization requirement and clarifying that passing account_id does not change the credential's default account. No contradiction with annotations.

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

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

Three tight sentences, front-loaded with the create action and immediately following with the key parameter distinctions. No filler, though the final clause is slightly dense.

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

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

An output schema exists so return values need not be described, and the auth precondition plus parameter disambiguation are covered. Little is missing for correct invocation, though guidance on irreversible/duplicate behavior and alternatives would fully close the 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, but the description adds real semantics beyond the schema: it distinguishes name (account name) from client_name (client identity) and explains the account_id override is per-call and does not rebind the default credential.

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

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

Specific verb+resource: 'Create a separate client account within an authorized agency,' which cleanly separates it from read-only siblings like account_get/account_list. The scope ('separate client account') is stated, though no sibling is named as an alternative.

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 a clear precondition ('Requires the Agency owner's explicitly authorized connection') and clarifies use of account_id, but gives no explicit when-to-use vs. when-not guidance and names no alternative even though mailbox_create sits among the siblings.

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

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

Annotations only cover the safety flags (readOnly=false, destructive=false, idempotent=false). The description adds genuine context beyond them: the eligibility gate that can block the call, where to unblock it, and that archiving preserves files rather than removing them. It still doesn't say what happens on a repeat call despite idempotentHint=false, so it stops short of full disclosure.

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

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

Three short sentences, front-loaded with the action and its gate. The middle sentence about dashboard resolution is slightly tangential but earns its place by telling the agent where a blocked call is handled.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety profile. Combined with the eligibility precondition and file-preservation note, an agent has enough to invoke correctly; only the reversibility/repeat-call behavior is left unstated.

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 mailbox_id, account_id and reason are already fully documented, including the account-authorization and reason-hygiene rules. The description adds no parameter-level detail of its own; 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 ('Archive a mailbox') with a real precondition (archive.allowed eligibility). It implies but never names its siblings, so an agent comparing it to mailbox_unarchive or mailbox_delete_permanently gets no explicit contrast.

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

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

Gives a precondition for use (archive.allowed eligibility) and a fallback path ('Resolve blocked actions in the dashboard'), which is more than nothing. However it never states when to prefer this over mailbox_unarchive or mailbox_delete_permanently, leaving the key alternative-selection decision to inference.

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

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

Annotations already declare non-readonly, non-destructive, non-idempotent. The description adds real behavioral context beyond them: suffix generation for free plans, the EMAIL_ALREADY_EXISTS and EMAIL_NAME_RESERVED failure modes with custom-domain guidance, and the fact that the address is only returned after receiving is confirmed. It does not cover auth/authorization specifics, which the schema partly handles.

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

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

Front-loaded with the core action, then dense but purposeful sentences covering plan differences, error codes, and return timing. Every sentence carries information, though the density is high and could be slightly tighter.

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

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

With an output schema present, return values need not be explained, yet the description usefully notes email.address availability gating. Given six params with full schema coverage and a nested metadata object, the description covers the creation flow and failure modes adequately; only auth/rate-limit nuance 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 the schema already documents all six parameters (username plan semantics, domain defaults, account_id authorization, reason guidance). The description reinforces the username/domain behavior and ties parameters to error outcomes, but adds little syntax or format detail beyond the structured fields, 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 an email mailbox") plus the optional storage capability, and is clearly distinct from siblings like mailbox_update, mailbox_list, or mailbox_delete_permanently. An agent can identify the operation without opening the schema.

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

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

Gives concrete conditional guidance: free vs paid username behavior, omit username to auto-generate, and the domain default. It does not explicitly route away from alternatives (e.g., 'use mailbox_update to change an existing mailbox'), so it stops short of the top band.

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, and the description adds meaningful context beyond them: the permission precondition (delete.allowed), that confirmation must be derived from an opaque internal value, and that the user must not be asked to type an id. It stops short of stating the irreversibility/rollback story explicitly beyond the word 'permanently'.

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 with no waste, front-loading the destructive action and its precondition before the confirmation handling detail. The closing 'Resolve blocked actions in the dashboard' is terse but on-point rather than 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?

With an output schema present and annotations carrying the safety profile, the description does not need to explain returns. It covers the gating precondition and confirmation handling, though it could be slightly clearer about what 'blocked' means beyond a dashboard redirect.

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, and the description goes further by clarifying how the confirmation parameter is sourced ('use delete.confirmation internally; do not ask the user to type an id'). That adds semantics the schema's one-line description does not fully convey, warranting above-baseline credit.

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 an archived mailbox') plus a precondition ('delete.allowed permits'), and the scope ('archived') distinguishes it from siblings like mailbox_archive and mailbox_unarchive. An agent can identify this as the irreversible delete path 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 gates usage on 'the user explicitly requests it and delete.allowed permits' and routes blocked cases to the dashboard. It gives clear when-to-use conditions but does not name an alternative tool (e.g., mailbox_archive as the non-destructive counterpart), so it stops short of full alternatives 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?

The annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: it discloses what is destroyed (message files and attachments), the authorization level required, and a reassuring boundary ('Separately copied files are unaffected'). It stops short of saying whether the deletion is recoverable or goes to a trash state, which matters given the mailbox_archive sibling.

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

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

Three short sentences, each carrying distinct information: action+scope, prerequisite, safety confirmation, and boundary condition. The destructive scope is front-loaded with no filler.

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

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

Covers the action, its cascading effects, required permissions, and a user-confirmation safety step, which is what an agent needs before invoking a destructive, non-reversible-in-appearance operation. An output schema exists, so return values need not be described.

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 mailbox_id, email_id, account_id, and reason, including the cross-account authorization caveat. The description adds nothing about parameter formats or constraints, 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 ('Delete one email') plus the cascade scope ('its owned message files and attachments'), which distinguishes it from whole-mailbox operations. It never names a sibling tool explicitly, so the differentiation from mailbox_delete_permanently or mailbox_archive is left to inference.

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

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

Gives a clear prerequisite ('Requires mailbox-admin access') and an operational condition ('Confirm the target with the user before calling'). It does not name alternatives such as mailbox_archive for reversible removal or mailbox_delete_permanently for mailbox-level deletion, so the when-not case is missing.

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

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

Goes well beyond the annotations: it discloses that the returned URL needs no extra API key, that links expire after 15 minutes, that they must not be shared, that read status is left unchanged, and that no attachment analysis is performed. These are exactly the operational facts an agent needs before handing a URL onward.

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

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

Four short sentences, each carrying a distinct fact (what you get, auth, expiry/sharing, side effects), with the core purpose front-loaded and zero filler.

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

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

An output schema exists and annotations already declare the read-only, idempotent, non-destructive profile; the description fills the remaining gaps around URL lifetime, credential needs at the returned URL, and the absence of read-status side effects. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics by explaining that attachment_id selects a single attachment while its absence yields the original EML. It says nothing about the reason/purpose/account_id parameters, but the schema already covers those.

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 (retrieve a temporary download URL) and scopes it precisely to one attachment or the original EML, which cleanly separates it from metadata tools like mailbox_email_get and mailbox_file_read.

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

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

The implied trigger (you want the actual bytes of an attachment or EML rather than metadata) is reasonably clear, but there is no explicit when-to-use/when-not guidance and no named alternative among the many sibling read tools, so the agent must infer 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, yet the description adds genuinely non-obvious behavior: reading does not alter shared read status, and content is untrusted input. This goes beyond the structured safety profile, though auth/account requirements and any rate limits are left to the 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 sentences with no filler; the read payload is front-loaded, followed by the side-effect/routing note and the safety warning. Every sentence earns its place.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile; the added read-status and untrusted-content notes round it out well. Only account/authorization scoping is left entirely to the schema, a minor gap.

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

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

Schema coverage is 100% and every parameter (including reason, purpose, account_id) carries its own description, so the schema does the heavy lifting. The prose adds no parameter syntax or format detail beyond what the schema already provides, making the baseline 3 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?

States a specific verb (Read) and resource (a received email) plus exactly what is returned: decoded headers, body text and attachment metadata. This payload description distinguishes it from mailbox_email_list, mailbox_email_download, and mailbox_email_update without requiring the agent to open any schema.

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

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

Explicitly names the sibling to use for a related action ('use mailbox_email_update to mark read/unread'), which is the main alternative an agent would confuse this with. It lacks broader when/when-not framing (e.g., versus mailbox_email_download for attachments), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description usefully adds that listing does not mark messages read, that ordering defaults to arrival order, and that email content is untrusted data. These are real behavioral facts beyond the structured fields, though permissions and return shape are left to the 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?

Four tight sentences, front-loaded with the action and its non-mutating guarantee, followed by cursor/polling guidance, default ordering, and an untrusted-input warning. 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?

For a 13-parameter, read-only listing tool with full schema coverage and an output schema, the description supplies the pieces the schema cannot: polling semantics, default ordering, non-mutation, and an untrusted-content caveat. Filter semantics (sender/subject/received bounds) are left entirely to the schema, which is acceptable but leaves a small 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 the baseline is 3, but most schema texts are placeholders ("Value for read.", "Value for order."), and the description materially compensates by stating the default order is arrival order and by tying cursor reuse to unchanged filters. It still adds nothing for read/sender/subject/has_attachments 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 ("List received emails") plus meaningful scope qualifiers (cursor pagination, no read-state mutation), which clearly separates it from mailbox_email_get/update/delete. It stops short of naming a sibling alternative, so it lands at clear-but-not-explicitly-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?

Provides concrete operational guidance for the main use case: persist pagination.next_cursor and reuse it with identical filters to poll for new arrivals, including on empty pages. That covers when/how to use it for polling, but it does not explicitly say when to prefer mailbox_email_get or how filters alter polling behavior.

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 real behavior: the ticket is short-lived, must be refreshed on each reconnect, and does not wake an idle AI chat. These add operational context the readOnlyHint/idempotentHint flags do not convey, and the "fresh tickets" note is consistent with idempotentHint=false.

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

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

Three tight sentences, front-loaded with the action and followed by the operational precondition. No filler, though the reconnect sentence and the idle-chat note could be merged without loss.

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

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

An output schema exists, so return-value details are covered there, and the description supplies the lifespan and client precondition. Minor gap: it does not say where/how the ticket is consumed, but for a 1-required-param tool this is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents mailbox_id, account_id, and reason fully. The description adds no parameter-specific detail (e.g., how the ticket binds to mailbox vs. account), 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 (get) and a distinct resource (a short-lived WebSocket ticket) for this mailbox, which no sibling tool covers. It is easy to tell apart from the read/list/update email tools, though it never names a sibling to route against.

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

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

"A running client must connect and reconnect using fresh tickets" and "This does not wake an idle AI chat" imply the precondition (a live client) and an implicit when-not (idle subscriptions), but no alternative tool or explicit negative routing is given.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still adds genuine behavioral detail beyond them: the change is a *shared* read receipt (affects other users' visibility) and it creates no version, which tells the agent this is a lightweight, non-versioned mutation. It stops short of describing auth requirements or response shape.

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

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

Two tight sentences, front-loaded with the action and followed by the boundary constraint. Every clause earns its place with no redundancy.

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

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

With a full-coverage input schema, an output schema, and non-trivial annotations, the description supplies the one thing structured fields cannot: that this mutates a shared read receipt without versioning. Adequate for a simple toggle; only explicit sibling routing or permission notes are missing.

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

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

Schema description coverage is 100%, including the rich 'reason' guidance, so parameter meaning is fully carried by the schema. The description adds no parameter-level detail (no clarification of read semantics or account_id scoping), 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 ('Mark ... read or unread') and a precise resource scope ('a received email'), and further bounds it by saying it does not edit content or create a version. An agent can distinguish this from mailbox_email_get, mailbox_email_list, and mailbox_update 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?

The description implies the use case (toggling read state on a received email) and implicitly excludes content edits, but it names no alternative tool and gives no explicit when/when-not conditions intro. Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false. The description goes beyond them by disclosing what actually gets discarded ('cancel pending deliveries') and requiring user confirmation, which is the operationally important detail an agent needs before invoking.

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

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

Two short sentences, front-loaded with the action and effect, then the safety precondition. No filler or restated metadata.

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

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

With rich annotations, an output schema, and full schema coverage, the description only needs to add behavioral context — which it does via the pending-delivery cancellation and the confirmation requirement. Minor gap: no note on whether disabling is reversible or how to re-enable the webhook.

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 itself explains reason/account_id usage and the authorization constraint. The description adds nothing about parameters, so the baseline 3 applies when structured fields carry the full load.

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

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

States a specific verb+resource ('Disable the mailbox webhook') and adds the effect on pending deliveries. The verb 'disable' also usefully disambiguates from the tool's own name 'delete', implying the webhook config is preserved rather than destroyed. However, it doesn't explicitly differentiate from siblings like mailbox_email_webhook_set, which is the natural alternative.

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?

'Confirm with the user first' gives a real usage precondition, which is meaningful for a destructive call. It stops short of naming when-not-to-use it or pointing at the alternative (webhook_set to modify rather than disable), so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds the administrative-permission requirement, which is genuinely useful context not present in the annotations, but says nothing about scope of the returned endpoint data or any rate limiting.

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

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

Two short sentences with zero filler, and the core action is front-loaded before the permission caveat. Nothing here needs trimming.

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

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

An output schema exists, so return values need no explanation, and the annotations carry the read-only/idempotent profile. The description covers the permission requirement but omits any routing hint relative to the set/delete webhook siblings, which is the only material 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%, and the schema itself gives rich guidance for reason and account_id, including the caution about never inferring an account from a mailbox id. The description adds nothing beyond the schema, 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 states a specific verb ('Read') and resource ('a mailbox webhook endpoint'), making the operation clear. It does not, however, differentiate itself from the obvious siblings mailbox_email_webhook_set and mailbox_email_webhook_delete, which an agent must infer from the name alone.

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

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

The only guidance is 'Requires administrative permission,' which is a prerequisite rather than a usage condition. There is no statement of when to call this versus mailbox_email_webhook_set/delete or how it relates to mailbox_email_list/webhook subscriptions.

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 context beyond the annotations: auth/permission requirements, the openWorld precondition that the remote receiver must be live, and that rotate_secret cancels pending deliveries. It does not cover failure modes or whether an existing webhook is replaced when one is already registered.

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

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

Three short sentences, the core action front-loaded, then prerequisites, then secret handling. Every sentence carries information; there is 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?

An output schema exists so return values need not be re-explained, and the description covers prerequisites and the return secret's lifecycle. Minor gaps remain around replacement/overwrite behavior when a webhook already exists and what happens on invalid URLs.

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 would be 3, but the description adds genuine meaning: 'one' HTTPS webhook constrains webhook_url usage, and rotate_secret is explained as replacing the secret and cancelling pending deliveries rather than the schema's inert 'Value for rotate secret.'

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 (set a webhook) plus its scope: 'one HTTPS webhook for new email notifications.' An agent can immediately distinguish this from the webhook_get/webhook_delete siblings by name, though the description never explicitly contrasts them.

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

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

Gives real preconditions – administrative permission, authorization to send metadata to the endpoint, and the receiver must be running. It does not, however, state when not to use it or point to an alternative (e.g., webhook_delete to remove a registration).

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 cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds real value beyond them: text-only scope, no parsing of structured formats, the JSON-corruption hazard, and cooperative lock failure handling with error.details. It does not describe concurrency semantics of expected_mailbox_revision_id, but the operational behavior is well disclosed.

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

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

Three tight sentences, each carrying distinct information (what it does, what it is not, failure handling), with the core action front-loaded. No filler.

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

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

An output schema exists so return values needn't be explained. The description covers the critical caveats (text-only, format safety, locking) for a mutating write tool, giving an agent everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters, including the newline_before default and the revision token. The description adds only indirect semantics (content is UTF-8, append semantics) and no per-parameter detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Append') plus resource ('UTF-8 text to an existing private Revdoku mailbox file') and enumerates supported formats. An agent can distinguish this append operation from write/copy siblings without opening any schema.

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

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

Clearly bounds the tool with negative guidance ('not a binary-file API,' 'does not parse CSV or JSON') and warns that raw append to .json can break it, plus lock-retry behavior. It stops short of explicitly contrasting with mailbox_file_write, which is the nearest alternative for the same resource.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses that the copy is server-side ('bytes are never downloaded or reuploaded') and that archived sources are usable. It does not say what happens when the destination path already exists (overwrite vs. error), which is the main behavioral unknown for a non-idempotent copy.

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

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

Two tight sentences with the core action and scope front-loaded, followed by the key constraint. 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?

With an output schema present, return values need no explanation, and the description covers action, source scope, and a usage constraint. The remaining gap is destination-collision behavior and the target_path vs. target_folder choice, minor but relevant for a mutating 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 every parameter is already documented, making 3 the baseline. The description adds only the 'storage reference' framing and the archived-source note; it does not clarify the relationship between target_path, target_folder, and target_mailbox_id, which is where an agent could mis-select inputs.

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

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

The description states a specific verb (copy) and resource (one existing file) plus the destination scope ('another path or mailbox') and source scope ('including archived sources'). 'Copy' inherently distinguishes it from the sibling mailbox_file_move, mailbox_file_write, and mailbox_file_rename without ambiguity.

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 precondition for correct use ('The target mailbox must be writable'), which tells the agent when this call will succeed. It stops short of naming alternatives or exclusion cases (e.g. use mailbox_file_move to relocate instead of duplicate), so it is clear context without routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds genuine behavioral context: this returns metadata only and does not download content, which is the key distinction from the read siblings.

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

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

Two sentences, front-loaded with the action and the metadata-only constraint, followed by the usage trigger. Zero filler.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description correctly covers the metadata-vs-content distinction and the source of the identifiers, leaving nothing an agent needs 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 the baseline is 3, but the description adds the meaningful precedence rule 'file_id (preferred) or path' that the schema does not state as explicitly. That ordering guidance is a real addition beyond the structured field descriptions.

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 ('Get full metadata for one mailbox file') and immediately differentiates from content-reading siblings with 'without downloading its content.' An agent can distinguish this from mailbox_file_read and mailbox_file_list without opening a schema.

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

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

Explicitly names when to use it: to expand the lean file_id/version_id returned by mailbox_file_write and mailbox_file_write_many. It gives a clear triggering condition but does not explicitly name the read-content alternative or state when NOT to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the default and hard cap of 100 results, and the requirement to use pagination.next_offset for subsequent pages. It does not state result ordering outside the folder case or any rate limits, keeping it below a 5.

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

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

Three compact sentences with zero filler, front-loaded on the primary verb and pagination constraint, then the disambiguating sibling reference. Every clause carries information the agent needs.

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

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

An output schema exists, so return values need not be explained, and the description still supplies the key pagination contract (next_offset). With a 7-parameter schema fully documented and required mailbox_id clear, the definition is close to complete; only the query+folder interaction and result ordering are 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 the schema already documents limit, query, folder, offset, account_id, and reason in detail. The description largely restates those semantics ('query searches file names/paths; folder lists immediate files') without adding format or edge-case detail 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 states a specific verb and resource ('List mailbox files') and immediately scopes it with pagination bounds. It also explicitly separates this tool from mailbox_email_list, so an agent can distinguish it from the closest sibling 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?

It tells the agent when to use this tool versus mailbox_email_list ('Use mailbox_email_list for received emails') and explains how to continue paging via pagination.next_offset. It lacks guidance on when to prefer mailbox_file_get or how query and folder interact when combined, so it falls 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 destructive=true and idempotent=false, but the description adds real value beyond them: same-mailbox moves create a rename revision, and cross-mailbox moves copy then soft-delete the source without reuploading bytes. The soft-delete detail tells the agent the source is recoverable, which the annotations alone do not convey.

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

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

Two sentences, no filler, with the core action stated first and the two move modes immediately following. Every clause earns its place.

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

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

For a destructive move tool with a full schema and an output schema, the description covers the essential behavioral distinction between move modes. It omits any mention of failure conditions (e.g., what happens if the destination exists) and does not clarify the relationship between target_path and target_folder, but the output schema and parameter docs carry most of the remaining load.

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 seven parameters are already documented in the schema, and the description adds no parameter-level detail. Its "storage reference" phrasing does not map cleanly onto the path/mailbox_id parameters, but it does not mislead about their use.

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 one file") and differentiates its behavior from siblings like mailbox_file_copy and mailbox_file_rename by explaining the revision/soft-delete semantics. The phrase "by storage reference" is slightly at odds with the path-based parameters, which muddies it a touch.

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 behavioral note about same-mailbox vs cross-mailbox handling implicitly helps an agent choose between move, copy, and rename, but the description never states when to prefer this tool over mailbox_file_copy, mailbox_file_rename, or mailbox_file_reorganize. Usage is implied rather than prescribed.

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, so the safety profile is covered. The description adds real context beyond that: a 750000-byte size ceiling, an untrusted-content/prompt-injection warning, and the binary-file exclusion. It does not say whether oversized files error or truncate, which is the one remaining behavioral gap.

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

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

Front-loaded verb+resource+scope, followed by alternatives, security note, and exclusion. Five short sentences, each carrying distinct information; nothing is 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?

Output schema exists so return values need not be explained. Purpose, size limit, sibling routing, security posture, and binary exclusion are all present, leaving nothing an agent needs in order to call this 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% and the schema already documents path, account_id, reason, and mailbox_id in detail. The description adds no parameter-level syntax or format guidance, 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 (Read) and resource (one text mailbox file) with explicit scope (HTML/CSS/JS/JSON/Markdown, up to 750000 bytes), and carves itself out from the email-specific siblings in the same sentence set.

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: 'For email, prefer mailbox_email_list and mailbox_email_get... and mailbox_email_download for attachments or original EML', plus a hard exclusion ('Not for binary files'). Both when-to-use and when-not-to-use are stated, with named alternatives.

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

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

Annotations declare the mutation and non-idempotent profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description is not carrying that burden. It does add genuinely useful behavior: the operation creates a rename revision without reuploading bytes, which tells the agent this is a cheap metadata-level change. It omits conflict behavior when new_path already exists and any lock prerequisites.

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

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

One dense sentence with the action and the key scoping constraint front-loaded, no filler or repetition. It is slightly overloaded by the unexplained 'by blob reference' clause, which costs a point but not 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. For a mutation tool with five parameters and lock-related siblings, the description still leaves open what happens on path collision and whether a lock must be held first, which is a meaningful gap for an agent invoking it.

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

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

Schema description coverage is 100%, so all five parameters, including path, new_path, account_id and reason, are already documented in the schema; baseline 3 applies. The description adds no syntax, format, or constraint detail beyond what the schema states, and its 'blob reference' wording actively muddies the path-based parameter model.

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 pair (rename or move) and a scoped resource (one same-mailbox file path), which an agent can act on directly. However, it never distinguishes itself from the close sibling mailbox_file_move, and the phrase 'by blob reference' is confusing since every parameter in the schema is a path string, not a blob handle.

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

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

The phrase 'same-mailbox' implies a boundary (no cross-mailbox moves), but there is no explicit when-to-use, when-not-to-use, or named alternative, despite mailbox_file_move and mailbox_file_copy being obvious candidates to route against. Guidance is left almost entirely to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuine extra context about the server-side, no-byte-transfer execution model, but says nothing about what a destructive batch operation overwrites, whether partial failures are possible, or how conflicting destinations are handled.

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

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

Two tight sentences with no filler; the core action is front-loaded and the execution-model caveat follows. 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?

An output schema exists, so return values need not be explained, and annotations cover the destructive/idempotency profile. However, for a batch destructive tool with ambiguous per-operation fields, the description omits any note on atomicity, overwrite behavior, or partial failure, leaving meaningful gaps 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%, so the baseline would be 3, and the description does contribute the key framing that inputs are server-side path/blob references rather than bytes. It does not, however, disambiguate the many overlapping operation fields (path/from_path/to_path/new_path/target_path/target_folder), which the schema itself handles only loosely.

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 set (batch rename, move, or copy) applied to a specific resource (files) and adds a distinguishing mechanism ('server-side path/blob references'). It is clear what the tool does, but it never names the single-file siblings (mailbox_file_copy, mailbox_file_move, mailbox_file_rename) that a confused agent could otherwise pick.

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 implied context ('Use for folder cleanup or reorganization'), which orients the agent toward bulk operations, but there is no explicit when-not guidance or reference to the individual rename/move/copy siblings. The agent must infer that this is the batch counterpart to those 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds meaningful behavior beyond them: writes are lock-aware and honor the revision token, and it flags the binary-file limitation, giving useful operational context.

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

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

Three short, front-loaded sentences with zero filler; the core action leads and the constraints follow.

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 full schema coverage, an output schema, and annotations, the description covers the key behavioral points an agent needs (lock and revision awareness, text-only scope). Only the overwrite/non-idempotent consequence of re-writing an existing path 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 the schema itself documents all 7 parameters including the revision-conflict behavior. The description only re-emphasizes the revision/lock interaction and adds no syntax or format detail the schema lacks, so this is the baseline 3.

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 text file to mailbox storage) and scopes it to text files, distinguishing it from binary-upload paths. It does not explicitly name sibling tools like mailbox_file_write_many or mailbox_file_append_text, so an agent must infer the boundary from the name alone.

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

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

Gives clear context ('Respect locks and expected_mailbox_revision_id') and an exclusion (use direct uploads or the CLI for binary files). It stops short of routing between write_many/append_text alternatives, which would be needed for a 5.

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

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

Annotations already declare destructiveHint=true, non-idempotency, and closed-world behavior. The description adds lock and revision concurrency guidance ('Respect locks and expected_mailbox_revision_id'), but it does not explain the deletion behavior of delete_missing or the precise destructive scope, so it adds only moderate context beyond the annotations.

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

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

Three short sentences, each carrying distinct information: purpose first, concurrency constraint second, and an alternative-tool pointer third. There is no filler, and the most important scoping information 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?

With a rich input schema, an output schema, and safety annotations, the description covers purpose, concurrency, and the main alternative for reorganization. It omits explicit warning about delete_missing, but that behavior is documented in the schema, so the definition is nearly complete for correct invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail. The description restates the batch nature and names the revision token, but adds no syntax, format, or constraint details beyond what the schema provides, making the baseline 3 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 uses a specific verb and resource: 'Write multiple text files to private mailbox storage.' The word 'multiple' clearly distinguishes this batch tool from the singular sibling mailbox_file_write, and the mention of path operations distinguishes it from reorganization tools.

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

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

It gives a clear alternative for one scenario: use path operations to reorganize existing files without rewriting bytes. However, it does not explicitly state when to choose this over mailbox_file_write for a single file, nor does it warn against use for binary files, leaving some selection guidance implied.

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

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

Annotations already establish this is a safe, idempotent read. The description adds genuine context beyond them: that include_email requires write access and that the tool reports archive/delete eligibility. It stops short of describing rate limits or pagination, but those are low-relevance for a single-resource getter.

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

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

Two tightly packed sentences with the return scope front-loaded and the routing guidance trailing. Every clause carries information; nothing is filler.

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

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

An output schema exists, so the description need not detail return values, and it still summarises the useful ones. For a read tool with full annotation and schema coverage this is sufficient, with only minor behavioral detail omitted.

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 baseline is 3. The description's claim that include_email=true exposes address and receiving state largely restates the schema's own note that it requires upload/write access and returns receiving/sending state, adding little that is not already structured.

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

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

States a specific verb (Get) and resource (mailbox) and enumerates exactly what is returned: details, current revision, email activity, and archive/delete eligibility. It also names the sibling tools that cover adjacent resources, so an agent can distinguish it without opening a schema.

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

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

Explicitly routes the agent to alternatives with conditions: mailbox_file_list for files, mailbox_email_list for messages, account_limits for quotas. It also flags the write-access prerequisite for include_email, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the scoping word 'visible' (only authorized mailboxes) and lists returned field categories, which is modest extra context, but says nothing about pagination, ordering, or result limits.

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

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

Two tight sentences with the listing scope front-loaded and the parameter hint second. No filler or redundancy.

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

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

An output schema exists, so return values need not be explained, and the description adequately conveys what is listed and the filter option. It omits any indication of how many mailboxes return or ordering, a minor gap for a 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 all three parameters (query, reason, account_id) are already documented in the schema. The description's 'filter by email address or ID' merely restates the query schema rather than adding format or matching details beyond it.

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

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

States a specific verb (list) and resource (visible storage mailboxes) plus the scoping qualifier 'visible' and the fields surfaced (incoming-email activity, archive/delete eligibility). This separates it implicitly from mailbox_get and mailbox_email_list, though no sibling is named explicitly.

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

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

The sentence 'Pass query to filter by email address or ID' gives a usage hint for one parameter but offers no when-to-use/when-not-to-use guidance and never names the alternative sibling (e.g., mailbox_get for a single mailbox). Usage is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation safety profile is covered. The description adds that the lock is for coordination ('so other agents can see this connector is working'), hinting at advisory semantics, but omits whether it is blocking, what happens on contention, permission requirements, and any expiry behavior tied to duration_seconds.

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

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

A single front-loaded sentence with no filler or repetition of structured fields. It is efficient, though arguably terse for a coordination tool with a related unlock sibling.

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

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

An output schema exists and annotations plus a fully-described schema carry much of the burden. Still, for a lock tool with a paired mailbox_unlock and a scoped sibling mailbox_lock_files, the description should clarify advisory-vs-blocking behavior and how the lock is released; that gap leaves it only minimally complete.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including reason, account_id, and duration_seconds. The description adds no parameter-level meaning, 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 ('Lock a whole mailbox') and scopes it to acquiring a lock rather than editing content. The qualifier 'whole mailbox' implicitly separates it from the sibling mailbox_lock_files, though it never names that alternative. The trailing coordination rationale is vague but does not obscure the core action.

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

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

Gives timing guidance ('before broad edits or uploads'), which implies when a lock is warranted versus narrower operations. However, it never names the alternatives (mailbox_lock_files for individual files, mailbox_unlock for release) or states when-not to use it, leaving the routing decision partly 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description usefully discloses that this is an advisory/coordination lock ("so other agents can see this connector is working"), but omits whether locks are enforced, expire, or conflict with existing locks.

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

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

A single front-loaded sentence with no padding, and it leads with the action and resource. The trailing clause about other agents is slightly wordy but carries real intent 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 6-parameter mutation that has both required and optional fields, the description is thin. An output schema exists so return values needn't be explained, but lock semantics (expiry, conflicts, enforcement) are left unaddressed despite being central to 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%, so every parameter (paths, reason, message, duration_seconds, etc.) is already documented in the schema. The description adds no parameter-level detail, 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 gives a clear verb+resource ("Lock one or more mailbox files") and states the reason (coordination between agents). It does not differentiate itself from the sibling mailbox_lock, so an agent must infer that this targets individual files rather than the whole mailbox.

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 timing cue ("before editing"), which is genuine usage context, but gives no guidance on when to prefer this over mailbox_lock, how long to hold the lock, or how it pairs with mailbox_unlock_file. Usage is implied rather than specified.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the useful state transition (archived -> active list) and scoping to a single mailbox, but says nothing about permissions, error behavior if the mailbox is not archived, or repeat-call effects.

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

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

A single front-loaded sentence with zero filler, appropriately sized for a simple state-change tool.

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

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

With an output schema present, annotations covering the safety profile, and full schema description coverage, the definition is nearly complete for a low-complexity mutation. It only lacks guidance on failure conditions (e.g., unarchiving a mailbox that is not archived) and the reason/account_id usage context that agents might want.

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 mailbox_id, account_id, and reason. The description only implies that exactly one mailbox is affected ('one archived mailbox'), which is a marginal addition over the required mailbox_id field.

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

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

States a specific verb (restore/unarchive) and resource (one archived mailbox), and the state transition target (active mailbox list) is explicit. It reads as the clear inverse of the sibling mailbox_archive, though it never names that sibling or otherwise distinguishes itself from it.

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

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

No guidance on when to use this versus alternatives, no prerequisites, and no mention of the corresponding mailbox_archive tool or the conditions under which an unarchive is appropriate. The usage context is only implied by the verb.

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

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

Annotations already declare the safety profile (write operation, idempotent, non-destructive), so the bar is lower. The description usefully adds the scope constraint that only connector-created locks can be released, but does not cover auth/permission needs or what happens to a lock not owned by this connector.

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

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

A single short sentence with zero filler, and the scope-limiting qualifier is included up front rather than 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?

An output schema exists so return values need not be described, and the schema carries the parameter detail. The description covers the essential behavioral constraint (connector-owned locks), leaving only minor gaps such as behavior on an unrecognized or already-unlocked mailbox.

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 fully documents mailbox_id, account_id, and reason, including the caveats about account inference and reason hygiene. The description adds nothing beyond the schema, which is the baseline-3 case.

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 (unlock) and resource (mailbox), and the qualifier 'locked by this MCP connector' distinguishes it from the file-oriented sibling mailbox_unlock_file. It is clear on its own, though it does not name the sibling explicitly.

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

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

The phrase 'locked by this MCP connector' implies the precondition for use (only locks this connector created can be released), but there is no explicit when-to-use/when-not guidance and no alternatives named among siblings like mailbox_unlock_file or mailbox_lock.

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

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

Annotations already declare the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description nonetheless adds a genuinely useful behavioral constraint not present in the structured data: only locks held by this MCP connector can be released, which tells the agent this call will not free another client's lock.

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

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

A single front-loaded sentence with no filler; the scope qualifier ('locked by this MCP connector') is attached directly to the action it modifies. Nothing in it is redundant with the name or title.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. What is missing is failure behavior — what happens when the file is not locked, or the lock belongs to another connector — which matters for a tool whose whole purpose is conditional on lock ownership.

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 a documented mailbox-relative path format and the optional reason/account_id semantics, so the schema carries the parameter burden. The description adds no syntax, format, or defaulting detail beyond what the schema already provides, making the baseline 3 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?

States a specific verb (Unlock) and resource (a mailbox file), which is clearly narrower than the sibling mailbox_unlock. However, it never names or contrasts with mailbox_unlock or mailbox_lock_files, so the agent must infer the distinction from the resource noun alone.

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

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

There is no explicit when-to-use statement, no prerequisites, and no reference to the alternative tools mailbox_unlock or mailbox_lock_files. The only implied constraint is that the lock must have been taken by this connector, which is stated as scope rather than as guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation nature is covered. The description adds nothing beyond that: it does not say whether metadata is replaced or merged, whether the operation can be undone, or any authorization requirement (only the schema's account_id field hints at that).

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

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

One short sentence with zero padding and the resource is front-loaded. It could be slightly more useful without being longer, but it wastes no words.

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

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

With a full output schema and complete parameter descriptions, most of the structured burden is carried elsewhere. Still, for a non-idempotent mutation tool the description omits update semantics (merge vs overwrite) and any usage framing, leaving real gaps for an agent deciding how to call it.

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

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

Schema description coverage is 100%, so the schema already documents mailbox_id, description, metadata, reason, and account_id in detail. The description names 'description' and 'metadata' but adds no format or merge-semantics detail beyond the schema, 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 clear verb (Update) and resource (mailbox) plus the specific mutable fields (description or metadata). It is distinguishable from mailbox_get/mailbox_list, but never names or contrasts with related siblings such as mailbox_archive or mailbox_create.

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

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

There is no when-to-use guidance, no preconditions, and no mention of alternatives among the many sibling tools. The agent must infer entirely from the name that this is the way to change mailbox-level descriptive fields.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context that annotations cannot express: the link requires normal user sign-in and 'grants no access', which correctly frames it as a navigation aid rather than a credentialed access token. It stops short of noting link expiry or scope limits.

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

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

Two short sentences with zero filler. The core purpose is front-loaded and the security clarification follows immediately where it is most useful.

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

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

With a 100%-covered schema, full annotations and an output schema, the description need not explain return values or parameter formats. It covers identity and security semantics adequately; the only shortfall is the absence of explicit routing guidance against sibling tools.

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

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

Schema description coverage is 100%, so reason, account_id and redirect_path are already documented in the schema, including the account-authorization caveat and example redirect paths. The description adds nothing about parameters, which is acceptable at this coverage level and matches the baseline of 3.

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

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

The description names a specific verb and resource: 'Return a stable dashboard link' and scopes it to 'mailboxes or connector access'. An agent immediately understands this produces a navigable URL rather than performing mailbox operations. It does not explicitly contrast itself with a sibling, but no sibling performs a comparable function, so differentiation is not a real gap.

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

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

There is no statement of when to call this versus alternatives such as revdoku_status, nor any preconditions or exclusions. 'For mailboxes or connector access' merely restates the resource rather than describing a triggering scenario, so usage is only weakly implied.

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

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

Goes well beyond the annotations: discloses that an email verification code is sent, that nothing is provisioned until verify succeeds, that tokens/codes/keys must stay in a private credential flow and out of chat or logs, and that retrying an uncertain signup is unsafe. The idempotentHint=false is corroborated with actionable 'do not retry' guidance.

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

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

Front-loaded with purpose, then constraints and security guidance, in five tight sentences with no filler. Slightly long, and the 'human's own email' instruction partly repeats the schema description, but each sentence carries operational value.

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

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

No output schema exists, yet the description implies a signup_token is returned and describes the two-step signup/verify lifecycle well enough to call the tool correctly. It stops short of describing the exact response payload, which is a minor gap rather than a blocker.

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 already documented in the schema, including the 'human owner's email, never an agent mailbox' constraint. The description reinforces the same point ('Supply the human's own email') but adds no new syntax, format, or edge-case detail. Baseline 3 for a fully documented 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 ('Create a Revdoku account') and immediately bounds the effect ('no account, mailbox or key is created until revdoku_signup_verify succeeds'). This distinguishes it cleanly from siblings revdoku_signup_verify and revdoku_signup_resend.

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 explicit routing: use this to sign up, existing users must instead sign in through OAuth, and do not automatically retry an uncertain signup. The prerequisite (human owner's authorization and own email) and the follow-up step (verify) are both named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them: the resend_after throttle window, the requirement to keep the token private, and the explicit negative side effects (no account creation, no expiry extension).

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

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

Three short sentences: the action first, then the token-handling constraint, then the explicit non-effects. No filler, and the most important routing information 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 one-parameter tool with no output schema and annotations that already cover the safety profile, this is nearly complete: it covers the action, the constraint, and the boundaries of the side effects. It does not say what the response looks like or what happens if the signup is no longer pending, which are minor gaps.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description adds a handling constraint for it ('Keep the signup token private') that the schema does not state, which is a genuine increment; the reference to 'resend_after seconds' as a non-schema value is mildly confusing but reads as server-side configuration.

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: resending an email verification code for a pending signup, scoped to a token. The closing clause ('Does not create an account or extend the signup expiry') implicitly distinguishes it from revdoku_signup and revdoku_signup_verify, though no sibling is named outright.

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

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

Usage is implied by 'pending signup' and the resend_after throttle, so an agent can infer this is for a signup that already exists but hasn't verified. However, no alternative tool is named and there is no explicit when-not guidance (e.g., what to do if the signup already expired or was verified).

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 the mutation profile (readOnly=false, idempotent=false, destructive=false); the description adds substantial non-obvious behavior — the one-time API key return, that repeats never return it again, that the key authorizes REST while hosted MCP tools still need OAuth, and that the key must be kept private.

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

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

Front-loaded with the core action, followed by the security and lifecycle caveats. Sentences are dense but each carries a distinct fact (key secrecy, REST vs OAuth scope, non-repeatability, existing-account exclusion), with only slight redundancy around the code-handling warning.

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

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

For a two-parameter mutation tool with no output schema, the description covers what is created, the one-time credential behavior, and channel restrictions. It does not address failure modes (invalid/expired code) or the resulting account state after creation, leaving minor gaps.

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

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

Schema description coverage is 100%: 'code' is documented as a six-digit email code and 'signup_token' as the token from revdoku_signup. The description reinforces where the code comes from but adds no syntax or format detail 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?

States a specific verb and resource: verify the emailed code and create the account, first mailbox, and scoped API key. This is clearly distinguishable from revdoku_signup, revdoku_signup_resend, and revdoku_status, which handle the surrounding flow rather than the verification step.

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 real routing guidance: 'Existing accounts require normal sign-in' tells the agent when not to call this, and 'Use a private application input for codes, not ordinary chat' specifies how to collect the code. It stops short of explicitly naming revdoku_signup or revdoku_signup_resend as the prerequisite/alternative 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that the response carries granted accounts, connector version and support guidance, and that account restrictions must be respected — useful, but no detail on failure modes or what 'support guidance' actually contains.

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

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

Four short sentences, front-loaded with the verb and the scope of what is checked, with no filler. The trailing sentences on restrictions and reconnecting are terse and slightly opaque, but they are not wasted.

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

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

An output schema exists, so return values need no explanation here, and both optional parameters are documented. For a low-complexity, read-only, two-optional-parameter status tool, the description covers what an agent needs; only the sibling-routing gap keeps it from full marks.

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%; both account_id and reason are fully documented in the schema, including the pointer to revdoku_status.accounts and the 'never infer from a mailbox id' rule. The description restates the account_id omission default but adds no syntax or format detail beyond the schema, 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?

'Check' + a concrete list of what is checked (email and file access, account identity, granted accounts, connector version) makes the purpose unambiguous. It is clearly distinguishable from the mailbox_* mutation siblings, though it never names account_get/account_list, which cover adjacent territory.

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 the key calling convention (pass account_id per call, omit to use the credential default) and one conditional remedy ('Reconnect if tools are missing'), which is genuine usage guidance. However it never states when to call this versus account_get or account_list, nor that this should be called first to discover valid account ids.

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