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

Beyond annotations (idempotent, non-destructive), description adds return format {success, error?} and the critical constraint that posting IDs are not accepted. No contradiction with annotations.

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

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

Two sentences with all critical information front-loaded. No redundant text, every sentence adds 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?

Given annotations, schema completeness, and no output schema, the description covers all necessary aspects: purpose, parameters, constraints, return format, and reversibility.

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

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

Schema coverage is 100%, and description adds crucial context: topic_id must come from list operations, slot options are explained, and date parameter requirement for custom slot. The distinction between topic_id and postingId is essential and well clarified.

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?

Explicitly states the action (schedule an email thread to bubble up) and resource (email thread). Differentiates from sibling hey_pop_bubble by mentioning reversibility.

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

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

Clearly states when to use (schedule a thread to reappear) and what not to use (posting IDs cause 404). Mentions reversible alternative hey_pop_bubble but does not contrast with hey_bubble_up_if_no_reply.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds the return shape and reversibility, but does not elaborate on side effects or triggers. Adequate but not exceptional.

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

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

Three sentences, front-loaded with the core purpose, no wasted words. Efficient and clear.

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 two-parameter tool, the description provides return value, reversibility, and ID clarification. No output schema exists, but the return shape is described. Complete for the complexity level.

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?

Both parameters are fully described in the schema (100% coverage). The description adds crucial context about using the correct ID field ('topicId' vs 'postingId'), which goes beyond schema documentation.

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 conditional behavior ('bubble up ONLY if there's no reply by a deadline date'), which differentiates it from siblings like 'hey_bubble_up'.

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

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

Explicitly mentions when to use (conditional bubbling) and provides a reversible alternative ('Reversible via hey_pop_bubble'). Also warns about the correct ID type. Could be improved by explicitly stating when not to use, but the alternative is implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description confirms 'Read-only with no side effects'. It adds value by clarifying that the data is local cache state (not live server state), which affects staleness interpretation. It stops short of describing freshness guarantees or how the storage estimate is derived.

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

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

Three short sentences, each earning its place: what it returns, its safety profile, and how/when to use it, with the most decision-relevant guidance front-loaded after the payload description.

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

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

No output schema exists, so the description must convey what comes back, and it does (message counts, cache age, storage estimate). The optional parameter is explained and the pre-flight use case is fully covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it specifies that folder scopes 'message/unread counts' specifically, telling the agent which outputs are affected. The schema-handled caveats about untracked folders complement this.

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?

Names a specific verb and resource ('Get local cache statistics') and enumerates the returned content: message counts, cache age, storage estimate. It also distinguishes itself from the sibling list tools by framing its role as a pre-flight check for force_refresh.

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

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

Explicitly states when to use it: 'Use before deciding whether to pass force_refresh on other list tools.' This routes the agent to the right decision point rather than leaving usage implied.

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

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

Adds real value beyond the annotations: the return shape ({success, error?}) and the fact that the operation is reversible by calling again with the opposite action. Annotations already cover the safety/freshness profile (destructiveHint=false, idempotentHint=true), so the description's contribution is the response contract and undo path.

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

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

Three short sentences with zero filler; the core action is front-loaded, followed by return shape, then the discovery hint. Every sentence carries distinct 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 3-parameter mutation with no output schema, the description covers the operation, the return contract, reversibility, and the ID-discovery prerequisite. Combined with complete schema coverage and annotations, an agent has everything needed to invoke 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 100%, so topic_id, collection_id, and the action enum are already fully documented in the schema. The description only repeats the hey_list_collections hint for collection_id and adds nothing new about parameter format or constraints, matching the baseline for fully covered schemas.

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 pair (add/remove) and a specific resource (an email thread within a collection), which an agent can distinguish from siblings such as hey_list_collections or hey_list_collection_emails. No ambiguity about what the tool mutates.

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

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

Explicitly routes the agent to hey_list_collections to discover valid collection IDs, which is the key prerequisite for calling this tool. It stops short of stating when not to use it (e.g., versus hey_set_status or label tools), so it falls just below 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 declare destructiveHint=true and idempotentHint=true, but the description adds what those hints cannot express: the delete bypasses Trash, is immediate and irreversible, and there is no restore counterpart. It also discloses the return shape ({success, draftId, error?}) despite no output schema existing.

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

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

Four short sentences, front-loaded with the destructive semantic and irreversibility, then return shape, then prerequisite. No filler and nothing 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 one-parameter destructive tool with no output schema, the description covers effect (immediate, non-Trash), reversibility (none), return value, and how to obtain the ID. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and the schema already names the source of draftId, so the description's provenance note is largely redundant with structured data. It adds no format, validation, or ID-shape detail beyond what the schema provides; baseline 3 applies for a single fully documented parameter.

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

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

States a specific verb and resource ('Permanently delete a draft by ID') and immediately scopes it against the sibling set by noting there is no hey_restore_draft. An agent can distinguish this from hey_save_draft / hey_edit_draft without opening any schema.

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

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

Explicitly states the prerequisite path ('Use hey_list_emails(folder='drafts') first if you don't already have the draftId from hey_save_draft or hey_edit_draft'), and explicitly excludes the assumed undo path. Both when-to-use and when-not-to-rely-on-restore are covered.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true (a filesystem-writing, non-idempotent operation). The description adds genuinely new behavior: the path must stay within ~, the default save location, and duplicate-filename auto-numbering (invite-1.ics, invite-2.ics), which is the concrete explanation for the non-idempotent hint. It does not mention permission or overwrite failure modes, so it falls 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?

Three tight sentences with zero filler: purpose first, then the prerequisite workflow, then the return shape. Every sentence earns its place and the most important constraint (read email first) 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?

There is no output schema, but the description supplies the return shape ({local_path, filename, size, mime}), the prerequisite tool, and the save-path behavior. Combined with complete schema coverage and annotations, an agent has everything needed to invoke 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 100%, so all three parameters (including the save_path default and directory semantics) are already fully documented in the schema. The description only restates that attachment_id comes from hey_read_email's attachments[] array, which the schema also says, so it adds little beyond baseline.

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 concrete verb+resource+effect: 'Download a single attachment from an email and save it to disk.' It is the only download/attachment tool among the siblings, so the scope is unambiguous without opening any schema.

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

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

Gives an explicit two-step workflow: call hey_read_email first to obtain the attachments[] array, then call this tool with the attachment_id. It names the prerequisite sibling and the exact input it provides, so an agent knows when and how to sequence the call.

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

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

Adds substantial context beyond the annotations: outright (non-merging) replacement semantics, the omit-to-leave-unchanged rule, irreversibility of overwritten values, and the return shape {success, draftId, error?}. There is mild tension with destructiveHint=false given the explicit warning that previous values are not recoverable, but the target draft itself is not destroyed, so this reads as nuance rather than a hard 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?

The core purpose and the crucial no-merge/omit rule are front-loaded, followed by return shape, irreversibility, and routing. Every sentence carries information, though the description is dense and runs slightly long for a five-parameter update tool.

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

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

No output schema exists, yet the description supplies the return shape and the key behavioral rules (replacement, omission, irreversibility) an agent needs to invoke it safely. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying that omitted fields retain their last-saved value and that passing a field replaces rather than merges — a semantic the schema does not state and that materially affects how the agent should call it.

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

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

States a specific verb (update), resource (an existing draft), and the exact mutable fields (recipients, subject, body). It also explicitly distinguishes itself from the sibling create tool hey_save_draft and the removal tool hey_delete_draft, so an agent can route correctly without opening any schema.

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

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

Explicitly states prerequisites ('Use hey_save_draft to create a draft before calling this') and a when-not condition ('use hey_delete_draft to remove one instead of blanking it out'). It also gives a concrete guidance action — re-fetch via hey_list_emails(folder='drafts') first if preservation matters.

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?

Description discloses that forwarding is immediate and non-destructive (thread unchanged), and mentions the return shape {success, error?}, adding value beyond annotations. Could include more on authorization or error conditions.

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

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

Three concise sentences, each serving a purpose: action/effect, key behavior, and usage guidance. No extraneous 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?

Covers purpose, usage, and return type for a simple forwarding tool. Lacks details on error handling or behavior with invalid entry_id, but adequate given tool complexity.

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?

With 100% schema coverage, the description adds little beyond the schema. It reinforces that body is optional but does not provide additional semantic or formatting guidance.

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 forwards an existing email immediately and notes the original thread remains unchanged, distinguishing it from siblings like hey_send_email and hey_reply.

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

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

Explicitly instructs to use this tool instead of hey_send_email for sharing existing content and hey_reply for replying within a thread, providing clear when-to-use and 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?

ReadOnlyHint annotation is consistent with description of extraction. Description adds context that it returns full details and requires prior call to hey_read_email, which is useful behavioral sequence.

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 waste: first sentence states purpose, second provides usage guidance. Front-loaded with core action.

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 no output schema, description lists all returned fields (title, start, end, etc.). Covers prerequisites, input, output, and relationships with siblings.

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

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

Schema has 100% parameter description coverage; description adds workflow context for email_id (same as hey_read_email) and clarifies attachment_id purpose for multiple .ics parts.

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?

Description clearly states the tool extracts and parses a calendar invite (.ics) from an email, with specific verb and resource. It distinguishes itself from siblings like hey_read_email and hey_download_attachment.

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

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

Explicitly tells when to use (after hey_read_email if calendar_invites present) and when not to use (use hey_download_attachment to save .ics). Provides clear workflow.

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

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

Annotations already indicate read-only and open-world hints. Description adds that it includes specific counts and emails, but doesn't mention caching behavior or other traits beyond what annotations provide.

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

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

Two sentences, no unnecessary words. Front-loaded with the purpose and usage guidance. Very concise.

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 no output schema, the description provides a reasonable expectation of what the summary includes. Could be more explicit about the complete return structure, but adequate for a simple tool.

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

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

Schema coverage is 100% for the single parameter (force_refresh). Description does not add any additional meaning or usage details about the parameter.

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?

Clearly states 'Get a complete Imbox summary' with specific included items (screener count, bubbled up emails, new emails). Differentiates from sibling tools by being a high-level overview, distinct from list or action 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?

States 'use this for a comprehensive view of the inbox state', providing context for when to use it. However, no explicit alternatives or when-not-to-use guidance.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=true), but the description adds real value by disclosing the return shape ({success, error?}) despite no output schema, and by explaining reversibility. It doesn't cover auth requirements or rate limits, but the added context is substantive.

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

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

Three tight sentences with zero filler: the action is front-loaded, the return shape follows, and the discovery pointer closes it out. Every sentence earns its place.

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

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

For a 3-param mutation tool with full schema coverage but no output schema, the description supplies the missing return shape, reversibility semantics, and ID discovery path. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema description coverage is 100%, so the enum, label_id, and topic_id are fully documented in the schema. The description's only param-related guidance (use hey_list_labels for IDs) duplicates the label_id schema description, so there is no net addition beyond structured fields.

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 pair (add/remove) and resource (label on an email thread), which is unambiguous and distinct from siblings like hey_set_aside or hey_move_to. An agent can tell immediately what this tool does without reading further.

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

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

Explicitly routes the agent to hey_list_labels to discover available label IDs before calling. It gives clear prerequisite context, though it doesn't contrast against similarly-scoped siblings like hey_set_status or explain when labeling is preferable to those alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds real behavioral value by disclosing the caching behavior ('Returns cached results unless force_refresh=true'), which the annotations do not convey. It stops short of stating auth needs, rate limits, or return shape, but this is useful added context.

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

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

Two tight sentences with zero filler; the primary purpose is front-loaded and the caching caveat follows. Every clause earns its place.

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

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

For a simple read-only, collection-scoped list tool with full schema coverage and safety annotations, the description covers purpose and the one non-obvious behavior (caching). Pagination and return format are handled by the schema, so little is missing, though it could note the collection_id dependency more explicitly.

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

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

Schema description coverage is 100%, so all four parameters (page, limit, collection_id, force_refresh) are already documented in the schema, including defaults and ranges. The description only restates the force_refresh semantics already present in the schema, adding no new parameter meaning beyond the baseline.

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 emails in a specific collection'), which clearly identifies the operation. It separates itself from plain list_email indirectly via the 'collection' scope, but never names a sibling collection-vs-label distinction, so it falls short of full sibling differentiation.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as hey_list_emails or hey_list_label_emails. The scoping is inferable from the tool name but the description offers 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?

Annotations already indicate readOnlyHint and openWorldHint. Description adds that it returns an array of {id, name} and lists all collections, but does not elaborate on behavior like pagination or edge cases. Still, the return format is useful context.

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

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

Two sentences, front-loaded with the core action 'List all collections,' and no wasted words. Every sentence adds 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?

Given no parameters, no output schema, and simple design, the description is complete. It specifies return format and how to use results with sibling tools, covering the agent's needs.

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?

No parameters (0), so schema coverage is irrelevant per guidelines at 100% vacuous. Description adds meaning by explaining the tool's function and output, which compensates for lack of param info. Baseline 4 is appropriate.

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

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

The description clearly states it lists all collections in Hey.com, specifies the return format (array of {id, name}), and distinguishes from sibling tools like hey_collection (single collection) and hey_list_collection_emails (emails of a collection).

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

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

Provides explicit guidance: 'Use the id with hey_collection or hey_list_collection_emails,' telling the agent when to switch to alternatives. Also, no parameters means no ambiguity in usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond them: results are cached unless force_refresh=true, and it candidly flags that the sent-folder recipient field is unverified against a live Sent page — a real reliability caveat.

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

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

Three front-loaded sentences: purpose, caching behavior, then returned fields. Each carries distinct information with no filler, though the return-field enumeration is somewhat list-like and could be trimmed.

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 output schema, the description correctly compensates by enumerating the returned fields (id, topicId, postingId, entryId, from, subject, date, unread). Caching semantics and the sent-folder edge case round it out; only pagination/interaction with page and limit is left entirely to the schema.

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

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

Schema coverage is 100%, so parameter definitions are already well documented (baseline 3). The description goes further by explaining force_refresh's cache-bypass effect in context and by describing the sent-folder quirk where from is always "Me" and the recipient moves to to/toEmail, which is nowhere 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 ("List emails in a Hey.com folder/view") and scopes it to the folder/view axis, which distinguishes it from siblings like hey_list_label_emails and hey_list_collection_emails. It does not name those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

Usage is implied by the folder/view framing, and the force_refresh sentence signals when a cache bypass is warranted. However, it never says when to prefer this over hey_search or the label/collection listing tools, so the agent must infer the selection rule.

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 and openWorldHint, so safety is covered. The description adds genuinely new behavioral context the annotations do not carry: results come from a cache by default and are only re-fetched when force_refresh=true. It omits pagination behavior and return shape, but adds real value beyond the structured fields.

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

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

Two sentences, zero waste, with the core operation stated first and the caching caveat second. Nothing is padded or 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?

For a read-only, open-world list tool with a fully documented schema and no output schema, the description covers the essential non-obvious behavior (caching). It is nearly complete; the only gap is what a result looks like and pagination limits, which the schema partially covers.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description contributes semantics the schema does not: it explains the consequence of force_refresh ('returns cached results unless...') rather than merely restating 'bypass cache'. label_id, page and limit are left to the schema, which documents them adequately.

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?

Names a specific verb and resource with a clear scope qualifier ('emails with a specific label'), which distinguishes it from the broader hey_list_emails. It does not, however, explicitly name or contrast with the closest siblings (hey_list_emails, hey_list_collection_emails), so differentiation must be inferred from the scope phrase.

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

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

Usage is implied by the scope ('with a specific label'), and the caching clause hints at when to set force_refresh, but the description never states when to prefer this over hey_list_emails, hey_list_collection_emails, or hey_search. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by disclosing the return shape ('array of {id, name}'), which matters since there is no output schema; it omits ordering/pagination but those are minor for a label list.

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

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

Three short sentences with zero waste: purpose, return shape, and next-step routing are front-loaded in that order. Nothing could be cut 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 zero-param, side-effect-free listing tool with annotations covering safety, the description supplies the one thing structured data does not: the return shape. It stops short of noting whether results are cached or ordered, a minor gap for this complexity level.

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. There is nothing for the description to clarify, and it correctly avoids inventing parameter semantics.

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 labels/folders in Hey.com') and goes further to declare the exact return shape ({id, name}) and the follow-up tools that consume the id. An agent can distinguish it from hey_list_label_emails or hey_list_collections without opening any schema.

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

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

The description names two follow-up tools that consume the returned id, which implies a discover-then-act workflow, but it never says when to prefer this tool over the sibling list tools or state any precondition. Usage is inferred rather than specified.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavior: results are cached unless force_refresh=true, and the output shape matches hey_list_emails. This goes beyond the structured fields.

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

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

Three tight sentences, zero filler, with the core purpose front-loaded and the caching caveat and removal pointer following in priority order.

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 output schema, the description compensates by stating the return shape matches hey_list_emails and that items carry a postingId. That is enough for an agent to act, though it could note pagination or empty-stack behavior.

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

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

Schema coverage is 100% and the single force_refresh parameter is fully documented in the schema including its default. The description's mention that force_refresh bypasses the cache largely restates the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List emails currently in the Reply Later stack'), which is distinguishable from sibling list tools like hey_list_set_aside and hey_list_emails. An agent can identify the target stack without opening the schema.

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

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

