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

Annotations declare write-ish (readOnlyHint=false) but non-destructive behavior. The description adds genuinely useful context beyond that: the connection persists across subsequent calls, an app password is required rather than the account password, and list_email_providers explains how to obtain one. It doesn't cover auth failures, retry behavior, or what happens when reconnecting an already-connected account.

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 one-line purpose followed by compact per-argument notes; no filler sentences. The Args-style formatting is slightly verbose for three parameters but every line 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 the return value need not be detailed, and the description's 'returns a status message' is a reasonable pointer. For a stateful connection tool the description covers the essentials (persistence, credential type, provider source); only failure modes and reconnect semantics are missing.

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

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

Schema coverage is 0%, so the description carries the full burden, and it does: provider accepts either a known provider name (enumeration supplied, which the schema lacks) or a raw IMAP hostname with an example, email_address is the full sign-in address, and app_password is explicitly not the regular password. This is meaningful semantics the schema alone cannot provide.

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

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

States a specific verb and resource plus the transport ('Connect to an email inbox via IMAP'), which is enough to separate it from siblings like disconnect_email and connection_status. It stops short of explicitly contrasting with those siblings, but the action is unambiguous.

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

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

Implied usage: the note that 'the connection persists for subsequent tool calls' tells the agent this is a prerequisite for the read/search tools, and the app_password hint points to list_email_providers. There is no explicit when-not-to-use or a named alternative, so guidance remains inferred rather than stated.

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

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

Annotations already declare readOnlyHint, but the description adds real behavioral context beyond them: it performs a network NOOP and can re-open a closed socket, a side effect an agent would not infer from the annotation. No auth requirements or failure behavior are described.

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

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

Two short sentences, front-loaded with the primary purpose, and the second sentence exists solely to explain the non-obvious NOOP behavior. No filler.

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

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

An output schema exists, so return values need not be explained, and the description covers the essential behavior for a simple status check. It stops short of covering error/failure semantics, but the core is 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?

The tool takes zero parameters, so the schema is trivially complete and there is nothing for the description to compensate for. Baseline for a 0-param tool.

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

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

States a specific verb and resource ('Check whether an email connection is active') plus a secondary output ('report the server version'). Easily distinguished from siblings connect_email, disconnect_email, and the read/search 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?

Explains the motivating scenario clearly — using it so a silently-closed socket surfaces here rather than on the next search or read. It does not explicitly name an alternative tool or a when-not-to-use condition, so it falls just 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 readOnlyHint=false and destructiveHint=false, so the agent knows this mutates session state without being destructive. The description adds only the 'current' scoping detail; it does not say whether stored credentials or configuration are retained, or whether reconnection is required afterward.

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 waste, front-loading the action and the target resource. Nothing extraneous and nothing buried.

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

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

With no parameters, an output schema present, and annotations covering the safety profile, the description is nearly complete for this tool. The only gap is post-disconnect state (what happens to the connection/session), which is a minor omission.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to carry. Baseline of 4 applies.

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

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

States a specific verb (disconnect) and resource (the current email inbox), which is enough for an agent to distinguish it from connect_email or connection_status. It does not explicitly name the sibling tools it complements, so it stops short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no reference to alternatives such as connect_email or connection_status. The intent is inferable from the name alone, but the description provides no routing help.

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 readOnlyHint annotation already establishes this is a safe, side-effect-free read. The description adds that the output contains setup instructions and App Password guidance, but since an output schema exists, most return-content disclosure is already covered by structured data, leaving only modest added value.

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 the reason to call it first. Every phrase earns its place and nothing is repeated.

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-argument read-only listing tool with an output schema and annotation coverage, the description supplies everything an agent needs: what it returns and when to reach for it.

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

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

The tool takes zero parameters, which is the baseline-4 case. There is nothing for the description to clarify beyond what the empty schema already conveys.

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

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

States a specific verb and resource ('List supported email providers') plus what it returns ('their setup instructions'), so the agent knows exactly what this produces. It does not name a sibling for contrast, though 'Call this first' implicitly positions it before connect_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?

Gives clear sequencing guidance ('Call this first to show the user which providers are supported') and states the user-facing purpose (generating an App Password). There is no explicit when-not or named alternative, but for a zero-param informational tool the context is sufficient to disambiguate from connect_email/connection_status.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description usefully adds that the output is a folder-name vocabulary consumed by search/read tools. It says nothing about pagination, folder hierarchies, or error behavior for a disconnected mailbox.

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 followed immediately by why the agent cares about the result. 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-value details are out of scope, and a parameterless read-only tool needs little else. The one missing piece is how it relates to the sibling search_all_folders, which the agent must infer.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; nothing in the schema needs elaboration and the description correctly does not invent any.

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 all folders/labels in the connected mailbox'), and clarifies the returned values feed search_emails and read_email. It does not explicitly differentiate itself from the sibling search_all_folders, so it falls short of a 5.

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

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

The downstream hint ('names that can be passed to search_emails and read_email') implies a discovery use case, but there is no explicit when-to-use/when-not guidance and no mention of the likely alternative search_all_folders.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds useful behavior beyond that: the folder must match the search, the body is pulled from whichever part contains the order details, and a conditional hand-off to read_pdf_attachment. It does not mention pagination or error behavior, but the added context is meaningful.

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

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

