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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral details beyond annotations: events are expanded into single instances and ordered by start time. It does not cover rate limits or auth, but for a read-only listing tool with strong annotations, this is adequate.

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

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

The description is two sentences, front-loaded with the verb 'List', and contains no redundant information. It efficiently communicates the core function and key output traits without 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 has moderate complexity with four parameters and an output schema, but the description covers the essential behavior (expansion, ordering, read-only). The schema explains parameters in detail, and the output schema handles return values. The description is sufficiently complete for an agent to understand when and how to invoke the tool.

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

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

The input schema provides rich descriptions for all four parameters (max_results, calendar_key, time_min_iso, time_max_iso), so the schema itself carries the parameter semantics. The description only mentions calendar_key and does not add additional meaning beyond the schema. Since schema coverage is high, the baseline score 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?

The description opens with 'List events from the secondary calendar for calendar_key', clearly stating the action (list) and resource (calendar events), and identifies the key parameter. It further defines the output behavior (expanded into single instances, ordered by start time). This distinguishes it from the sibling calendar_upsert_event, which is a write 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?

The description implies the tool is for reading events and explicitly labels it as read-only, which suggests it should not be used for modifications. However, it does not name alternatives like calendar_upsert_event or provide explicit when-to-use/when-not-to-use guidance. The usage context is clear but not fully articulated.

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 mark readOnly=false, idempotent=true, destructive=false. The description adds valuable context beyond these: it clarifies the write target (secondary calendar only), the in-place update behavior for existing iCalUIDs, and the prevention of duplicate events on re-runs. This meaningfully supplements the structured hints without 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 description is three sentences long, front-loaded with the primary purpose, and every sentence adds meaningful detail (idempotency, secondary calendar scope, update-vs-create behavior). There is no fluff or repetition of schema content.

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

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

For a write tool with a rich schema and output schema present, the description adequately covers the core behavioral context: idempotency mechanism, calendar routing, and side effects. It does not cover authentication or error specifics, but those are not essential given the schema and annotations. The sibling list clearly separates read vs write tools.

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 description does not mention any parameter names, and schema description coverage is 0%. However, the input schema itself provides rich descriptions for every parameter (calendar_key, start_iso, ical_uid, etc.), including the stable UID derivation and calendar routing. The description's idempotency statement is conceptually helpful but largely redundant with the schema's ical_uid explanation, so a baseline score 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 'Create or update an event in the secondary calendar' with the specific resource (calendar event), action (create/update), and scope (secondary calendar). It distinguishes from sibling tools like calendar_list_events (read-only) and emphasizes idempotency by iCalUID.

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

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

The description provides clear context: it is for writing to the secondary calendar, never the primary, and is idempotent for repeat runs. It does not explicitly name alternative tools for read operations, but the contrast with calendar_list_events is implied and the 'never the primary calendar' guidance prevents misuse.

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 readOnly=false and destructive=false, so the safety profile is known. The description adds transparency by explaining label display name resolution to IDs (case-insensitive, system labels work), optional creation of missing add-labels, and that missing remove labels are skipped and reported. This goes beyond annotations, though it doesn't discuss rate limits or granular error cases beyond 'unresolved_remove_labels'.

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 fluff. The first sentence states the core operation, the second adds a practical example. Every phrase earns its place, and it is front-loaded with the primary 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?

The tool has moderate complexity with multiple parameters and an output schema. The description covers the key behavioral nuances (label resolution, creation, removal semantics) while leaving pagination and response format to the output schema. It doesn't mention auth, but annotations and sibling context make it adequately complete for an agent to invoke confidently.

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 reported as 0%, so the description must compensate. It explains that label names are resolved to IDs, supports system labels, and that create_missing_labels controls label creation. The schema only provides bare field names and default values, so the description adds meaningful semantics that help an agent provide correct parameter values.

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

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

The description opens with a specific verb+resource: 'Add and/or remove labels on specific Gmail messages by ID via batchModify.' This clearly distinguishes it from sibling tools like gmail_search_emails or gmail_bulk_label_matching, which focus on searching or bulk labeling based on criteria, not direct message ID targeting.

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 a concrete use case: 'Use to mark messages AI-Processed and remove UNREAD.' This implies when the tool is appropriate, though it doesn't explicitly contrast with alternatives like gmail_bulk_label_matching. The context is clear enough for an agent to choose this tool for direct label mutations on specific messages.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable context beyond that: 'Bodies are passed through the masking layer before return' and 'HTML is stripped to text when that's all that's available'. These are important behavioral traits not visible in annotations.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds meaningful information. The final 'Read-only' is redundant with annotations but does not detract from conciseness.

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 that an output schema exists, the description does not need to detail return values. It covers the key behaviors: batch size, body decoding, HTML stripping, and masking. However, the lack of mention of the 'format' parameter is a minor completeness gap.

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

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