Names the follow-up tool hey_remove_reply_later with the exact identifier (postingId) needed, which routes the agent correctly for removal. It does not explicitly say when not to use this versus hey_list_emails, so it falls short of the 5 bar.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds a genuinely useful trait they do not: results are cached and only refreshed when force_refresh=true. That caching disclosure is real behavioral value beyond structured fields, though rate limits, pagination, or staleness windows are not addressed.

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

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

Three short sentences, front-loaded with the purpose, then the caching caveat, then the follow-up tool. Every sentence earns its place with no filler.

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

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

For a one-parameter, annotation-covered list tool with no output schema, the description compensates by describing the return shape ('same shape as hey_list_emails, plus clearanceId'), which is exactly what an agent needs to chain into hey_screen_by_id. Nothing essential is missing.

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

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

With a single parameter at 100% schema description coverage, the schema already documents force_refresh as a cache-bypass flag with a default of false. The description echoes that behavior ('unless force_refresh=true') but adds no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List senders waiting in the Screener for approval') and immediately differentiates itself from the sibling hey_screen_by_id, which handles approval/rejection instead. An agent can tell what this tool does and what it does not do without opening a schema.

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

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

Explicitly routes the agent to hey_screen_by_id with the returned clearanceId for the follow-up approve/reject step, which gives clear situational context. It stops short of stating when *not* to use this tool (e.g., vs hey_list_emails or hey_screen for other inbox views), so it is clear but not fully 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?

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavioral detail the annotations do not cover: results come from a cache and force_refresh bypasses it, and the payload is the same shape as hey_list_emails. It omits cache scope/TTL, but that is a minor gap given the read-only safety profile is already declared.

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

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

