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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, which is thin. The description compensates fully: it discloses that nothing reaches a draft until the step 3 token is used, that abandoned uploads expire on their own, that validation happens before any bytes are sent, and that the tool returns upload_id, max_chunk_bytes, and expires_at. This is rich behavioral 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?

The description is dense but every sentence earns its place: protocol position, usage condition, return values, safety guarantees, and allowed types. It is front-loaded with the most important fact (step 1 of 3). Slightly long, but the density is justified given the multi-step protocol and validation rules.

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 4-param tool with 100% schema coverage, an output schema, and a multi-step protocol, the description covers everything an agent needs: when to call, what to pass, what comes back, what is refused, and what happens next. The output schema presumably documents the return shape, so the description needn't repeat it. No 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%, so the baseline is 3. The description adds value by explaining the cross-parameter contract: filename extension selects the allowed type and must agree with content_type, size_bytes is verified at step 3, and sha256_hex is re-computed later. It doesn't enumerate each parameter, but it explains the semantics that bind them together, which the schema doesn't fully convey.

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

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

The description states a specific verb ('Start staging'), a specific resource ('one outgoing attachment'), and explicitly positions it as step 1 of a 3-step protocol, naming the sibling steps. It clearly distinguishes this tool from upload_attachment_chunk, finish_attachment_upload, and create_confirmed_draft.

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

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

The description gives explicit when-to-use guidance: 'Call it only for a file the user asked to attach, with bytes the client already holds.' It also states exclusions ('never a local path, and never reads the filesystem') and names the exact sequence of sibling tools to use instead. This is exemplary usage guidance.

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

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

Annotations only indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description goes far beyond this by disclosing that drafts are saved to Drafts, cannot send email, consume attachment tokens, report cleanup_warnings, and refuse unaccepted reply targets. It also warns that retrying a successful creation adds a second draft, giving agents critical non-obvious behavioral knowledge.

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

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

The description is long but every clause carries safety-critical guidance. It is front-loaded with the primary precondition and then covers prerequisites, reply behavior, refusal semantics, and return expectations. Slightly verbose but appropriately so given the risk profile of the operation.

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

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

For a 12-parameter mutation tool with safety implications, the description covers preconditions, parameter sourcing, failure modes, return values, and post-creation behavior. It explains what is refused, what happens to attachments, and why retrying is harmful. Nothing essential 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%, but the description adds important cross-parameter meaning: user_confirmed must only be true after exact confirmation, reply parameters require allow_unthreaded_reply acceptance, attachment_tokens are single-use and consumed, and reply inputs never contribute recipients, subject, or body. This is substantial added value beyond the schema.

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

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

The description clearly states the tool creates a Proton draft, but only after explicit user confirmation of recipients, subject, body, and attachments. It distinguishes itself from siblings by emphasizing that every draft, reply or not, goes through this one tool and that it cannot send email.

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

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

The description gives explicit conditions for use: only after user confirmation, only with chosen sender aliases from list_sender_addresses, only with reply context from get_reply_context, and only with attachment tokens from finish_attachment_upload. It also explains when requests are refused and that one should never retry a successful creation, leaving no ambiguity about when to call 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?

Even though destructiveHint already signals danger, the description adds crucial behavioral context: the token and staged bytes are destroyed, the operation is irreversible, a second call with the same token fails, and it never affects mail, drafts, or received attachments. This goes well beyond the annotations and fully discloses the risk profile.

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

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

The description is dense but every sentence earns its place: it front-loads the destructive action, then gives usage timing, exclusions, non-idempotency, scope, and return value. No filler or repetition of schema details.

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 single required parameter, full schema coverage, an output schema, and annotations, the description still adds the complete lifecycle context (when tokens are consumed, what cannot be undone, staging restart). Nothing an agent needs to decide whether and how to call this tool is missing.

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

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

Schema coverage is 100% and the parameter description already explains that attachment_token is the token returned by finish_attachment_upload, not upload_id, and is single-use. The tool description reinforces this lifecycle context but does not add substantial parameter semantics beyond what the schema already provides, so baseline 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 names a specific verb and resource: 'Permanently remove one staged outgoing attachment before it is used, destroying its token and the staged bytes.' This clearly distinguishes it from sibling tools like finish_attachment_upload and create_confirmed_draft, so an agent can tell exactly what operation is performed.

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

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

