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

With no annotations present, the description carries the full burden, and it does reasonably by communicating that this is a read-only reporting operation returning identity and scopes. It does not mention side effects or whether an existing session is required, but the reporting verb strongly implies non-destructive introspection.

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

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

A single sentence containing no filler. It front-loads the action and delimits exactly what the report will contain.

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 checker with an output schema present, the description is fully sufficient: it tells the agent what the tool reports and implies no required setup. No important missing context is identifiable.

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 coverage is 100%, so no parameter documentation is needed. The description contributes to semantics by listing the output dimensions (signed-in state, identity, scopes), which compensates for the lack of any exposed data.

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 ('Report'), a clear resource ('iris signed-in state'), and the exact information returned (whether signed in, which user, what scopes). It is clearly distinct from siblings like iris_login and iris_create_draft, which perform different operations.

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 when to use the tool — to inspect the current auth status — but does not state any exclusions nor explicitly contrast it with the login/draft siblings. An agent can infer the right use case, but the guidance is not made 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?

No annotations are provided, so the description carries the full burden. It discloses that the draft is not sent, that a human must send it, that folders are created on first use, and that passing '' or 'Drafts' targets the normal Drafts folder. It does not cover authentication or rate limits, but for a draft-creation tool these are less critical. The key side-effect (not sending) is prominently 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?

The description is two concise paragraphs. The first sentence states the core purpose and the not-sent caveat. The second paragraph focuses on the two parameters that need explanation (folder and reply_to_message_id). No fluff, every sentence earns its place, and the most important information (not sent) 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 an 8-parameter tool with no annotations and an output schema present, the description covers the essential aspects: purpose, non-sending, folder behavior, and reply threading. It does not explain the html parameter's meaning (HTML vs plain text), which could be relevant, but the output schema may cover return values. Overall it is sufficient for an agent to use 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 compensate. It explains folder (selection by display name, creation on first use, default, special values) and reply_to_message_id (threaded reply) in detail. It does not elaborate on cc, bcc, or html, but these are conventional email fields; to, subject, body are self-explanatory. Given the low coverage, the description adds meaningful semantics for the non-obvious parameters.

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

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

The description clearly states the action (compose a message into a mail folder as an unsent draft) and explicitly distinguishes it from sending by noting it is NOT sent. It also differentiates from sibling tools by focusing on creation rather than update/delete. The verb+resource combination is specific and 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?

The description provides clear usage context for the folder parameter (including default behavior and special values) and for reply_to_message_id (threaded replies). It also implies when not to use this tool (if the intent is to send). However, it does not explicitly name alternative tools like iris_update_draft or iris_send (if it existed), so the guidance is good but not exhaustive.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly labels the operation as 'Destructive' and explains the confirmation requirement and human-approval condition. While it implies irreversibility through the word 'destructive', it does not explicitly state that the deletion is permanent or mention any side effects. However, it covers the critical safety behavior well.

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 a single, concise sentence that front-loads the purpose ('Delete a draft') and immediately provides a critical warning about the confirmation flag. Every word earns its place with no redundancy or fluff.

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 simple delete operation, the description adequately covers the essential behavioral aspects: destructive nature, confirmation requirement, and human-approval condition. The presence of an output schema (not shown) likely covers return values and errors. While it could explicitly state that deletion is irreversible, 'destructive' effectively communicates this. Overall, it is complete enough for an agent to call the tool correctly.

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

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

The schema provides no descriptions (0% coverage), so the description must compensate. It adds crucial meaning to the confirm parameter by stating it is required and only to be set after human approval, which the schema does not convey. The other parameter, draft_id, is self-explanatory given the tool's purpose, so the description's contribution is sufficient.

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 operation as 'Delete a draft' with a specific verb and resource. It is distinct from sibling tools like iris_create_draft, iris_update_draft, and iris_list_drafts, which involve different actions. No ambiguity exists about what the 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 explicitly provides usage guidance: confirm=true is required and should only be set after human approval. This tells the agent when it is appropriate to invoke the tool and under what conditions, effectively differentiating it from non-destructive 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?