Three short sentences, zero waste, front-loaded with the core purpose and followed by cache behavior and the follow-up action. Every sentence carries information an 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?

With no output schema, the description usefully tells the agent the result set shape matches hey_list_emails and how to act on the returned postingId. Caching behavior and the removal path are covered; only finer details like refresh cost or list size limits are absent.

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

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

Schema coverage is 100% for the single force_refresh parameter, so the baseline is already covered. The description reinforces the semantics by explaining that true bypasses the cache, which adds practical meaning to the flag beyond the schema's terse wording.

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 emails currently in the Set Aside stack') and places it against siblings by noting the result shape matches hey_list_emails and that removal is done via hey_unset_aside. An agent can distinguish this from hey_list_emails, hey_list_reply_later, and hey_list_collections without opening a schema.

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

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

Gives clear operational context: results are cached unless force_refresh=true, and the returned postingId feeds hey_unset_aside. It stops short of an explicit 'use this instead of X when...' routing rule, so it is strong 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?

Adds details beyond annotations: explains return format {success, error?}, HTTP methods, and that the action is reversible per-item. Consistent with idempotentHint and non-destructive nature.

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?

Concise yet informative: each sentence adds value. Front-loaded with purpose, then specifics, then usage guidance.

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?

Fully describes both usage modes, return format, and reversibility. No output schema needed given simplicity and parameter count of 1.

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?