The schema description coverage is 0%, so the description must compensate. It mentions 'message IDs' and the 100 limit, but it completely omits the 'format' parameter that allows 'metadata' instead of 'full'. This is a significant gap since the agent cannot know about this option from the description alone.

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 'Fetch full content for up to 100 Gmail messages by ID', which is a specific verb ('fetch'), resource ('Gmail messages'), and scope ('by ID', 'up to 100'). This distinguishes it from sibling tools like search functions and thread reads.

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

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

The description implies usage when message IDs are already known ('by ID'), but it does not explicitly state when to use this over alternatives or provide exclusions, such as 'use search to find IDs first'. No alternatives or when-not-to-use guidance is 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 indicate readOnly=false, idempotent=true, and destructive=false. The description adds meaningful behavior context: it resolves label names to IDs and can create missing add-labels. This goes beyond the annotations, though it does not mention the max_results cap which could affect the 'every matching message' claim.

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 the primary search-and-modify behavior. Each sentence adds necessary context: the operation, the resolution behavior, and the primary use case. No filler or redundancy.

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

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

The description covers the main workflow and special behaviors but misses the max_results limit, which is important because 'every matching message' could be misleading given the default cap of 500. The output schema exists, so return values don't need explanation, but the incomplete mention of limitations prevents a higher score.

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

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

Schema description coverage is 0%, so the description must compensate. It does mention 'query' and label names (add/remove) and 'create missing add-labels', mapping to add_label_names and create_missing_labels. However, it does not describe max_results or the exact semantics of label resolution beyond a general statement. The schema itself provides detailed parameter descriptions, but the tool description adds only moderate value.

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 searches Gmail with a query and then adds/removes labels on every matching message, combining search and batchModify. This distinguishes it from sibling tools like gmail_search_emails (search-only) and gmail_apply_labels (label-by-IDs). The verb+resource+scope is specific and unambiguous.

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

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

The phrase 'Use for bulk tagging of a query' provides direct guidance on when to use the tool. The description also implies it is the right choice when you need to apply labels to search results, as opposed to labeling specific message IDs. It doesn't explicitly name alternatives or exclusions, but the context is clear enough.

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

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

Beyond the annotations, the description discloses important behavior: PII tokens are restored before saving, secrets remain redacted, it syncs to Apple Mail's Drafts via IMAP, and it returns a self-minted Message-ID and deep links. The 'Does NOT send' caveat explicitly clarifies side effects. This is genuinely helpful context that annotations alone do not 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?

Three dense sentences deliver the purpose, required inputs, behavioral caveats, and return value hints without wasted words. The most important action verb is front-loaded, and every sentence contributes meaning.

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 reasonably complex, but the description covers the core workflow: inputs from a prior read, token restoration, redaction persistence, threading, IMAP sync, return artifacts, and the no-send caveat. An output schema exists, so the return-value details are not strictly required in prose, and the description still summarizes them enough for an agent to know what to expect.

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

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

The schema coverage signal is 0% for the top-level params object, so the description compensates by mapping the original message fields ('from', 'subject', 'threadId', 'message_id') to the required inputs and explaining the PII-token handling. It does not mention the optional 'references' parameter, and exact formats are left to the schema, so it is strong but not exhaustive.

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

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

The description opens with a specific verb+resource: 'Create a threaded REPLY draft to an email in Gmail.' It clearly distinguishes itself from sibling read/search/label tools by emphasizing the draft creation and explicitly stating 'Does NOT send.' This leaves no ambiguity about the tool's primary function.

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

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

The description gives concrete usage direction: 'Pass the original message's from/subject/threadId/message_id plus your composed reply body.' It also explains when it is not appropriate by noting 'Does NOT send,' which helps differentiate from a send operation. It stops short of naming alternatives or explicitly saying 'use X instead,' so it gets a 4 rather than 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 confirm read-only, idempotent, and non-destructive behavior. The description adds valuable context by mentioning that bodies pass through the masking layer, which is an important privacy/security behavior not captured by annotations. It also notes that bodies are decoded, adding insight beyond the schema.

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

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

The description is two sentences with no filler. It front-loads the core purpose and includes necessary specifics (order, headers, decoded body, masking) in a compact structure.

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

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

With an output schema present and strong annotations, the description covers the essential aspects: thread-level scope, message ordering, headers, body decoding, and masking. It is complete for a straightforward read operation.

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

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

