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 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, 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, 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.