Adds meaning beyond the schema by explaining that omitting posting_id clears entire tray and passing a specific ID clears one item. References postingId field from list operations for clarity.

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?

Description clearly states the tool clears the 'New for you' tray dot, specifying both per-item and bulk modes. It distinguishes from sibling tool hey_mark_unseen by mentioning reversibility.

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

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

Explicitly advises using after triaging or skimming a batch to keep tray tidy. Mentions reversal via hey_mark_unseen, providing clear alternative.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds context about the return format ({success, error?}) and the side effect of reading the email implicitly marking it seen. This goes beyond annotations.

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

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

Three sentences, each one adding value. Front-loaded with the core action, then return type, then usage caveats. No wasted words.

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

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

The tool is simple with one parameter and no output schema. The description fully covers purpose, usage guidelines, side effects, and return format, leaving no gaps.

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

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

Schema description coverage is 100%, and the description only restates what the schema already says ('The topic/thread ID to mark as unseen'). No additional meaning or clarification is provided.

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

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

The description clearly states the tool's action: 'Mark a thread as unseen/unread to reset its read status.' It uses a specific verb and resource, and distinguishes itself from the sibling 'hey_mark_seen' by explaining the difference.

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 explicit guidance on when to use this tool (to reset read status) and when not to (to clear the orange dot without re-marking unseen, use 'hey_mark_seen'). It also mentions the side effect of reading email marking it seen.

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?