The description mentions 'by thread ID' but does not elaborate on the format, origin, or constraints of the thread_id parameter. The input schema provides a clear explanation, but since the context signal indicates low schema coverage (0%), the description's contribution is minimal. The parameter is simple enough that the description's mention is adequate but not rich.

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 verb 'Fetch' and the resource 'full Gmail thread by thread ID', with specifics about ordering, headers, and decoded plaintext body. It distinguishes itself from sibling tools like gmail_search_emails (search) and gmail_batch_read_email (batch individual messages) by focusing on thread-level retrieval.

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 implicitly conveys when to use the tool: when you have a thread ID and need the complete conversation in order. However, it does not explicitly mention alternatives or exclusions, such as using gmail_batch_read_email for individual messages or search tools for finding 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 declare readOnlyHint=true and idempotentHint=true. The description adds behavioral value by specifying the return shape ('message IDs plus a pagination token') and a performance characteristic ('Cheaper than gmail_search_emails'). It does not mention auth or rate limits, but the annotations cover safety adequately.

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 focused sentences: the first states the action and result; the second provides cost trade-off and read-only note. Every word earns its place, and the most important information is front-loaded.

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

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

For a straightforward search tool with rich annotations and an output schema, the description fully covers the essential context: what it returns, when to use it over the sibling, and its safety profile. The pagination mechanism is inherited from the schema, and the output schema presumably documents the return structure.

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

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

The description itself does not explain parameters, but the schema provides thorough descriptions for query, page_token, and max_results. Since schema coverage is effectively 100%, the baseline of 3 applies; the description's reference to 'pagination token' simply reinforces the page_token parameter without adding new 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?

The description states 'Search Gmail and return only message IDs plus a pagination token' with a clear verb and resource. It also distinguishes itself from the sibling tool gmail_search_emails by noting it is 'Cheaper than gmail_search_emails when you only need IDs', making the purpose unambiguous.

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

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

Explicit guidance is provided: 'Cheaper than gmail_search_emails when you only need IDs to feed into gmail_batch_read_email or gmail_apply_labels.' This names specific alternatives and the exact scenario in which this tool should be chosen over the sibling.

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, destructiveHint=false, idempotentHint. The description adds useful behavioral context beyond annotations: it returns compact summaries, supports pagination via page_token, and excludes full bodies. This clarifies the read-only scope and return shape. It does not contradict 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, front-loaded with the core purpose and return payload. Every word earns its place; no fluff or repetition. Ideal size for a tool of this complexity.

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 has 4 parameters and an output schema. The description covers the essential behavior: search, return summaries, pagination, and read-only nature. It does not explain pagination looping or error handling, but the schema and annotations fill gaps. Overall complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 0%, so the description should compensate for parameter details. It only mentions Gmail search syntax for 'query' and pagination for 'page_token', adding some context. However, it does not explain 'tags' or 'max_results' beyond what the schema already provides. Since the schema itself has thorough descriptions, the addition is minimal but not harmful.

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

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

The description uses a specific verb ('Search Gmail') and resource, and clearly states what it returns (compact message summaries with listed fields). It distinguishes from sibling gmail_search_email_ids by noting it returns summaries, not just IDs, and from thread-reading tools by explicitly saying it does not return full bodies.

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 to use Gmail search syntax and mentions pagination, giving clear operational context. The 'does not return full bodies' implies using a different tool for full content, but it does not explicitly name alternatives like gmail_read_email_thread or gmail_batch_read_email. This is clear but not fully explicit.

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

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

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds valuable context about the channel membership requirement and the expected error if the bot is not invited, going beyond the annotations.

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

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

Three concise sentences, each earning its place: the action, the usage context, and a key prerequisite/error note. No redundant or filler content.

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

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

For a simple posting tool, the description covers purpose, usage timing, and a critical operational requirement. The output schema is present, so there is no need to describe return values, making the description complete.

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

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

The description does not discuss parameters, but the input schema comprehensively describes both 'text' (required) and 'channel' (optional). Since the schema carries the parameter semantics, the description does not need to repeat them; baseline 3 is appropriate.

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

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

The description clearly states it posts a message to Slack via chat.postMessage, with a specific verb and resource. It also frames the use case (delivering a final report after email/calendar processing), which distinguishes it from the sibling Gmail/calendar 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?

The description explicitly says 'Use this to deliver the final report after processing emails and registering calendar events,' giving clear when-to-use context. It also mentions the prerequisite that the bot must be a member of the channel, which is important operational guidance.

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