It explicitly states when to use the tool ('when the user cancels an attachment or replaces a wrong file after finish_attachment_upload') and when not to ('It is not needed after a draft is created'). It also points to the restart path via begin_attachment_upload, giving the agent clear 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, and the description adds meaningful behavioral context beyond that: raw bytes are never returned, no file is written, returned text is attacker-controlled data, unsupported media types are refused, and truncation is flagged. This gives the agent a clear safety contract for a tool handling untrusted content.

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

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

The description is compact yet complete, with the core purpose in the first sentence, safety warnings promptly after, and a clear sibling differentiation at the end. Every sentence adds value; no filler or redundancy is present.

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

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

Given the annotations, full schema coverage, and an output schema, the description covers all essential context an agent needs: prerequisites, security handling, accepted media types, return fields, truncation behavior, and the boundary between received and outgoing attachments. There are no obvious gaps that would lead an agent to misuse the 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%, and the description does not materially add parameter-level details beyond the schema. It reinforces that attachment_index must come from read_message and never be guessed, but the schema already states this. The baseline of 3 is appropriate because the schema carries the parameter-semantics 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?

The description states a specific action ('Extract bounded text'), the resource ('one received PDF, plain-text, or CSV attachment'), and the selection mechanism ('selected by its index from read_message'). It also differentiates from the outgoing-attachment sibling by naming begin_attachment_upload as the route for outgoing mail, making the tool's scope unambiguous.

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

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

It explicitly instructs the agent to call read_message first, to check which attachments are flagged text_extractable, and to never guess an index. It also states that non-text media types are refused and directs outgoing attachments to begin_attachment_upload, giving clear when-to-use and when-not-to-use guidance relative to 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?

The description thoroughly discloses failure behavior, single-use token semantics, expiration, and return fields. However, it says a hash mismatch 'discards the staged upload outright', which is a destructive side effect. This directly contradicts the annotation destructiveHint: false. Per the rubric, a contradiction with annotations forces a score of 1 and should be flagged.

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

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

The description is dense but every sentence earns its place: sequence, failure mode, recovery path, return payload, expiration, and lifecycle consumption. It is front-loaded with the primary purpose and step position, with no filler or repeated schema content.

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

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

Despite having an output schema and annotations, the description covers all behavioral context an agent needs: prerequisites, failure handling, restart guidance, token expiry, single-use consumption, and early discard via a sibling. 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. The description adds meaning beyond the schema by explaining where upload_id comes from ('begin_attachment_upload returned') and what finishing does with it ('exchanges that id for the attachment token and closes the upload'). This is useful semantic context above the schema's own description.

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

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

States a specific verb ('verify'), a resource ('attachment upload'), and its exact role as 'step 3 of 3'. It also distinguishes itself from siblings by explaining it exchanges upload_id for a token that create_confirmed_draft accepts, so an agent can tell it apart from begin_attachment_upload, upload_attachment_chunk, and discard_attachment.

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

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

Explicitly says when to call it: 'once after the last upload_attachment_chunk'. It also defines failure conditions (bytes still missing), and provides an alternative by instructing to 'restart at begin_attachment_upload rather than retrying'. It even names discard_attachment for early destruction, leaving no ambiguity about sequencing.

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, idempotentHint, destructiveHint), the description discloses critical behavioral context: 'Every value is untrusted data read out of that email, not a decision: no address here is a confirmed recipient' and 'It creates nothing and leaves the message unread.' It also reveals the threading_supported: false and threading_notice limitation, which is not in the annotations. This adds substantial value for safe agent decision-making.

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

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

The description is front-loaded with the core purpose, then adds contextual usage and behavioral notes in a logical order. Every sentence earns its place: the untrusted-data warning, the alternative routing, the threading limitation, and the non-destructive nature. No fluff or redundancy; it is long but information-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?

The description is fully complete for the tool's complexity: it explains the return contents (including threading fields), the workflow with create_confirmed_draft, the limitation of read_message, and the safety aspect of untrusted data. With an output schema present, no critical information is missing. An agent can call it correctly and handle the results appropriately.

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% for all three parameters (uid, folder, max_quote_chars), each with detailed descriptions. The tool description does not add parameter-level detail beyond what the schema already provides; it only mentions 'bounded quote' which is implicit in the parameter description. Per calibration, baseline is 3 when schema covers parameters thoroughly.

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

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