Discloses return format ({success, error?}), reversibility, and scope boundaries beyond annotations. Annotations already indicate non-read-only, non-destructive, and idempotent; description adds context confirming these.

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

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

Every sentence provides essential information—action, return value, usage advice, reversibility, and exclusions. No redundancy; core purpose 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?

Covers primary use cases and return format. Minor gaps exist (e.g., error conditions for invalid id), but the presence of 'error?' in return implies error handling. With no output schema, this is sufficient.

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?

Input schema has 100% description coverage, so baseline is 3. Description adds value by explaining the meaning of each destination value and when to use them, going beyond the schema's enum labels.

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?

Clearly states the action (move email thread) and the specific views (imbox, feed, paper_trail). Differentiates from sibling tools by noting it does not affect trash, spam, or screener.

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

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

Explicitly says when to use each destination (paper_trail for receipts, feed for newsletters, imbox to restore) and provides alternatives for other actions (hey_set_status, hey_screen).

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?

Discloses idempotent behavior (consistent with annotations), non-destructive nature, return value {success, error?}, and error condition for incorrect ID types. Adds value beyond annotations.

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

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

Concise two-sentence description front-loaded with action and effect, no wasted words.

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

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

For a simple 1-parameter tool without output schema, the description covers purpose, usage, prerequisites, return type, and error cases completely.

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?

Input schema already covers 100% of parameters with detailed guidance on topic_id vs postingId. Description reinforces but adds minimal new information beyond schema.

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

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

The description clearly states the tool pops/dismisses a bubbled email thread, distinguishing it from sibling tools like hey_bubble_up by specifying the reverse action.

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

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

Provides explicit instructions on when to use, including the prerequisite of using topic_id (not posting_id) and clarifies that the thread is not deleted, just unpinned.

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 (readOnlyHint, openWorldHint) indicate safe, non-destructive operation. Description reinforces read-only nature and details output structure (entries[], attachments[], calendar_invites[]) and format behavior, adding value beyond annotations.

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

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