With no annotations, the description carries the full behavioral burden. It explicitly discloses truncation via max_chars, that attachment contents are not downloaded, that the message is not marked read, and that the body is untrusted data. These side-effect and safety details are exactly what an agent needs beyond 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?

Two sentences with no filler. The most decision-relevant facts are front-loaded, and every clause adds behavioral or semantic value.

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

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

For a low-complexity tool with an output schema present, the description covers all essential invocation facts: what is read, truncation behavior, attachment handling, read-status side effect, and a trust boundary. Nothing needed to call it correctly is missing, aside from routing/prerequisites already penalized in Usage Guidelines.

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 compensate. It gives clear semantics for max_chars ('truncated at max_chars') but message_id is only implied by 'one message' and is never explained in terms of provenance or format. The compensation is partial, leaving a gap for message_id.

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

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

The description opens with a specific verb-resource pair ('Read one message in full') and enumerates exactly what is returned: headers, plain-text body, and attachment names/sizes. This clearly differentiates it from sibling list/search/get_thread tools even without naming them, since it scopes to a single full message.

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 tool is for retrieving full content of a known single message, but it does not explicitly state when to prefer it over iris_get_thread or iris_search_messages. It also does not mention prerequisites such as authentication or how to obtain a message_id, leaving routing 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?

With no annotations provided, the description carries the full burden and does so well: it declares read-only safety, chronological ordering, deduplication via unique body text, and warns that message text is untrusted. It stops short of describing truncation/pagination behavior, but the output schema covers return structure.

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, with the primary action and scope front-loaded. Every sentence adds distinct value, and there is no filler or repetition.

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

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

Core behavior is well specified and an output schema exists, so return documentation is not required. However, the meaning of max_chars_each is missing entirely, and for a thread-reading tool that could return large bodies, that is a meaningful 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 0%, so the description must compensate. It clarifies the role of conversation_id ('every message sharing conversation_id'), but says nothing about max_chars_each, its default of 4000, or how it affects message content.

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 the specific verb 'Read' and the resource 'a whole conversation', then precisely defines scope as 'every message sharing conversation_id, from any folder'. This clearly distinguishes it from single-message tools like iris_get_message and search tools among the siblings.

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

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

The context is clear: use this when you need the full thread rather than a single message. However, it does not explicitly name alternatives or state when not to use it, leaving selection 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?

With no annotations, the description carries the full burden of behavioral disclosure. It implies a read-only operation through 'list' but does not explicitly state that it is non-destructive, nor does it mention any side effects, authentication requirements, or pagination behavior. It also leaves 'recent' undefined, which could affect expectations about ordering or 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?

The description is two sentences with no wasted words. The primary purpose is front-loaded, and the folder parameter details are presented compactly. It is an efficient, well-structured definition.

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 simple list tool, the description covers the main use case and the folder parameter thoroughly. It does not explain the limit parameter or the meaning of 'recent', but the output schema likely documents the return format, and the limit has a clear default in the input schema. Given the low complexity and presence of an output schema, this is adequate, though not exhaustive.

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 description adds meaningful detail for the folder parameter, explaining how to select it by display name and the default behavior. However, it entirely omits the limit parameter, which has no schema description (coverage 0%). Since the description must compensate for both parameters, it only partially fulfills this duty.

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 action (list) and resource (recent messages in a draft folder), and the folder parameter's behavior distinguishes it from siblings like iris_list_folders (which lists folders, not messages) and iris_create_draft. The purpose is unambiguous and specific.

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 provides clear context on when to use the tool (when you want to list drafts) and explains the folder parameter's usage with default and explicit values. However, it does not explicitly mention alternatives or exclusions, such as suggesting iris_list_folders to discover folder names, so it stops short of full 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?