Front-loads the purpose, then parameters, then return behavior in a compact block with no filler. The references to 'order details' and 'amount' are narrowly domain-specific and slightly muddy a generic email reader, but overall it is tight and well-ordered.

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 enumerated, yet the description still summarizes the returned fields and explains source-selection of the body. Combined with the annotation-carried safety profile, an agent has nearly 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 description coverage is 0%, so the description carries the burden and largely compensates: message_id is sourced from search_emails, and folder is described with the constraint that it 'must match the search' (beyond the schema's plain default of INBOX). Both parameters gain semantic meaning not present in the schema.

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

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

States a specific verb and resource ('Read the full content of a specific email') and implicitly differentiates from siblings by naming search_emails as the source of message_id and read_pdf_attachment as a follow-up. An agent can tell this is the single-message full-content reader, distinct from the search/list 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?

Explains how to obtain the input ('message_id from search_emails results') and gives an explicit conditional branch to an alternative tool ('if has_pdf is true and the body has no amount, call read_pdf_attachment'). It lacks an explicit when-not-to-use statement, but the routing guidance is concrete.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's burden is lighter. It adds modest behavioral context – that failures surface as 'an error message' and that the args must be sourced from prior tool results – but says nothing about size limits, scanned/image PDFs, or parsing behavior beyond the text return already covered by 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?

Front-loaded with purpose, then usage, then a compact Args block. Nothing is padded and each block is one to two lines.

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 readOnlyHint covering safety and an output schema covering return values, the description only needs to supply purpose, trigger, and parameter sourcing – all of which are present. An agent has everything required to call this tool correctly.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: every one of the three args is documented, and two of them name their provenance ('message ID from search_emails results', 'filename from read_email's attachments list'). This is meaningfully more than the bare schema property names.

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 + resource ('Extract the text of a PDF attachment') and grounds it with a concrete example ('an emailed receipt'). It implicitly differentiates from read_email by describing the extraction step, but never distinguishes itself from the sibling save_attachment, which also operates on attachments.

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 trigger condition: use this when read_email lists a PDF attachment but the body only says something like 'your receipt is attached'. That is a concrete when-to-use rule, though it gives no explicit when-not or alternative (e.g. when to use save_attachment instead).

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds that it writes to disk and that it returns the saved path or an error, but it omits meaningful write-side behavior: whether an existing file at save_path is overwritten, whether the directory must exist, and any permission requirements.

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

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

The purpose sentence is front-loaded and the Args list is compact and scannable, with no filler. The docs-style block is slightly longer than a prose alternative would be, but it earns its space given 0% schema coverage.

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 needn't detail return values (it still notes the path/error return), and annotations cover the safety profile. The main residual gap is write-behavior detail such as overwrite semantics, but the core inputs and provenance are 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 0%, so the description carries the parameter burden, and it does so by explaining all four params including the otherwise-undocumented 'folder' as 'the folder the message is in'. It adds provenance for message_id and filename, though it does not disclose the INBOX default for folder.

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 first sentence names a specific verb and resource ('Download an email attachment and save it to disk'), which cleanly distinguishes it from siblings like read_email and read_pdf_attachment that read rather than persist. An agent can select this tool without inspecting the schema.

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

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

The Args block embeds the workflow by stating where inputs come from — message_id 'from search_emails results' and filename 'from read_email's attachments list' — which tells the agent the prerequisite calls. However, it never states when to prefer this over read_pdf_attachment or any exclusion/prerequisite failure condition.

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 readOnlyHint=true, so the description carries the behavioral burden and does it well: it discloses the performance cost ('slower'), the return shape (grouped by folder), and partial-failure handling ('folders that could not be searched'). It does not mention any connection/auth prerequisite, which siblings like connect_email suggest may exist.

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

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

Four short sentences, each earning its place: scope, sibling differentiation, return shape, and performance tradeoff, with the scope constraint front-loaded. No redundancy or filler.

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

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

An output schema exists, so the description needn't explain return values, yet it usefully summarizes grouping and partial failures. The remaining gap is the absence of any prerequisite/auth or rate-limit context for a tool that fans out across every mailbox folder.

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

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

Schema description coverage is 0% across 6 parameters with only titles, so the description must compensate and mostly does not. 'Same parameters as search_emails' is a useful cross-reference but forces the agent to open another tool's schema; it gives no format or semantics for since_date/before_date, body_or_subject, or how limit_per_folder interacts with the per-folder grouping.

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 (search across ALL folders in the mailbox) and enumerates the folder scope (inbox, spam, trash, archive, custom). It explicitly distinguishes itself from the sibling search_emails by noting it runs the search in every folder rather than one.

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?

'Same parameters as search_emails but runs the search in every folder' names the alternative and the condition that selects this one. 'Slower but thorough' conveys the cost/benefit tradeoff, though it stops short of an explicit 'use search_emails when you know the folder' exclusion.

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?

readOnlyHint=true already establishes the safe-read profile, and the description adds genuinely useful context beyond it: default limit of 50 returned newest-first, the exact result fields ({id, date, from, subject}), and the follow-up path via read_email(). It does not discuss pagination beyond the limit or rate limits, keeping it short of a 5.

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

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

Front-loaded with the purpose sentence, then a scannable Args block, then the return shape and follow-up hint. The args block is long but earns its place given 0% schema coverage; only minor trimming would be possible without losing 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 7-parameter read tool with an output schema, the description covers the gaps that matter: folder discovery, date formats, result fields, and the read_email follow-up. The one missing piece is an explicit cross-reference to search_all_folders for cross-folder queries.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: every one of the 7 params is explained, including the folder default and example values, the YYYY-MM-DD date formats, and limit's default and ordering. This fully compensates for the empty schema 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 and resource ('Search for emails in a folder') and scopes it to a single folder, which implicitly contrasts with the sibling search_all_folders. However, it never names that sibling, so the distinction is left for the agent to infer from names alone.

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

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

Gives concrete routing context: directs to list_folders() to discover folders and to read_email() with the id for full content. It does not explicitly state when to prefer search_all_folders over this single-folder tool, so the alternative is only implied.

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