Three concise sentences, front-loaded with main purpose, then details on output and alternative tools. No wasted words; each sentence adds distinct value.

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

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

No output schema, but description adequately explains return fields and links to sibling tools for next steps. With annotations, provides complete context for safe and effective use.

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

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

Schema coverage is 100%, but description adds context: explains id can be topicId or entryId, clarifies format default and behavior (html = full thread, text = first message only). Provides meaning beyond schema definitions.

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?

Description clearly states it reads an email thread's full content, using specific verb 'Read' and resource 'email thread'. It distinguishes from siblings like hey_download_attachment and hey_get_calendar_invite by mentioning them for further actions.

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

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

Provides guidance on when to use format='html' vs 'text', and references sibling tools for attachments and calendar invites. Implies using topicId from list operations, but does not explicitly state when not to use this tool (e.g., for single messages vs threads).

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

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

Annotations already indicate the tool is not read-only, not destructive, and idempotent. The description adds the return format {success, error?}, reversibility, and per-entry scope, which are valuable but not extensive behavioral details.

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

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

Three sentences, no wasted words, front-loaded with primary action. Every sentence serves a purpose: main action, return value, reversibility, scope, and sibling reference.

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 two-parameter tool without output schema, the description covers usage, behavior, return value, and differentiation from siblings. No obvious gaps.

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

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

Input schema covers both parameters with descriptions, so baseline is 3. The description adds guidance to use entryId from list operations and explains that it operates on individual entries, providing context beyond 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?

Clearly states the tool sets read/unread status of an email entry. Distinguishes itself from the sibling hey_mark_unseen by specifying it works on individual entries, not threads.

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

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

Explicitly tells when to use this tool (for individual entries) and when to use an alternative (hey_mark_unseen for entire threads). Also states the operation is reversible.

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

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

Annotations cover safety flags (idempotentHint, destructiveHint=false, readOnlyHint=false), and the description adds substantive context beyond them: the "Done" status change, the move back to the Imbox, and the return shape {success, error?}. It also discloses reversibility and the exact recovery path, which is not derivable from the annotations.

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

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

Four short sentences, each carrying distinct information (action, side effects, return shape, prerequisite, reversal). The primary action is front-loaded and there is no redundant restatement of the name.

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

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

For a single-parameter mutation with no output schema, the description supplies everything needed: the source of the required id, the side effects, the return shape, and the undo path. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the parameter is documented, so the baseline is 3. The description adds value by stating where to obtain posting_id (hey_list_reply_later), giving the agent a concrete sourcing workflow rather than just a type.

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 (remove) and resource (email from Reply Later) and goes further by naming the observable side effects: marking the item "Done" and moving it back to the Imbox. This distinguishes it cleanly from siblings like hey_set_aside, hey_reply_later, and hey_unset_aside.

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

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

Explicitly names the prerequisite source for posting_id (hey_list_reply_later) and describes the inverse operation (hey_reply_later with topic_id), which is strong routing. It lacks an explicit when-not condition, which keeps it just 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?

Annotations already declare non-readOnly, non-idempotent, non-destructive, open-world. The description adds real value beyond them: the return shape ({success, error?}), the default recipient behavior (own address auto-excluded), and threading preservation. It doesn't mention auth needs or rate limits, but for this tool those are minor.

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 and return shape, then recipient defaults, then override cases, then sibling routing. Every sentence earns its place and nothing is repeated verbatim from the schema without purpose.

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

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

No output schema exists, and the description compensates by stating the return shape. Combined with the recipient-default and threading notes, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the default recipient set and the automatic exclusion of your own address, which explains why `to` exists at all. The detailed `to`/`cc` mechanics are largely mirrored from the schema, capping it below 5.

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

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

Specific verb+resource ('Reply to an email thread') with a stated distinguishing trait ('preserving threading on both ends'). It explicitly names the sibling it is not (hey_send_email) and the condition that differentiates them, so an agent can disambiguate without opening any schema.

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

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

Gives explicit routing guidance: 'Prefer this over hey_send_email when responding to an existing thread; use hey_send_email only for new conversations.' It also explains when to reach for the `to` override (chasing your own thread, redirecting off a mailing list).

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

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

Annotations already declare this is a mutation (readOnlyHint=false), idempotent, and non-destructive; the description adds genuinely new context: reversibility via hey_remove_reply_later, the postingId prerequisite from hey_list_reply_later, and the return shape {success, error?}. It stops short of describing side effects like removal from the Imbox, which keeps it below a 5.

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

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

Three short clauses: action, reversal path, decision rule with alternative. Front-loaded and every sentence earns its place with no padding.

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

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

With no output schema, the description supplies the return shape, the undo path, and the routing rule against a sibling — everything an agent needs to call and recover from 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 100% and the single 'id' parameter is documented there (topicId or entryId from list operations), so the baseline applies. The description's mention of postingId pertains to the reversal tool rather than the input, adding no new meaning about the argument itself.

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

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