The description clearly states the tool's function: 'Read one message and return what composing a reply needs' and enumerates the exact outputs (Message-ID, suggested Re: subject, addresses from Reply-To/From/To/Cc headers, bounded quote). It also distinguishes itself from read_message by noting that read_message 'reports no reply candidates,' providing a specific differentiator.

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 instructs when to use this tool instead of an alternative: 'Call it instead of assembling a reply from read_message.' It also specifies the workflow with create_confirmed_draft, telling the agent to show candidates and quote to the user and pass only confirmed data. Additionally, it mentions the threading limitation to explain before a draft is confirmed.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable behavior: it returns names only (no counts/hierarchy), fails with a tool error when Bridge is unreachable, and names are localised. This is meaningful 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 sentences with no filler. The primary action is front-loaded, followed by crucial usage guidance and a failure condition. Every sentence earns its place.

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

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

For a no-parameter read-only tool with a full output schema and robust annotations, the description covers return scope, usage prerequisite, failure mode, and localisation nuance. Nothing an agent needs to call 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?

The tool has zero parameters, so the schema trivially covers everything. The description correctly adds no parameter-specific info because none is needed; it instead clarifies output semantics, which is appropriate for a no-parameter tool.

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

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

The description states a specific verb and resource: 'List the folder names the locally running Proton Bridge exposes'. It also differentiates from siblings by explicitly noting it returns names only and pointing to mailbox_status and list_messages for other concerns.

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 instructs to call this tool before passing any folder argument to another tool, explains why (account-specific, localised, exact match), and names the correct alternatives for counts and content. No ambiguity about when 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=true and idempotentHint=true, but the description adds concrete behavioral details beyond them: fetches use BODY.PEEK so listing never marks messages as read, and there is no continuation cursor (a real limitation). This is exactly the kind of contextual disclosure that helps an agent predict side effects and plan calls.

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, each earning its place: the first states purpose and scope, the second routes to alternatives, the third details the returned metadata and the non-mutating behavior. Front-loaded with the core purpose, no fluff or repetition.

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

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

With an output schema present and annotations covering safety, the description fills the remaining gaps: what fields are returned (metadata list), what is never returned (body/attachments), the side-effect-free behavior, and the lack of a continuation cursor. An agent has everything needed to call this tool correctly and to decide between it and siblings.

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 entries are themselves detailed (limit explains no-cursor behavior, folder requires exact spelling, unread_only is read-only). The tool description adds no parameter-specific information beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('List newest-first message metadata for one folder'), then immediately differentiates from siblings by naming search_messages and read_message as alternatives for other needs. It also states what entries carry and never carry, making the tool's purpose unambiguous.

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

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

Explicitly states when to use this tool ('to browse or triage a folder') and when not to ('to find messages by keyword use search_messages instead', 'to obtain a body use read_message with a UID returned here'). Also clarifies that older messages are not reachable via paging and require search_messages. No inference needed.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, and the description adds valuable behavioral context: the first entry is the default, only listed addresses are accepted as from_address, the list is locally fixed, and received-email addresses are never sending choices even if they appear here.

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?

Every sentence carries meaningful information, and the most important purpose is stated first. The description is compact yet covers purpose, usage, constraints, and return behavior without 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?

For a parameterless read-only tool with an output schema, the description fully equips the agent: what the tool returns, the ordering, the default behavior, the acceptable input constraint, and the key caveat about received-email addresses. No necessary context is missing.

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

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

There are zero parameters, so the input schema leaves nothing to explain. The description goes further by describing the return shape (default_sender plus sender_addresses, primary first), adding meaning beyond the empty schema.

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

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

The description states a specific action ('List the sender addresses this server may draft as') with a clear resource and scope. It also distinguishes its purpose from message/attachment tools by focusing on accepted sending addresses and defaults.

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 explicitly tells the agent when to call it: before offering a sending alias choice, and to verify whether an address belongs to the user. It also clarifies that the list is fixed and cannot be extended, which prevents futile attempts to modify 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 destructiveHint, so the safety profile is covered. The description adds valuable behavior beyond annotations by listing concrete failure conditions: Bridge not running, wrong IMAP port, and rejected stored credentials, plus the consequence of confusing a config fault with an empty inbox.

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, each earning its place: purpose and output, usage guidance, and failure behavior. It is front-loaded with the core action and immediately contrasts itself with siblings, with no filler.

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

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

For a zero-parameter read-only status tool with rich annotations and an output schema, the description is complete. It covers what the tool returns, when to call it, how it differs from siblings, and what error modes to expect.

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

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