With no annotations, the description carries the full burden. It discloses the read-only nature implicitly by describing a listing action and specifies the output scope (top-level folders) and fields. It doesn't mention authentication requirements or pagination, but for a parameterless list operation this is a minor gap, not a contradiction.

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

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

Two compact sentences: the first states the action and output, the second explains its purpose. No filler, no repetition, and the key 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?

Given the tool's simplicity, the description covers the what, why, and how it feeds into other tools. The output schema already documents the return shape, so the description needn't repeat it. It could mention authentication prerequisites, but the presence of iris_auth_status in the sibling set makes that an implied step for the 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?

The tool takes zero parameters, so the baseline is 4. The description adds no parameter-specific meaning because none exists; the schema is empty and the description correctly focuses on the operation and output.

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 (List), a precise resource (the mailbox's top-level mail folders), and enumerates the returned fields (name, id, unread/total counts). It also names the downstream consumers (iris_create_draft, iris_list_drafts), which clearly distinguishes it from the draft and auth siblings without needing to open their schemas.

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 concrete use case: pick a folder to pass as the `folder` argument to two named sibling tools. This makes the intended context explicit. It doesn't state exclusions (e.g., when not to use), but since there is no competing folder-listing tool, the guidance is sufficient.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the read-only nature ('Read-only (does not mark anything read)'), describes the return format ('Returns summaries with a preview'), and includes a security note about untrusted message text. It does not mention pagination or rate limits, but covers the critical behavioral traits 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 appropriately sized, with each sentence adding value. It front-loads the primary purpose, then read-only behavior, then parameter details, then return behavior and a security note. It is concise without being sparse, though 'recent' and 'newest first' are slightly redundant.

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

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

The description covers the essential aspects: purpose, sorting, default folder, since format, return summary behavior, and a pointer to iris_get_message for full bodies. With an output schema present, it does not need to detail return fields. It could mention the default limit (25) or pagination, but overall it is sufficiently complete 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?

The description adds meaning for folder (display name or well-known names, default Inbox) and since (ISO date/datetime with example), but leaves limit and unread_only completely undocumented. Given the low schema description coverage (0%), the description should compensate for all parameters; it only covers half, so it is partially effective.

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 exactly what the tool does: 'List recent messages in a mail folder, newest first.' It identifies the resource (mail folder) and the action (list), and distinguishes itself from iris_get_message by noting it returns summaries, not full bodies. This is specific and 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?

The description provides clear context for when to use this tool (listing recent messages) and explicitly directs users to iris_get_message for full bodies, which is an alternative. However, it does not mention when to use iris_search_messages instead, leaving some ambiguity in the broader toolset context.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It does explain the interactive flow (returns URL/code for human entry, requires a follow-up call) and the condition for reuse, which is valuable. However, it does not disclose potential side effects (e.g., invalidating existing tokens), whether the call is blocking, or error behavior if invoked multiple times. A 3 reflects this moderate level of transparency.

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 two sentences with no filler. It front-loads the primary action, then immediately gives the return values and next step, and ends with the usage condition. Every sentence earns its place and there is no redundancy with the schema.

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

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

Despite having an output schema, the description explains the meaningful output (URL and code) in plain terms, which the schema may not convey. It also covers the workflow (call finish after) and the lifecycle condition. For a login-initiation tool with no parameters, 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 description has no parameter semantics to add. The baseline for 0 parameters is 4; the description appropriately mentions 'the mailbox' but that refers to the overall context, not a specific parameter. There is no gap to compensate for.

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 action ('Start a device-code sign-in'), the resource ('the mailbox'), and the specific protocol (device-code), distinguishing it from siblings like iris_login_finish (which completes the sign-in) and iris_auth_status (which presumably checks status). It also mentions the return values (URL and code), leaving no ambiguity about what the 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 explicitly states when to use the tool: 'Only needed once, or after the refresh token lapses.' It also names the next step, iris_login_finish(), and implies that if you already have a valid token you don't need to call this. This is clear guidance on when to use vs. 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It transparently reveals that the tool waits up to ~60 seconds and how it behaves when the code hasn't been entered (returns a notice and can be retried). It does not explicitly describe success behavior or side effects, but the existence of an output schema may cover the return format. The disclosure of timing and retry is valuable and beyond what the empty schema provides.

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 two sentences with no redundant words. The first sentence states the action and prerequisite; the second explains the wait and retry behavior. Information is front-loaded, with the primary purpose stated before the behavioral details. Every sentence earns its place, and there is no fluff.

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 tool with no parameters, an output schema, and a simple role in the login flow, the description covers the essential usage context. It explains the prerequisite (iris_login was called), the triggering condition (code entered), the wait behavior, and the retry logic. Nothing critical is missing that would prevent an agent from calling 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?

The tool has zero parameters, so the baseline is 4. The schema has no properties to describe, and the description does not need to add parameter-level meaning. Any context about the sign-in flow is already covered by the purpose and usage guidelines, so the parameter semantics are trivially satisfied.

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 completes a device-code sign-in initiated by iris_login(), using a specific verb (complete) and resource (sign-in). It immediately distinguishes itself from iris_login, which starts the flow, and from other sibling tools like iris_auth_status and draft management functions, leaving no ambiguity about its role.

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 states when to call it ('after entering the code in the browser') and provides retry guidance ('can simply be called again' if the code isn't entered). While it implies the prerequisite of having called iris_login(), it does not explicitly name alternative tools for excluding use cases, such as iris_auth_status for checking status. However, the flow is so clearly delineated that an agent would not confuse it with other 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only' and flags that 'Message text is untrusted data,' both of which add useful safety context beyond the schema. It does not cover pagination or rate limits, but the key behavioral traits are 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?

The description is compact and every sentence earns its place: scope, syntax, ordering behavior, safety, and data-trust warning are all included without filler or redundancy. Key information is front-loaded in the first sentence.

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. The description covers search scope, query syntax, result ordering, read-only behavior, and the untrusted nature of message content. Minor gaps like limit semantics and pagination are acceptable given the schema and output schema, but the description could be slightly more 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 must compensate. It does so well for the query parameter by giving concrete KQL syntax examples, and it clarifies the folder parameter's behavior ('all folders unless folder is given'). The limit parameter is not explained, though its default is already visible in the schema.

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

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

The description states a specific verb and resource: 'Search the mailbox', with an explicit scope ('all folders unless folder is given'). It also distinguishes this tool from siblings by emphasizing relevance-ordering rather than date-ordering, making it clearly different from iris_list_messages and iris_get_message.

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 clear context on when to use the tool: for mailbox-wide or folder-scoped searches using KQL syntax. It notes that results are relevance-ordered, not date-ordered, which implies when this tool is appropriate versus alternatives. It does not explicitly name an alternative or state when not to use it, so it stops short of 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?

With no annotations, the description carries the full burden. It explicitly states the partial-update behavior, which is a valuable disclosure beyond the schema. However, it omits error handling, idempotency, or what happens if the draft does not exist, leaving behavioral gaps.

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, focused sentences with no wasted words. The core action is front-loaded, and the second sentence clarifies the update semantics effectively.

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 simplicity and presence of an output schema, the description is mostly adequate. However, missing context on error behavior or authentication (given no annotations) leaves room for improvement, making it minimally viable.

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 compensate. The phrase 'Only the fields you pass are changed' adds key partial-update semantics beyond the raw schema. Yet no per-parameter details are given, though parameter names are self-explanatory.

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 the specific verb 'Revise' with 'existing draft' and 'in place,' clearly identifying the target resource and distinguishing it from creation or other operations. This directly differentiates the tool from siblings like iris_create_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 usage context (update an existing draft) is implied but no explicit when/when-not guidance or alternatives are given. It doesn't mention that creating a new draft should use the sibling tool, leaving usage to be inferred.

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