States a specific verb and resource ('Move an email thread to Reply Later') and explicitly contrasts with siblings hey_set_aside and hey_remove_reply_later, so an agent can distinguish it without opening other 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?

Gives explicit when-to-use ('emails you intend to respond to but not right now') and when-not-to-use with a named alternative ('if no reply is planned, use hey_set_aside instead'), plus the reversal path. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is partly covered. The description adds real value: it names the Drafts folder destination, discloses the return shape ({success, draftId?, error?}), and surfaces the key workflow limitation that sending isn't available via MCP.

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

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

Front-loaded with the core action, then folder destination, optionality, return shape, and alternatives. Dense but every sentence carries distinct information; nothing is redundant 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 no output schema, the description supplies the return shape, the folder behavior, the optionality semantics, and the critical workflow limitation that sending must happen outside MCP. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the params are already documented (baseline 3). The description adds rationale beyond the schema: recipients, subject, and body are all optional specifically so a partially-written draft can be saved, which explains the intended usage pattern.

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 ('Save a new draft email') plus scope ('without sending it'). It's immediately distinguishable from siblings like hey_edit_draft, hey_send_email, and hey_reply, which it names directly.

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

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

Explicitly routes the agent: use hey_edit_draft to keep revising, hey_send_email/hey_reply to send immediately, and finish in the web/app UI since MCP can't send. When-to-use, when-not, and alternatives are all 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 declare destructive/idempotent/openWorld, and the description adds substantial non-redundant context: reject does NOT mark spam, existing emails are untouched, the operation falls back to the contact-page clearance route, and it is reversible in the Hey UI but not via MCP. It even discloses the return shape, which annotations cannot.

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 verb pair, then layers approve/reject semantics economically in a few tight sentences. Slightly heavy on parenthetical implementation detail (the /contacts/{id}/clearance path), but nearly every clause earns its place.

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

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

For a 3-param mutation with no output schema, the description covers action semantics, edge cases (already-approved senders), side effects, reversibility, and return shape. Nothing the agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents destination defaults and that it is ignored on reject; the description largely restates these. It adds the 'screen out' alias and the approve routing/default, but no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb pair and resource ('Approve or reject a sender by email address') and explicitly differentiates from siblings by naming hey_list_screener and hey_screen_by_id. An agent can pick this tool over those without opening a schema.

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

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

Gives explicit when-to-use routing ('Use hey_list_screener to see pending senders, or hey_screen_by_id for clearance IDs') and clarifies that reject applies to both pending and already-approved senders. The alternative tools and the condition selecting them are stated outright.

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

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