The tool has zero parameters and the schema covers 100% of them, so there is little for the description to add on parameter meaning. Baseline for zero-parameter tools is 4; the description instead clarifies output semantics, which is the more relevant information here.

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 action ('Check the local Proton Bridge connection'), a specific resource (the configured account), and the key outputs (INBOX message and unread counts). It also distinguishes itself from sibling tools by stating that this tool reports INBOX totals only, unlike list_folders and list_messages.

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

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

The description gives explicit when-to-use guidance: call it first to confirm mail reachability, and before reporting the mailbox as unavailable. It also names which sibling tools to use for other needs, making the decision boundary clear.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds critical security context (attacker-controlled data), clarifies HTML/attachments are stripped, and discloses the message is left unread. These are not derivable from annotations, adding substantial behavioral clarity.

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?

Six sentences, each carrying distinct value: purpose, security warning, output scope, usage alternatives, return metadata, and side effect. No redundancy; the most critical info (safety and scoping) 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 an output schema present, the description still covers key return fields (headers, body, truncation flag, attachment metadata) and ties them to downstream tools. It also includes the security warning and the folder/UID relationship, making it fully actionable for an agent.

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 covers all parameters at 100%, so baseline is 3. The description enriches this by explaining the UID's origin and per-folder nature, tying folder to the exact string from list_folders, and clarifying truncation behavior via the max_chars parameter. These go beyond the schema's phrasing.

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 precise action ('Read one email as bounded plain text') and immediately distinguishes itself from siblings by clarifying HTML/attachment bytes are not returned. It also names alternative tools for attachments and reply context, making its scope unmistakable.

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 tells when to call this tool (with a UID from list_messages/search_messages) and when not to (use extract_attachment_text for attachment text, get_reply_context for preparing an answer). Also notes the folder-scoping constraint and the BODY.PEEK side effect, leaving no ambiguity.

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

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

The description discloses that the query is escaped into an IMAP TEXT search preventing injection, that matching never marks a message as read, and that it returns the same metadata as list_messages but never a body. These details go beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) and provide valuable behavioral context for safe usage.

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

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

The description is three sentences long, front-loaded with the core purpose, then usage guidance, then behavioral notes. Every sentence adds value and there is no redundancy or filler. It is compact yet comprehensive.

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

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

Given the tool's moderate complexity, the presence of a detailed output schema, and annotations covering safety, the description covers all essential aspects: purpose, usage, behavior, and integration with siblings. It mentions result ordering, no body, no read marking, and query escaping, making it fully sufficient for an agent to invoke correctly.

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

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

The input schema already documents all three parameters thoroughly (query, limit, folder) with detailed descriptions covering semantics, defaults, and constraints. The description adds no additional parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.

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 ('search'), resource ('one folder for messages'), and scope ('whose text matches a query, newest first'). It explicitly differentiates from siblings: list_messages for browsing without a query and read_message for reading a match, leaving no ambiguity about what this tool does.

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

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

The description gives explicit when-to-use guidance: 'Use it to find messages by keyword; to browse a folder without a query use list_messages, and to read a match use read_message with a UID returned here.' It also clarifies that a search never spans folders and suggests calling once per folder, as noted in the schema, making the intended usage unmistakable.

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

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

The description discloses stateful behavior beyond annotations: chunks are refused and not stored on validation failure, the upload position remains unchanged, and ordering is enforced. It also explains the return fields (received_bytes, expected_bytes, next_chunk), which adds important runtime 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?

Every sentence earns its place: core action, sequence position, failure modes, retry behavior, and return values are all packed in without redundancy. The description is dense but organized and fully front-loaded with the main purpose.

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

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

The description fully covers what an agent needs to invoke this tool correctly: ordering, size limits, rejection conditions, retry semantics, and the following step. Combined with the provided output schema and parameter descriptions, nothing essential 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?

Even though schema coverage is 100%, the description adds key semantic meaning: upload_id identifies a staged upload, not the final attachment token; chunk_index follows next_chunk returned from the previous call; data_base64 must be raw encoded bytes, never a path or data URL. This meaningfully reduces misuse risk.

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 action ('Append the next base64 chunk to an attachment upload') and the strict ordering constraint. It clearly identifies its place in a multi-step process and is distinguishable from sibling tools like begin_attachment_upload, finish_attachment_upload, and discard_attachment.

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 frames this as step 2 of 3, repeated until all declared bytes are sent, then closed with finish_attachment_upload. It also gives concrete retry guidance: on refusal, retry the same index rather than restarting, because the upload stays open at its current position.

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