Goes well beyond the annotations (destructiveHint, idempotentHint) by spelling out the downstream effect of each action on future mail flow, the default destination, and the reversibility constraint ('reversible from the Hey UI's contact page, not yet via MCP'). It even discloses the return shape '{success, error?}' in the absence of an 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-loads the action and resource, then branches cleanly into Approve/Reject effects, a reversibility note, the return contract, and sibling routing. Every sentence carries information; none is filler.

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

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

With no output schema, the description supplies the return contract, both action semantics, the destination default, reversibility limits, and sibling navigation. An agent has everything needed to invoke this destructive, idempotent 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 coverage is 100% and the schema already documents the destination default (imbox) and enum meanings, so the description largely restates what is structured. It adds only light value by tying destination to the approve branch and clarifying it is ignored on reject.

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 compound action (approve/reject) on a precise resource (first-time sender in the Screener) keyed by clearance ID. It is immediately distinguishable from hey_list_screener and hey_screen by the ID-vs-email keying, which the description itself calls out.

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

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

Explicitly routes the agent: 'Use hey_list_screener to get clearance IDs' and 'for senders that have already left the screener, use hey_screen by email instead.' Both the prerequisite and the exclusion condition that selects a sibling are named.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description adds genuinely new behavioral context: the two-stage cache-then-network lookup and the latency/freshness tradeoff controlled by force_refresh. It stops short of describing result payload, ranking, or what happens when the cache is cold and the network fails.

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

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

Three short sentences, each earning its place: purpose, retrieval mechanism, and the override flag. The core intent is front-loaded with no filler.

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

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

For a 3-parameter, no-output-schema read tool the description covers the operational behavior an agent needs to call it sensibly. The remaining gap is that it never indicates the result shape (email objects) or result-set behavior, which an agent must infer from siblings.

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

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

Schema coverage is 100%, so all three parameters including ranges and defaults are already documented in the schema. The description only reinforces force_refresh's meaning ("real-time results"), adding no constraint or format detail beyond the schema — the correct baseline when the schema does the heavy lifting.

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 emails by query") that clearly separates it from the sibling list_* tools, which enumerate rather than query. It does not explicitly name an alternative, but the resource and intent are unambiguous.

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

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

It explains the retrieval flow (cache first, then network) and points to force_refresh for real-time results, which implies when to use which mode. However it never says when to reach for hey_search versus hay_list_emails or other listing siblings, so the routing decision is left to inference.

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

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

Annotations indicate mutating operation (readOnlyHint=false) and description adds immediate sending and return shape, but lacks details on potential side effects or failure modes beyond a brief mention.

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 unnecessary words; first sentence defines action and return, second provides direct usage comparison to siblings.

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

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

Covers purpose, usage alternatives, and return format briefly. Lacks details on constraints like attachment support or rate limits, but sufficient for a simple send email tool given sibling differentiation.

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

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

Schema coverage is 100% with descriptions for all parameters; description adds no extra semantic meaning beyond the schema, meeting baseline expectations.

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?

Description clearly states 'Send a new email immediately' and differentiates from sibling tools hey_reply and hey_forward with specific usage contexts.

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

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

Explicitly states when to use this tool vs alternatives: 'Use for standalone outbound messages; use hey_reply for thread responses, or hey_forward to share existing emails with new recipients.'

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 it non-read-only, idempotent, and non-destructive; the description adds the operational details that matter: the action is reversible via hey_unset_aside, which requires a postingId obtained from hey_list_set_aside, the response shape is {success, error?}, and it does not affect future emails from the sender.

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 compact sentences with the core action, reversibility, return shape, and routing rule front-loaded; no filler and nothing repeated from structured fields.

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

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

For a one-parameter mutation with no output schema, the description supplies the return shape, the undo path, and the side-effect boundary, leaving nothing an agent needs to invoke it correctly unstated.

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

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

Schema coverage is 100% and the single parameter is already documented there (topicId/entryId). The description adds no syntax or format detail for the id beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Move) and resource (email thread) plus the destination state (Set Aside). It differentiates itself from siblings by naming hey_reply_later as the alternative for a different intent.

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 explicit when-to-use ('emails you plan to revisit but don't need to reply to'), when-not ('emails needing a reply'), and the alternative tool (hey_reply_later). Also names the reversal path (hey_unset_aside) and the prerequisite ID source.

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 provide destructiveHint and idempotentHint; description adds concrete details: 'trash removes from Imbox', 'spam blocks the sender', and error handling for bundles. No 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 dense sentences with no unnecessary words. Front-loaded with purpose, then return format, then edge cases. Highly efficient.

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?

Addresses return format, destructive effects, reversibility, and special case (bundles). No output schema needed given simplicity. Complete for minimum viable understanding.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds context on id parameter usage (topicId vs postingId) and action effects, but enum already lists actions.

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?

Description clearly states it changes an email thread's status, which is a specific verb+resource. It distinguishes from sibling tools like hey_label or hey_collection by focusing on status actions (trash, spam, etc.).

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

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

Provides explicit context on reversibility (trash/spam), destructive effects, and bundle-specific limitations (only trash works on bundles). Could mention when to use this vs other status-changing tools like hey_screen, but the domain is different.

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?

Discloses key behaviors: reversible, keeps thread in current view, returns {success, error?}. Aligns with annotations (idempotentHint true, destructiveHint false). No contradictions.

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

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

Three concise sentences front-loading the core purpose, with no extraneous text. Every sentence adds 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?

Given the simple tool, annotations, and full schema coverage, the description fully satisfies the agent's needs. Mentions return format despite no output schema.

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

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

Schema covers both parameters (100%). Description adds context for posting ID (use from list ops) and action enum values, going beyond 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?

Clearly states 'Mute or unmute a thread' with the Hey.com term 'Ignore' for clarity. Distinguishes from siblings like hey_read_email (which checks mute status) and hey_move_to (which moves threads).

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 when to use (stop/resume notifications) and provides explicit guidance to check mute status via hey_read_email. Could add more on when not to use, but 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds genuinely useful context beyond them: the return shape {success, error?} and the fact that the action is reversible via hey_set_aside. It does not mention failure modes or what happens if the posting_id is absent, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the action and effect, followed by return shape and prerequisite. No filler and every sentence carries operational 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 one-parameter tool with no output schema, the description covers the effect, the return shape, the parameter source, and reversibility. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the single parameter's description already states it comes from hey_list_set_aside, so the description largely repeats rather than extends the schema. Baseline 3 applies when the schema does the heavy lifting.

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 (Remove) and resource (an email from Set Aside), and states the resulting state change (moved back to the Imbox or original location). It is clearly distinguishable from the sibling hey_set_aside, which performs the inverse operation.

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 the prerequisite (requires posting_id from hey_list_set_aside) and names the alternative operation that reverses it (hey_set_aside with topic_id). It does not spell out a when-not-to-use condition, but the context is unambiguous for a single-purpose unsave tool.

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