Nilyo

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

Although annotations already mark destructiveHint: true, the description adds substantial behavioral detail: the free and immediate effect during trial, prorated charging on the saved payment method for active subscriptions, the confirm requirement, and the one-click Stripe confirmation link. This goes far beyond the generic annotation and gives the agent the necessary caution.

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

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

The description is compact, front-loads the core action, and packs conditional behavior, confirmation flow, and use cases into about four sentences. It is slightly longer than strictly necessary but every sentence carries operational information, so 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 mutating billing tool with no output schema, the description covers the essential operational aspects: trial vs. subscription behavior, the confirm gate, plan/interval changes, and typical use cases. It does not explicitly describe the result of the confirm=true call or error conditions (e.g., missing payment method), but it is sufficient for safe 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% and each parameter is already well documented, including confirm's behavior and interval's annual discount. The description restates the confirm workflow in narrative form but does not introduce new parameter semantics beyond the schema, so the 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 opens with a specific action and resource: 'Change the user's plan (Personal, Personal Plus, Team) or billing interval.' It then lists concrete use cases ('Use when a second account of a provider needs Personal Plus...') that distinguish it from sibling tools like account_start_subscription and team_add_seats, even though it does not name them explicitly.

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

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

The description explicitly states when to use the tool ('Use when a second account of a provider needs Personal Plus, when the user wants Team for colleagues, or asks to switch monthly/annual') and prescribes a two-step invocation sequence (call without confirm, then with confirm after approval). It lacks explicit when-not-to-use guidance or named alternatives, so it stops short of a 5.

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

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

Annotations are all-false hints, so the description carries the burden, and it adds real behavioral context: the tool returns a provider-owned auth link, requires no user password, and is a browser fallback. It does not detail side effects like link expiry or whether initiating re-auth revokes the old session, but the core behavior and security stance are clearly disclosed. There is no contradiction with 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?

Every sentence adds a distinct fact: purpose, trigger, re-auth condition, sibling routing, and password prohibition. It is dense but not bloated, and the main purpose is front-loaded before caveats. The length is proportionate to the tool's branching cases.

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 2-param tool with no output schema, the description covers providers, re-authentication, sibling alternatives, and security guidance; the returned 'link' is identified even if its shape/expiry is not. It could note the imap_connect sibling as an alternative, but nothing essential for correct invocation 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?

Although schema coverage is 100%, the description substantially enriches both params. It maps account_id to the concrete unipile_account_id from list_connected_accounts and explains that omitting it creates a new account, and it clarifies the 'email' vs 'imap' enum distinction. This goes well beyond the schema's property 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?

The description opens with a specific verb and resource: 'Get a secure connection (or reconnection) link' for listed providers, and explicitly names sibling alternatives (whatsapp_connect, telegram_connect) to differentiate. The provider list and the re-authentication clause make the tool's exact role unmistakable. It clearly distinguishes from siblings rather than merely restating the name.

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 exactly when to use it ('when the user asks to connect/add/reconnect an account'), when to pass account_id, and when not to use it (prefer whatsapp_connect/telegram_connect for QR in-conversation). It also gives a hard rule: never ask for provider passwords. This is explicit routing with no reliance on 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns pending with a QR code or pairing code that refreshes when changed, and it explicitly instructs polling behavior. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded: it states the purpose, the return states, the polling cadence, and the parameter behavior in three sentences. Every sentence earns its place with no 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?

For a simple read-only status tool with one optional parameter and no output schema, the description covers the essential workflow: what statuses to expect, how to poll, and what to do when connected. It doesn't describe the exact structure of the QR code or pairing code fields, but that is minor given the tool's simplicity and the annotations covering safety.

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, and the description adds meaning by explaining that intent_id is the value returned by whatsapp_connect/telegram_connect and that omitting it checks the latest attempt. This clarifies the parameter's provenance and default behavior beyond the schema's simple description.

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 checks the status of an in-conversation WhatsApp/Telegram connection initiated by whatsapp_connect or telegram_connect. It names the specific resource (connection status) and the possible return states, distinguishing it from the connect tools and other account 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 tells the agent when to use this tool: poll every 10-20 seconds until status is connected, then retry the user's original request. It also explains how to handle the optional intent_id parameter, saying to omit it to check the most recent attempt. This is clear operational 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuine data-boundary disclosure — 'Never exposes payment details' — plus the implicit scope that it targets only the authenticated user, which is useful context 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?

Two sentences, front-loaded with what is returned and followed by when to use it; the field enumeration is long but each item earns its place by telling the agent what it can answer without a follow-up call. Slight density cost from the parenthetical billing-action list.

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 carries the return-value burden and does so by enumerating the returned fields and listing the billing actions surfaced. Combined with the explicit usage triggers and the payment-data exclusion, 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing parameter-level for the description to clarify or miss.

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 ('Show') and resource (the authenticated Nilyo user's account/subscription state), then enumerates the exact contents: login email, plan, trial/subscription status, limits, seats, members, and billing actions. It reads clearly against adjacent siblings like account_connection_status or list_connected_accounts but never names them, so differentiation is left to inference.

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 unusually rich trigger conditions: verifying which login the agent is connected to, user questions about plan/trial/price/seats/team, diagnosing a blocked action, or before proposing an upgrade. It stops short of naming alternative tools or stating when not to use it, which keeps it out of the top band.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds useful behavioral context beyond annotations: it filters to disconnected accounts and returns an empty list when healthy, which clarifies the tool's effect and output semantics.

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 of purposeful prose. It front-loads the core purpose, then adds the empty-list behavior, with no filler or repetition.

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

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

For a zero-parameter, read-only tool with rich annotations, the description is complete: it states what is listed, why, and what an empty result means. No schema or output details are needed to select or invoke 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?

There are zero parameters and schema description coverage is 100%, so the description carries no parameter burden. Per the baseline for zero-parameter tools, this is a solid score; the description also clarifies what the returned list represents.

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 and resource: 'List the user's connected accounts that currently need re-authentication (status disconnected)'. It clearly distinguishes this from broader account tools like list_connected_accounts and account_connection_status by focusing on the re-authentication need.

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

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

The description gives clear context: use it proactively to offer reconnection before a request fails. It does not explicitly name alternatives or state when not to use it, but the use case is well implied by the 'proactively offer to reconnect' framing.

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 it's a mutating operation (destructiveHint=true). The description adds value by explaining it returns Stripe checkout links (so the actual payment happens externally), and notes the presentation behavior ('Present monthly and annual options; default to the current plan'). This goes beyond the annotations without contradicting them.

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

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

The description is compact yet informative. Each sentence earns its place: it opens with the core function, then usage conditions, then the alternative, then presentation preferences. No fluff, though it could be slightly tightened.

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

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

For a tool with an output schema absent, the description explains what it returns (checkout links) and when to use it. It also covers edge cases (trial, expired, lapsed) and defaulting. The only minor omission is a description of the actual response structure, but that's not required given the tool's simplicity.

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% — both 'plan' and 'interval' are fully described in the schema. The description adds some behavior guidance (e.g., 'default to the current plan'), but this is about tool behavior rather than parameter semantics, so it stays at the baseline 3.

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 verb and resource: 'Return Stripe Checkout links ... to start or restore the paid subscription.' It also distinguishes itself from the sibling account_change_plan, making its unique purpose obvious without reading 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?

Explicit when-to-use is given: 'Use after a subscribe result or when the user asks to subscribe/pay/upgrade before having a subscription.' It also provides an exclusion: 'If the user already has an active Stripe subscription, use account_change_plan instead.' This is a model of clear routing.

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, idempotentHint=true, and destructiveHint=false, so the safe, non-mutating nature is fully covered. The description adds no behavioral detail beyond saying it returns recipes and rules, which is consistent but not extra disclosure.

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

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

The description is a single sentence followed by a focused 'Use when' list. It front-loads the purpose and then gives concrete examples without redundancy or filler.

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

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

For a simple read-only guide tool with one optional parameter and rich annotations, the description fully covers what the tool returns and when to invoke it. No output schema exists, but the return content (recipes and chaining rules) is described sufficiently for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, and the single optional 'workflow' parameter is already clearly documented in the schema as 'Optional workflow name; omit to return all recipes.' The description doesn't need to add more, and it doesn't.

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 ('Return') and a specific resource ('Nilyo's agent workflow recipes and chaining rules'), and then enumerates concrete use cases such as resolving LinkedIn URLs to provider user IDs and finding a chat before replying. This clearly distinguishes it from sibling tools like agent_id_guide and general LinkedIn lookup 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 when you need to know how to...' and lists several concrete scenarios, giving an agent clear triggers for invocation. It does not explicitly name alternatives or when not to use it, so it stops short of a full 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds substantive behavioral context beyond this: the guide is 'authoritative', it explains 'exactly which previous tool produces each ID', and it warns that 'lookalike values must NOT be passed'. This tells the agent what kind of content and constraints the tool returns, which is meaningful additional disclosure.

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

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

Two sentences with no filler. The main action ('Return the authoritative Nilyo ID semantics guide') is front-loaded, followed immediately by usage context, and then content scope. Every clause earns its place and the description remains skimmable despite covering many ID categories.

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 reference tool with one optional enum parameter and no output schema, the description covers the resource, when to use it, and what it contains. The main missing piece is how the 'id_type' parameter affects the returned content—whether it filters the guide or is required. This is a notable but non-critical gap given the tool's simplicity and the annotations already covering safety and idempotency.

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 for the lone 'id_type' parameter. It groups the ID types into human-readable categories ('inbox/contract ID', 'email/thread/folder/attachment ID', etc.), which maps helpfully onto the enum values. However, it never explains the parameter's actual behavior—that passing a specific id_type filters the guide and that omitting it returns the full guide. This is a significant gap given zero schema coverage.

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 and resource: 'Return the authoritative Nilyo ID semantics guide.' It makes the tool's function immediately clear and enumerates the ID types covered. However, it does not differentiate itself from the sibling tool 'agent_capability_guide', which is also a guide-style tool, so it falls short of a full 5.

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

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

The description explicitly states when to use the tool: 'Use this when unsure whether a tool needs a LinkedIn system user ID, public identifier, request ID, ...' This is clear contextual guidance. It does not, however, state when NOT to use it (e.g., when the ID type is already certain) or name any alternative tools, so it does not fully meet the 5-level 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 already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is structured. The description adds valuable behavioral context beyond annotations: it notifies attendeescias a side effect, only applies to events organized by the connected account, and warns to confirm before acting. This enriches the safety profile without contradicting 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?

The description is two sentences with no filler. The primary action and scope come first, followed by a concise differentiator and a practical caution. 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 destructive, non-idempotent operation, the description covers the key context: what it cancels, its side effect, how it differs from the delete sibling, and a confirmation warning. With no output schema, it doesn't need to explain returns. The main small gap is that it doesn't mention parameter prerequisites, but those are thoroughly handled in the schema, so overall it is nearly complete.

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

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

The tool description itself does not add parameter semantics, but the input schema covers 100% of the parameters with detailed descriptions (e.g., event_id says how to obtain it and never pass a title/date; calendar_id warns against names). Since the schema already documents param meaning, a baseline of 3 is appropriate—no extra value is needed or 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 states a specific verb ('Cancel') with a clear resource ('an event organized by the connected account') and a distinct side effect ('notify attendees'). It also explicitly differentiates from the alternative 'deleting an event only from the user's calendar', which aligns with the sibling calendar_delete_event. This leaves no ambiguity about the tool's 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 an explicit when-to-use: cancel events organized by the connected account when attendees should be notified. It also names the alternative scenario ('deleting an event only from the user's calendar') and adds a caution to 'confirm the exact event before cancellation', which guides safe 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 a non-read-only, non-idempotent mutation. The description adds the provider scope but does not disclose further behavior such as duplicate handling, immediate visibility, or external side effects. There is no contradiction with annotations, but the description contributes little beyond the obvious creation action.

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 wasted words. The core action is front-loaded in the first sentence, and the usage guardrail is in the second. Perfectly sized for the tool's simplicity.

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 creation tool with annotations covering the write nature, the description plus the detailed account_id parameter guidance are sufficient to invoke the tool correctly. The only notable omission is any indication of the return value, but no output schema exists, so this is a minor 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 description itself does not expand on individual parameters, but the schema already covers 3 of 5 parameters (timezone, account_id, background_color) with descriptions. The remaining parameters, name and description, are self-explanatory. The account_id parameter description is especially rich, providing operational guidance beyond basic 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 a specific verb ('Create') and resource ('calendar') with the account scope ('selected Google or Microsoft account'). It explicitly differentiates from the sibling calendar_create_event by adding 'not merely an event,' so an agent can immediately tell which creation tool is appropriate.

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 a clear when-to-use condition: 'Use only when the user explicitly asks for a new calendar, not merely an event.' Additionally, the account_id parameter description gives detailed guidance on when to omit versus when to list accounts and ask, preventing incorrect multi-account selection.

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 a behavioral guarantee ('preserve timezone and all-day semantics instead of guessing them'), which is useful. Annotations already cover mutability and non-idempotency, so the description adds a bit of extra context but not extensive behavior like side effects or response 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?

Two sentences, front-loaded with the main purpose, and no wasted words. The required fields and behavioral note are efficiently stated.

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 complex tool with 16 parameters and nested objects, the description is sparse. It does not cover optional parameters or return expectations, though the schema has some descriptions and the behavioral note about timezone/all-day helps. Still, an agent may lack guidance on many optional fields.

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?

Description mentions only required parameters (title, attendees, start, end) and a timezone note, but does not explain the many optional parameters (location, conference, recurrence, visibility, etc.). With schema coverage at 31%, it fails to compensate for the gaps, adding minimal value beyond the schema's own descriptions.

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

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

States a specific verb (Create), resource (event), and scope (one resolved calendar), clearly distinguishing from calendar_create_calendar and calendar_update_event. It also mentions required fields and a behavioral nuance, making the purpose unmistakable.

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?

Implies usage for creating events; does not explicitly compare with siblings like calendar_update_event or calendar_cancel_event, but the purpose is clear and no exclusions are needed. The 'one resolved calendar' hint suggests it is not for multi-calendar operations.

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 destructiveHint=true and readOnlyHint=false, and the description reinforces this by stating 'This is destructive'. It adds valuable context beyond annotations by instructing the agent to resolve and confirm the calendar and to never infer the ID, which is a critical behavioral guardrail not expressed in the schema or 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 zero redundancy. The action is front-loaded, and the safety warning follows immediately. Every word earns its place; no filler or vague language.

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 destructive delete tool with no output schema, the description adequately covers the key risks (destructive nature, ID resolution) and the required parameter. It doesn't describe return values, but none are expected. The inclusion of the confirmation guidance makes it complete enough for an agent to use 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%, and the schema already explains the calendar_id parameter, including how to obtain it and never pass a display name. The description reiterates the 'never infer' warning but adds no new parameter semantics beyond what the schema provides. Baseline of 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 the verb 'Delete' and the resource 'one exact calendar', which distinguishes it from sibling tools like calendar_delete_event. It also adds the qualifier 'exact' to set precision expectations. This is specific and unambiguous.

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

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

The description does not explicitly name alternatives or when-not-to-use, but it provides critical usage guidance: resolve and confirm the calendar before deleting, and never infer the ID from its display name. This gives clear context for safe invocation, even though it doesn't contrast with siblings.

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 destructiveHint=true and idempotentHint=false. The description adds context beyond annotations: deletion is scoped to the connected account's calendarasi and the parent calendar_id must be preserved. This provides useful operational detail without contradicting 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?

The description is two sentences, front-loaded with the action, and every phrase carries weight. It avoids repeating schema content, delivering only the essential behavioral scope and caution in 26 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 destructive three-parameter tool with no output schema, the description combined with the rich parameter schema and annotations covers all necessary details: the event to delete, the required IDs, and the scope. The account_id parameter is fully explained in the schema. No critical contextual gap exists.

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 each parameter is thoroughly documented (event_id must be exact and never a title/date; calendar_id must be exact and never a name; account_id is optional for single-account contexts). The description's mention of preserving calendar_id reinforces the schema but adds minimal new meaning. 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?

The title and description clearly state the action ('Delete') and the resource ('resolved calendar event'). The phrase 'removes it only from the connected account's calendar' distinguishes this tool from siblings like calendar_cancel_event or calendar_delete_calendar, clarifying it deletes a specific event instance within a single account.

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 by specifying 'resolved' event and the scope (only from connected account's calendar), but it never explicitly names alternatives or states when not to use this tool. The caution to 'Confirm the intended event' is a usage note, but no direct comparison to calendar_cancel_event or calendar_restore_event is made.

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, idempotentHint, and destructiveHint, so the description only needs to add behavioral nuance. It adds the requirement of an exact ID and the warning not to pass a display name. It does not detail error behavior or return format, but the safety profile is fully covered by 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 tight sentences with no filler. The key constraint (exact ID, not display name) is front-loaded, and 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 simple read-only get-by-id operation, the description, schema, and annotations together provide enough to call it correctly. It does not describe the return value, but that is typically inferred for a 'get' operation and the absence of an output schema does not create ambiguity.

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 schema already documents both parameters. The description reinforces the calendar_id semantics (exact ID, obtain via list, never display name) but adds little beyond the schema's own text. This matches the baseline 3 for high coverage.

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

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

The description states a specific verb and resource ('Get one calendar') and immediately scopes it to 'the exact ID returned by calendar_list_calendars', which distinguishes it from the listing sibling. It also explicitly warns against passing a display name, preventing misuse.

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

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

The description gives clear context: use the exact ID from calendar_list_calendars, and explicitly forbids passing a calendar display name. It does not name alternative tools or explain when to prefer this over other calendar operations, but the prerequisite and constraint are unambiguous.

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, idempotentHint, and a non-destructive operation, so safety is covered. The description adds a useful pairing/identification constraint and warns against title/date lookup, but it does not disclose not-found behavior or any provider-specific response details. This is moderate added 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?

Two short sentences with the core action and required IDs front-loaded, followed by a critical guardrail. There is no filler, repetition, or unnecessary detail.

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 get-by-ID tool, the description plus the fully documented input schema and safety annotations give an agent everything needed to invoke it correctly. The return value is evident from the name and operation type, and no side effects need disclosure. Not-found behavior would be a nice addition but is not essential 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%, and each parameter description already documents exact ID sources, pairing, and the rule to never pass titles or dates. The tool description's mention of exact parent calendar_id and event_id restates the schema relationship without adding new semantics. 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 states a specific verb ('Get'), the resource ('one event'), and the required identifying pair (exact parent calendar_id and event_id). This clearly distinguishes the tool from siblings like calendar_list_events and calendar_get_calendar. The negative instruction about not using title or date sharpens the purpose even 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?

The description gives a clear when-to-use condition: call this only when both exact calendar_id and event_id are available. It also gives an explicit when-not: never identify an event only by title or date. It does not name sibling tools or point to calendar_list_events/calendar_create_event as ID sources, though that information appears in the schema.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context about supporting Google/Microsoft accounts and the requirement to use the returned calendar.id rather than a display name, which 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?

Two sentences with no filler. The core action is front-loaded, and the critical usage constraint (use calendar.id, not display name) follows immediately. 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 simple read-only list tool, the description covers the essential workflow: list calendars, use the returned id, and pass account context when needed. It does not describe pagination or response shape, but those are partially inferable from the parameter names, and annotations carry the safety-related context.

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 only 25%: account_id is richly documented, but limit, cursor, and offset have no descriptions. The main description reinforces the connection between the tool and account_id but does not explain pagination parameter behavior, leaving those parameter semantics to be inferred from their names.

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

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

States a clear action and resource: 'List calendars for the connected Google or Microsoft account.' It also explains the purpose of the result ('Use the returned calendar.id before listing, creating or updating events'), which differentiates it from sibling calendar tools like calendar_get_calendar or calendar_list_events.

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 practical routing guidance: obtain a calendar.id from this tool before listing, creating, or updating events, and never pass a display name as calendar_id. It does not name sibling alternatives explicitly, but the 'use before...' pattern clearly positions this tool as the entry point for calendar operations.

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 cover read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds useful context about 'one resolved calendar' and the event.id workflow. However, it does not disclose pagination behavior, filtering defaults, or output shape, leaving some behavioral gaps.

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

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

Two sentences, no fluff, and the core action is front-loaded. Every phrase earns its place: the verb, the resource scope, and the intended workflow are all present without 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?

With 18 parameters and no output schema, the description is far from complete. It gives a clear purpose but leaves search semantics, filter usage, pagination, account disambiguation, and return values unexplained. The low schema coverage makes this a significant gap for an agent trying to use the tool correctly.

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

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

Schema description coverage is only 22%, and the description adds no parameter-level meaning beyond the purpose. Many parameters such as busy, limit, title, cursor, offset, and event_type are left undocumented. The description does not compensate for the low schema coverage, making it hard for an agent to know which filters to use.

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

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

The description states a specific verb and resource: 'List or search events inside one resolved calendar.' It also clarifies the primary use case: 'obtain event.id before reading, updating or deleting an event,' which clearly distinguishes this tool from event mutation tools and calendar listing 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 tells the agent when to use this tool: before reading, updating, or deleting an event. It implies the tool is for working within a single resolved calendar, setting a clear prerequisite. It does not name an alternative like calendar_get_event, but the intended workflow 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?

Annotations indicate this is not read-only and not idempotent, but the description adds valuable behavioral context: the restore depends on Google's retention of the cancelled event, and Outlook should surface an error rather than be handled with a fallback. This goes beyond the structured annotations without contradicting them.

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 compact sentences with no filler. The core action and object are front-loaded, followed by the necessary provider and error-handling constraints, making it easy for an agent to parse quickly.

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?

Together with the fully detailed input schema, the description covers the action, provider availability, a time-based precondition, and failure behavior for an unsupported provider. The absence of an output schema is not a major gap for a simple restore operation, though a bit more detail about the response could push it higher.

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 provides detailed semantics for event_id, calendar_id, and account_id, including exact ID requirements and never-pass guidance for titles/names. The description does not add parameter-specific detail, so the baseline of 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 uses a specific verb ('Restore') and resource ('event previously cancelled by the connected organizer'), which clearly identifies the action and distinguishes it from sibling tools like calendar_cancel_event and calendar_delete_event. The provider scoping ('Google Calendar') further sharpens the intended 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 explicitly states when this tool can be used: only for Google Calendar and only while Google retains the cancelled event. It also gives direct guidance for Outlook by instructing the agent to report the provider error without substituting another action, which 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?

The description warns that 'declining can remove the event from their calendar,' which directly contradicts the annotation destructiveHint=false. Even though it adds useful caveats about Outlook organizers and account scope, the contradiction undermines the agent's ability to trust either signal.

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 contain all essential guidance with no filler. The main action is front-loaded, and the important caveat about Outlook organizers follows immediately.

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 scope, prerequisites, and provider-specific caveats, which is strong for an RSVP tool. It omits return-value details, but there is no output schema and the mutation semantics are reasonably clear.

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 60% schema coverage, the description adds useful context by mapping the action to status values and emphasizing the connected-account restriction, which relates to account_id. However, it does not explain the comment parameter or add much beyond the existing schema descriptions for event_id and calendar_id.

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

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

The description states a clear, specific verb-resource pair: accept, tentatively accept, or decline an invitation. It also immediately scopes the action to 'the connected account only,' which helps distinguish it from other calendar mutation tools like calendar_cancel_event or calendar_update_event.

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 actionable usage prerequisites: resolve the event first and avoid using this tool for Outlook organizers. It clearly notes a limitation but does not explicitly name sibling alternatives or contrast with them.

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

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

With annotations providing readOnlyHint=false, destructiveHint=false, and openWorldHint=true, the description adds value by specifying that only 'explicit fields' are updated, implying partial updates and not destructive behavior. It also instructs to 'pass only changes requested by the user,' which is behavioral context not in annotations. No contradictions found.

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 concise: two sentences, front-loading the core action and key guideline. It avoids redundancy with the schema but also omits some potentially useful info like example updates. However, it is efficient and well-structured for its 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?

Given the tool's complexity (6 parameters, mutation, no output schema), the description provides essential context: resolve calendar_id first, pass only changes, and rely on schema for param details. It could mention what fields are updatable or consequences, but the schema covers field details. Missing return info is minor since no output schema exists, but the tool's function is clear.

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 67%, meaning most parameters have descriptions, including important guidance on account_id and calendar_id. The description reinforces that calendar_id must be resolved and only changes passed, which adds value beyond the schema. For parameters without descriptions like name and description, the description's general context compensates reasonably.

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 'Update explicit fields on an existing calendar,' which is a specific verb and resource. It clearly indicates this tool is for modifying a calendar, distinguishing it from sibling tools like calendar_create_calendar and calendar_delete_calendar. The description also emphasizes passing only user-requested changes, which adds clarity.

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: resolve calendar_id first and pass only changes requested by the user. It implicitly guides when to use this tool (when updating existing calendars) but does not explicitly state when not to use it or mention alternatives like calendar_update_event. However, the instruction to resolve calendar_id is a strong usage guideline.

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 state non-read-only, non-idempotent, and non-destructive behavior. The description adds value by specifying that only explicit fields are updated (behavioral detail not in annotations) and by warning against retrying after ambiguous failures, which indicates partial-application risk. These traits are 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?

The description is two sentences: the first states the primary purpose, the second gives two critical operational warnings. It is front-loaded and concise with no filler or redundant 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 mutation tool with 17 parameters, no output schema, and low schema coverage, the description is too sparse. It does not explain return values, how unspecified fields are treated, provider-specific behaviors (only the notify parameter hints at Google-specificity), or account selection steps. The two warnings are helpful but insufficient for complex edge cases.

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 only 35%, so the description should compensate. However, the only parameter-related guidance (event_id paired with calendar_id) is already present in the schema's event_id description. No additional meaning is provided for the other 15 parameters, such as start, end, attendees, or recurrence.

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 'Update explicit fields on a resolved event' with a specific verb and resource, and the 'resolved' qualifier distinguishes it from creation and other calendar operations. This clearly differentiates it from siblings like calendar_create_event and calendar_update_calendar. The phrase 'explicit fields' also signals a partial update rather than a full overwrite.

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 after resolving an event (by mentioning 'resolved event') but does not explicitly contrast with alternatives like calendar_create_event or calendar_cancel_event. It gives operational guidance (pairing event_id with calendar_id, avoiding blind retries) but lacks an explicit when-to-use or when-not-to-use statement, leaving some inference to the agent.

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, destructiveHint=false, and openWorldHint=true, so the mutation/non-idempotent profile is covered. The description adds the useful 'Resolve chat_id independently from user_id' constraint, but says nothing about what happens when the user is already a participant, notification behavior, or permission requirements.

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

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

The purpose is front-loaded in the first clause, which is good, but the remainder is a dense run-on that repeats schema content verbatim (chat_id definition, 'Never pass' lists) and mixes chat-ID and user-ID guidance without clear separation. It is informative but not tight.

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 and a mutation tool, the description thoroughly covers identifier resolution but omits outcome behavior: success/failure semantics, idempotency effects, or what the caller gets back. Adequate for calling the tool, but incomplete for predicting its effects.

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 parameters are already documented in the schema — including much of the same 'Obtain with'/'Never pass' text that appears in the description (a notable duplication in chat_id). The description adds marginal value via the cross-ID resolution chain, so 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?

States a specific verb+resource+scope: 'Add an exact provider user to an exact group chat.' An agent can immediately distinguish this from chat_remove_participant, chat_list_participants, and messaging_start_chat 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?

The description gives extensive guidance on how to obtain chat_id and user_id ('Obtain with: provider list conversations/inbox chats -> chat.id') and what never to pass, but it never states when this tool should be chosen over alternatives such as messaging_start_chat or messaging_send_message, nor any preconditions. Usage is implied rather than framed as a decision.

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

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

The annotations already declare destructiveHint=true and idempotentHint=false, so the description's 'destructive' label is redundant. However, it adds meaningful context by stating deletion is 'where supported' and instructing the agent to resolve/verify chat_id first, which conveys limited support and a safety precondition beyond the structured 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 relatively concise and front-loaded, leading with the core action and then layering preconditions and identifier guidance. The middle section repeats some schema text, but it serves as a standalone summary. No unnecessary filler is present.

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 destructive tool with no output schema, the description covers the most critical invocation details: what to delete, how to obtain the identifier, and what to never pass. However, it does not explain what happens when deletion is unsupported or on error/response behavior, and the account_id selection guidance is only in the schema, leaving a moderate gap for agents dealing with multiple accounts.

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 repeats the chat_id semantics already present in the schema and does not add new parameter-specific meaning. The account_id parameter is described only in the schema, not in the main description, but the schema itself covers it thoroughly.

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 and resource: 'Delete/remove one exact chat where supported.' It clearly distinguishes this from sibling tools like message_delete by targeting the chat object, and reinforces the resource type by explaining that a chat_id, not a person name, user_id, or message_id, is required.

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

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

The description provides clear usage context: resolve and verify chat_id first, note that this is destructive, and it only works 'where supported.' It also tells the agent exactly what identifiers are unacceptable. It does not explicitly name alternative tools or conditions for choosing a different tool, so it falls 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description clarifies that returned participant user IDs are NOT chat IDs and can be reused for membership operations. This is valuable output-semantics disclosure that annotations 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?

The description is front-loaded with purpose, then gives necessary resolution and output guidance. It is slightly dense and repeats some chat_id text also present in the schema, but every sentence contributes useful 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 simple read-only two-parameter tool with no output schema, the description compensates by explaining output ID semantics and how to resolve the required chat_id. It could mention the response shape more explicitly, but the essentials for correct invocation are 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 description coverage is 100%, so the schema already thoroughly documents chat_id and account_id. The description adds usage emphasis like 'Resolve chat_id first' and 'Never pass...' but does not add substantive parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: 'List members of an exact group/multi-party chat.' It is clearly distinguished from sibling chat operations like adding/removing participants, and the first sentence immediately tells the agent what the tool does.

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

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

The description gives strong usage context: resolve chat_id first, obtain it from conversation listings, and never pass person name/user_id/message_id. It does not explicitly name alternatives, but the prerequisite and ID-type guidance make correct invocation clear.

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 destructiveHint: true, so the agent knows this is a mutation. The description adds context about exact matching and the need to inspect participants, which is useful beyond annotations. However, it doesn't elaborate on side effects (e.g., notifications, irreversibility) or error behavior, so it provides only moderate additional transparency.

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

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

The description is a single focused paragraph that front-loads the purpose and then gives practical warnings. It is not bloated, though it repeats some schema text verbatim, which is slightly redundant but does not hinder readability.

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 removal operation, the description covers the essential: action, exactness, inspection hint, and ID separation. The sibling chat_list_participants provides the inspection path, and annotations cover the destructive nature. It lacks explicit notes on permanent effects, but that is minor given the simplicity.

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 parameter descriptions in the schema are already detailed (including the exact same warnings about chat_id and user_id). The tool description largely repeats this content rather than adding new meaning, so it doesn't compensate beyond the baseline for high schema coverage.

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

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

The description states a precise action: 'Remove an exact provider user from an exact group chat.' It clearly distinguishes from siblings like chat_add_participant (add) and chat_list_participants (list). The verb and resource are specific, and the 'exact' qualifiers prevent ambiguity.

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: 'Inspect participants first when identity is ambiguous' implies using chat_list_participants before removal. Also warns against passing wrong ID types. While it doesn't name sibling tools directly, the usage context is clear and actionable.

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 openWorldHint=true, so the safety profile is covered. The description adds useful ID-handling constraints ('Never pass: person name, user_id, message_id'), but it does not explain what happens when fields like pin_status or archive_status change, nor any permission or reversibility 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?

The description is front-loaded with the purpose and then gives ID guidance in a compact, structured way. Some of the chat_id text duplicates the schema, but overall it is appropriately sized and every sentence is relevant to correct invocation.

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, and the description does not explain the semantics of six of the eight parameters, including the string or boolean forms for muted_until. It covers chat_id acquisition and negative ID constraints well but leaves significant gaps for a mutation tool with many metadata fields.

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 only 25%, so the description must compensate for six undocumented parameters. Instead, it repeats the chat_id guidance that already appears in the schema and adds no meaning for name, label, pin_status, muted_until, read_status, or archive_status. An agent gets no help understanding what values those fields expect or represent.

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

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

The description states a specific verb and resource: 'Update mutable metadata of an exact chat.' It clearly distinguishes the operation from deletion or participant management, though it does not explicitly name any sibling tool. The purpose is clear enough for an agent to know this is a metadata mutation.

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

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

It gives strong ID-resolution guidance: 'Resolve chat_id first; do not use person/user ID' and 'Pass only fields explicitly requested.' It also explains how to obtain the chat ID. However, it does not mention when to use this tool instead of overlapping siblings such as messaging_set_chat_state for chat state changes.

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 readOnlyHint=false and destructiveHint=false, so it is a non-destructive write. The description adds the reply nuance and the requirement to obtain a reply_to_message_id, which is extra context. However, it does not describe side effects (e.g., that the draft is saved to the account and retrievable later) or any authentication requirements. Given the annotations already indicate mutation, the description adds moderate value but not a full behavioral picture.

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

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

Two sentences with no filler. The main action ('without sending') is front-loaded, and the reply guidance is provided efficiently. Every word contributes to clarity.

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 8 parameters and no output schema. The description covers the core action and the tricky reply scenario, but it does not clarify whether html and plain_text can both be provided, the relationship between them, or how the draft is later sent (e.g., via email_send_draft). It also doesn't mention error conditions or the expectation that drafts are stored. For a draft-creation tool with this many parameters, more guidance would improve completeness, but the description is adequate for basic usage.

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 only 25% (account_id and reply_to_message_id have descriptions). The tool description adds context specifically for reply_to_message_id (provider-specific formats and how to obtain it), which is valuable. However, it does not explain the common parameters (to, cc, bcc, html, plain_text, subject) beyond what the schema provides. With low coverage, the description could compensate more, but it only partially does.

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 verb 'Create' and the resource 'email draft', and explicitly notes 'without sending', which distinguishes it from email_send_draft and email_send. It also hints at the reply scenario, making the primary purpose unambiguous even without examining sibling 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 provides specific guidance for the reply case ('If replying, first read the source email...'), which helps when to use this tool with a reply reference. It does not explicitly mention alternatives like email_update_draft or email_send_draft, but the 'without sending' clarification implicitly distinguishes it from send operations. This is useful context though 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to restate these. It adds a useful constraint about parent_id not being a display name, which clarifies parameter behavior. However, it does not disclose potential side effects like duplicate handling or whether the operation is reversible, which would be helpful given it is a mutation.

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 concise: one sentence for purpose and one for the critical parent_id constraint. It is front-loaded with the primary action and contains no filler. Every sentence adds value, making it efficient for an agent to parse.

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 create operation with 3 parameters, the description is adequate. It explains the purpose and the key constraint on parent_id. However, it does not mention what happens when parent_id is omitted (e.g., creates at root level) or what the return value is (since no output schema exists). These are minor gaps given the tool's simplicity and the schema's coverage.

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 67% (parent_id and account_id are described). The description adds a redundant clarification about parent_id being an exact ID from email_list_folders, which is already in the schema. It adds no information about the 'name' parameter. Since the schema already covers most parameters, the description adds marginal value beyond the schema.

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

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

The description clearly states the verb 'create' and the resource 'mailbox folder/label', which distinguishes it from sibling tools like email_delete_folder, email_update_folder, and email_list_folders. It is specific enough to avoid confusion with other email actions, though it could be more explicit about creating a new folder vs. other folder operations.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is the tool for creating folders while others are for updating or deleting, nor does it state any prerequisites beyond the parent_id note. The parent_id note hints at needing email_list_folders, but it does not clarify usage context relative to siblings.

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=true, readOnlyHint=false, and idempotentHint=false, so the description's 'destructive' tag is largely redundant. It does add that the operation affects exactly one draft and that the ID must come from list/create, which helps prevent misuse. It does not mention permanence/irreversibility, but the destructive annotation already signals that risk.

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

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

The description is a single short sentence that front-loads the core action, then adds the necessary input source and a destructive warning. There is no filler or repetition beyond the intentional emphasis on destructiveness.

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 two-parameter destructive tool, the schema and annotations cover parameter semantics and safety, while the description clarifies scope and input provenance. It lacks an explicit note about response/confirmation behavior and does not distinguish from email_trash, but the essentials for correct invocation are present.

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 draft_id as the exact ID from email_list_drafts/email_create_draft with a warning not to use subject or email_id. The account_id schema also provides detailed guidance. The tool description only restates ID provenance and adds no new parameter meaning, 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?

The description starts with a specific verb and object: 'Discard one exact draft.' This clearly identifies the tool as a single-draft deletion operation. It does not explicitly name sibling tools like email_trash or email_delete_folder, but the scope ('exact draft') plus the title make 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?

The description gives a useful usage cue: the draft_id must come from email_list_drafts or email_create_draft, implying the tool is for drafts that already exist. However, it does not explicitly mention when to prefer this over alternatives such as email_trash, nor does it state exclusions. The destructive warning is a caution, not a usage routing.

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 destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds operational caution: 'verify target' and the 'exact' match requirement, plus the explicit ID-type warning. It does not disclose downstream effects (e.g., whether messages inside the folder are deleted), but the annotations carry the primary behavioral burden and the description adds useful safety 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?

The description is three sentences and front-loaded with the core action. The third sentence is long and partly duplicates the schema's folder_id description, but it consolidates the ID-source workflow and the human-name warning into one place. Overall it is dense without being bloated.

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 only 2 params, no output schema, and annotations covering the destructive and read-only profile, the description covers the key prerequisites and the most common failure mode (passing a human folder name). It does not mention account_id, but the schema fully handles that. It also doesn't explain what happens to folder contents, but that is arguably beyond what a delete invocation needs from the description.

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 applies. The description repeats folder_id semantics already in the schema but adds a concise resolution path ('Obtain with: email_list_folders -> folder.id'). It stays silent on account_id, but the schema provides a detailed explanation of when and how to pass it. The description adds marginal value on top of the schema.

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

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

The description opens with a specific verb-resource statement: 'Delete one exact mailbox folder/label.' The qualifier 'one exact' and the focus on folder/label clearly distinguish it from sibling tools like email_trash (messages), email_delete_draft, and email_update_folder. It also signals that resolution is a separate concern, differentiating from email_resolve_folder.

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 clear prerequisite workflow: 'Resolve folder_id first and verify target.' It also gives a strong negative constraint: 'Never pass: human folder name such as Inbox when an ID is required.' While it doesn't explicitly name alternative tools or state when not to use this tool, the context of the email_* siblings and the ID-resolution guidance make usage conditions clear.

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 cover readOnly/idempotent/non-destructive, so safety needs no restating. The description adds a genuinely behavioral fact not in the annotations: on IMAP/Exchange-over-IMAP the email id encodes folder+UID and CHANGES when the message is moved or a draft updated, so ids must be reused from the last operation. It does not describe the returned payload (bytes vs. URL vs. base64), which is the remaining behavioral gap.

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

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

The purpose is front-loaded, but the body is heavy and repetitive: 'Email provider ID: Exact email ID returned by Nilyo...' and the IMAP id-instability sentence appear verbatim in both the description and the schema, and the never-pass lists are restated multiple times. A tighter statement of the chain and the one non-obvious caveat would carry the same information in half the space.

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 two-id retrieval tool with full schema coverage and read-only annotations, the input side is well covered. The gap is the output: with no output schema, the description never says what retrieval yields (raw bytes, a signed URL, base64, a saved file path) or how large attachments are handled, which an agent needs to act on the result.

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 largely reproduces the schema text, so the baseline is 3. It earns an extra point for presenting the cross-parameter workflow ('resolve/list -> email_id -> read -> attachment.id -> retrieve') as a single ordered chain, which clarifies the dependency between the two required ids in a way the per-field schema text does not.

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 opening sentence gives a specific verb and resource ('Retrieve one exact attachment') plus the provider scope (Gmail, Outlook/Microsoft, IMAP), which is enough to separate it from generic read/list tools. However, it never names the sibling it pairs with (email_read_message) or states the contrast explicitly, so the differentiation is inferred from the required chain 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?

The 'Required chain: resolve/list email -> email_id -> read email -> attachment.id -> retrieve' tells the agent exactly what must happen before invoking, and the repeated 'Never pass' clauses (filename, URL, RFC Message-ID, subject, stale IMAP ids) are explicit exclusions. This is about as prescriptive as a usage section gets.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds minimal behavioral context beyond this, such as 'one exact draft' implying a single-resource getter, but no additional side-effect or error behavior is disclosed. Since it does not contradict annotations and adds a small amount of context, a 3 is appropriate.

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 zero filler: it states the core purpose first, then the critical constraint. All information is front-loaded and every word earns its place, making it highly scannable for an agent.

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 getter tool with rich annotations and complete schema coverage, the description is nearly sufficient. It does not explicitly state the return format or error behavior, but the presence of annotations and the tool's straightforward pattern make these gaps minor. An agent can confidently call this tool with the provided ID and account context.

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 schema fully documents both draft_id and account_id, including the instruction that draft_id must come from email_list_drafts/email_create_draft and the account selection logic. The description repeats the draft_id source constraint but adds no new information beyond the schema, fitting the baseline of 3 when 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 'Get one exact draft' uses a specific verb and resource, clearly distinguishing it from sibling tools like email_list_drafts (which lists drafts) and email_get_thread (which retrieves a thread). It also adds a precise scoping constraint by stating the draft_id source and excluding subject/email_id, making its unique 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?

The description explicitly instructs that draft_id must come from email_list_drafts or email_create_draft and never from subject/email_id, which is a strong usage rule that prevents common misidentification. However, it does not explicitly contrast with alternatives like email_get_thread or email_read_message, though the source constraint implicitly routes the agent to the correct sibling for listing drafts.

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, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds the exactness and ID-resolution constraint, but doesn't describe error behavior or return shape, which matters because there is no 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?

The description is short and front-loads the core purpose, then gives the resolve-first rule and the 'never pass a human folder name' caution. It has some redundancy with the schema, but every sentence still contributes actionable guidance; the missing punctuation after 'folder.id' is a minor readability flaw.

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 read operation, the description plus schema and annotations cover the required folder_id format, where to obtain it, and the optional account_id selection rule. There is no output schema, so a brief note on return value or not-found behavior would make it fully complete.

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

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

Schema description coverage is 100% and the description largely repeats the folder_id schema text ('Exact Gmail label... Obtain with email_list_folders -> folder.id'). It therefore doesn't add meaning beyond what the input schema already provides, so the baseline of 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?

Description uses a specific verb ('Get') and a clearly bounded resource ('one exact Gmail/Outlook/IMAP folder'), immediately distinguishing it from listing or resolving folder operations such as email_list_folders and email_resolve_folder.

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 explicitly instructs the agent to resolve a folder name to an ID first and to obtain that ID via email_list_folders, and it warns never to pass human folder names like 'Inbox'. It doesn't explicitly contrast this tool with the resolve/list siblings, so it stops short of a full 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 readOnlyHint and idempotentHint, and the description adds useful context: the requirement for an exact thread_id and the account selection logic. It does not contradict annotations and provides extra behavioral detail 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?

The description is moderately concise but contains redundancy (e.g., repeating the thread_id instructions in two places). The main purpose is front-loaded, but the repetitive phrasing could be tightened.

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

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

Given the tool's simplicity, the description covers the necessary details: how to get thread_id, the optional account_id behavior, and the safety profile from annotations. It is complete enough for an agent to invoke correctly, though it lacks explicit mention of return format.

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 schema already documents both parameters. The description repeats the thread_id warning but does not add significant new meaning beyond what the schema provides. It meets the baseline but does not elevate 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?

The description states 'Retrieve full email thread by exact thread_id' with a specific verb and resource, and distinguishes from other email tools like email_read_message by focusing on the thread ID. It clearly indicates what the tool does.

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

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

It provides explicit guidance on obtaining thread_id from list/read responses and warns against substituting subject/email_id. It also gives context for account_id when multiple accounts exist. However, it does not explicitly name alternative tools, so it falls 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds an important behavioral constraint: availability is provider-dependent, since generic IMAP typically has no contact directory. It doesn't mention return format or pagination, but those are minor given the strong annotation coverage.

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 zero filler. The core verb, resource, and purpose are front-loaded, and the second sentence earns its place by warning about a common misuse case (generic IMAP).

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 optional-parameter list tool with no output schema, the description covers the tool's purpose, the key provider limitation, and enough return implication (contact info enabling name-to-address resolution). Pagination mechanics are left to the cursor schema, and the return shape is not spelled out, but those gaps are not critical 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?

The schema carries most of the meaning: account_id is richly documented (Nilyo connection ID, unipile_account_id, disambiguation instructions), and cursor is described. The description adds no parameter-specific detail, and the undocumented limit parameter is left to inference, though its intent is fairly clear from the name and bounds.

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

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

The description states a specific verb ('List'), a well-scoped resource ('Gmail/Microsoft contacts'), and an explicit goal ('resolve a human recipient name to an email address before composing'). It distinguishes itself from generic IMAP and from the sibling whatsapp_list_contacts by naming the provider scope.

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 explicitly tells the agent when to use the tool (before composing, to map a recipient name to an address) and when not to rely on it ('Generic IMAP normally has no provider contact directory'). It doesn't name a specific sibling tool as the alternative, but 'use mailbox context instead' gives a clear fallback strategy, so it earns just below the top score.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by explaining the draft.id field's role in subsequent operations and warning that it is not email_id or subject. This enriches the annotation-covered core without contradicting it.

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 short sentences with no filler. The primary purpose is stated first, followed by the key output-field caveat. It is efficient and front-loaded, though it could have been even more structured by grouping the draft.id clarifications into one sentence. Overall, it 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?

The tool has no output schema, so the description should compensate for return-structure details; the draft.id clarification helps but leaves the rest of the return object unspecified. The description also omits any explanation of the limit and any_email parameters, which are left to schema (limit has none) and guesswork. Given the complexity of 4 params and no output schema, the description is adequate but incomplete.

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 only 50% (limit and any_email lack descriptions). The tool description does not compensate; it mentions no parameters at all. Cursor and account_id are described in the schema, but limit and any_email remain ambiguous. The description's note about draft.id concerns output, not input parameters, so it does not help an agent understand the meaning or usage of any_email or limit.

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 lists email drafts with a specific verb and resource. It also adds a crucial distinction: the returned draft.id is the identifier for subsequent get/update/send/delete operations, and clarifies it is not email_id or subject. This distinguishes it from sibling tools like email_list_messages and prevents misuse of the returned ID.

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 no explicit guidance on when to use this tool over alternatives such as email_list_messages, nor does it state any exclusions or prerequisites. The only implication is that this is for drafts, but it doesn't clarify whether email_list_messages includes drafts or when to prefer one over the other. There is no mention of the account_id requirement for users with multiple accounts (even though the schema describes it, the description doesn't reference it).

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 cover safety (readOnly/idempotent/non-destructive), and the description adds real operational context beyond them: IMAP pages capped at 50 live messages, keep limit ~20 to avoid timeouts, an empty page is not 'zero emails' without a filter, and IMAP IDs change on move/update. No auth or error-mode detail, but the added traits are genuinely useful.

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 core purpose well, but the long 'Email provider ID' block is verbose and partly duplicates guidance that matters more to read/move tools, and the folder ID text repeats the folder_id schema description verbatim. Information-dense but not tight.

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 explains that listing yields email.id and that totals must come from email_list_folders, plus IMAP page caps and cursor-based paging. For a 9-parameter tool with IMAP quirks this is nearly complete, with only the to/from/any_email semantics left uncovered.

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?

At 33% schema coverage the description must compensate. It documents after/before as ISO 8601 UTC datetimes with a 'today' hint, the limit constraint, and folder_id's exact-ID requirement. However to, from, and any_email have no description anywhere in either the schema or the text, leaving meaningful gaps.

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 with scope: 'List messages inside one exact folder.' The 'one exact folder' scoping distinguishes it from a broader message listing, but it never names the sibling email_list_messages, so the differentiation is inferred rather than explicit.

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 a concrete IMAP workflow (list folders -> select folder.id -> list messages -> email.id -> read/action) and a clear when-not: for totals use folder.total_count/unread_count from email_list_folders instead of listing. It stops short of explicitly contrasting with the email_list_messages sibling for cross-folder listing.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by explaining that the returned folder.id is an exact Gmail label/Outlook/IMAP folder ID and that this listing is a preamble to message listing in IMAP. No contradiction with annotations exists.

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 opening sentences are efficient, but the tail block ('Mailbox folder/label ID: ...') reads like copy-pasted parameter documentation and is confusingly disconnected from this tool's input schema. It repeats the folder-id concept already stated, so the structure is not as clean as it could be.

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 list tool with no output schema, the description covers the essential operational facts: what is listed, why the returned IDs matter, and how this fits into IMAP message listing. It does not describe pagination or the full return shape, but the cursor schema and annotations compensate reasonably.

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 at 67%, and the schema already documents cursor and account_id well; limit has no description. The description's 'Mailbox folder/label ID' block is more about output semantics than the current tool's parameters, so it adds only marginal value for parameter understanding. 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 states a specific verb and resource: 'List Gmail labels, Outlook folders or IMAP folders.' It goes beyond a simple label by explaining the output's role ('Returned folder.id is required by folder-specific operations'), which clearly differentiates this list tool from folder mutation or message-listing siblings.

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

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

The description gives concrete usage context: 'For IMAP this is normally the first step before listing messages' and warns 'Never pass: human folder name such as Inbox when an ID is required.' However, it does not explicitly name alternatives like email_resolve_folder or email_get_folder, so the when-to-use guidance is strong 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 declare readOnlyHint, idempotentHint, and destructiveHint safely. The description adds useful non-obvious behavior: IMAP pages are capped at 50, results are listed live, and the limit should be kept small. This is genuinely helpful context beyond the structured 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 relatively compact and front-loaded with the core purpose. It packs provider scope, use cases, pagination limits, and an alternative into a few sentences. The cross-channel phrasing is slightly verbose, but it still earns its place by explaining when the tool is helpful.

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 listing tool with no output schema, the description covers the essential decisions: provider scope, when to use, pagination caps, limit advice, and the alternative for totals. It could be more complete by explicitly describing the return shape or cursor-based pagination, but the core agent workflow (find email_id, then open the message) is supported.

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 67%, and the schema already documents after, before, folder_id, and account_id in detail. The description adds guidance for the limit parameter ('keep limit small (20)') and implies email_id appears in results. However, it does not clarify cursor semantics or add meaning for the undocumented limit/cursor parameters beyond what the schema provides.

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

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

The description states a clear action and resource: 'List email messages from the user's connected Gmail, Microsoft/Outlook OR generic IMAP mailbox.' It also explains that the tool is used to find email_id before opening a message. However, it does not explicitly distinguish itself from the sibling email_list_folder_messages, so an agent may still be unsure which listing tool to choose.

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 context: it is especially useful for IMAP mailboxes not covered by native connectors and for cross-channel workflows. It also directs agents to email_list_folders for totals, which is a helpful alternative. It does not explicitly state when to choose email_list_folder_messages or email_list_drafts instead.

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

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

Annotations declare the safety profile (mutation via readOnlyHint=false, not destructive, not idempotent), and the description adds nothing beyond that about the effect of marking read. The ID-lifecycle warning is duplicated verbatim from the input schema, so it earns no transparency credit here.

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 first sentence is tight and front-loaded, but everything after it is the parameter description pasted wholesale into the body, duplicating the schema field-by-field. Roughly 80% of the text is redundant with structured data.

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 and annotations cover the safety posture, so the description only needs to cover the operation plus ID hygiene, which it does. It omits any note on provider-specific behavior of read state (e.g., server sync effects), leaving it merely adequate.

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 schema already carries the full ID semantics and account_id guidance. The description simply restates the email_id text without adding format, validation, or fallback meaning. 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?

The opening sentence gives a specific verb+resource+scope ('Mark one exact email read'), which distinguishes it from bulk operations. It does not explicitly name its closest sibling email_mark_unread, but the operation is unambiguous.

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

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

It states a prerequisite workflow ('Resolve human email reference -> email_id first') and where to obtain the ID, which implies usage. It never says when to use this versus email_mark_unread or what happens if the email is already read.

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, openWorldHint=true), so the bar is lower, and the description adds genuinely useful non-obvious behavior: on IMAP/Exchange the id encodes folder+UID and changes on move or draft update, so a stale id silently targets the wrong message. It doesn't describe the resulting state change beyond 'unread', but the ID-volatility warning is real added value.

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

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

Purpose is correctly front-loaded in the first sentence, but the remainder is a long block that largely restates the schema's email_id text, including a run-on 'Obtain with / Never pass' list that is hard to parse. It is thorough but not tight.

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-required-param mutation with no output schema, the ID resolution path is covered exhaustively and annotations carry the safety semantics. The only real gap is the absence of any routing versus email_mark_read / email_trash.

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's ID guidance is essentially a verbatim duplicate of the email_id schema description, adding no syntax or format detail the schema lacks, and account_id is not discussed at all in the description body.

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 with scope ('Mark one exact email unread'), which is unambiguous and immediately separable from its sibling email_mark_read. An agent knows exactly what state transition is requested.

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 a strong prerequisite ('Resolve email_id first') and routes to the tools that produce the id, but never says when to choose this over email_mark_read or email_trash, nor any when-not condition. Usage is implied by the verb rather than stated.

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

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

Annotations declare a non-read-only, non-idempotent, open-world mutation, and the description adds genuinely new behavioral context: on IMAP the id encodes folder+UID and CHANGES after a move, so result.id must be reused. That is material, non-obvious behavior beyond the annotations. It does not contradict the annotations (mutation allowed, not destructive).

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 well with the core operation and the id-change caveat, but the back half is a near-verbatim paste of the schema's email_id and folders_ids descriptions, producing heavy redundancy. Padding rather than earning each sentence.

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

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

No output schema exists, and the description responsibly explains the return value ('the result is the email after the change') plus the ID-reuse implication. For a state-changing tool with annotations covering safety, this is largely complete, though the opaque 'specifics' parameter is never addressed.

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?

Coverage is 50%; email_id and folders_ids semantics are explained, but the same text already appears in the schema parameter descriptions, so the description adds little beyond what the schema provides. The 'specifics' object parameter is undocumented in both places, so the description fails to compensate for the coverage gap.

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 with scope: 'Move/label one exact email.' An agent can distinguish it from email_trash or email_mark_read by the resource and operation. However, it never explicitly routes against those siblings, so it stops short of a 5.

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

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

Gives strong 'how' guidance for parameter resolution (resolve email_id independently, resolve folder names to folder.id, never pass 'Inbox' strings). But it offers no explicit when-to-use-this-vs-alternatives guidance — e.g., versus email_trash, email_update_folder, or email_mark_read — leaving tool selection to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that it spans multiple providers and returns body/headers, which is useful but modest. No permissions, rate-limit, or failure-mode context is added.

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

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

Two compact sentences with the operation stated first and the workflow hint second. 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 read-only tool with rich annotations and fully documented parameters, the description covers what it does and roughly what it returns (body/headers). There is no output schema, but a read of a single message needs little more; return-format details would be a minor addition.

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 email_id field description is unusually thorough (IMAP UID instability, what not to pass). The description itself adds no parameter guidance, 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 (Read) and resource (a specific email including body/headers), and names the providers (Gmail, Outlook, IMAP). It is clearly a single-message read, distinguishable from email_list_messages, though it does not explicitly contrast with email_get_thread or email_resolve_message.

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

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

Gives sequencing context: 'Use after email_list_messages and before a contextual reply or cross-channel decision.' That tells the agent when in the workflow to reach for it. It lacks explicit exclusions versus thread- or resolve-oriented siblings, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not required to re-state safety. It adds workflow behavior: it lists folders to map names to IDs, notes IMAP importance, and provides a warning. It does not describe edge cases like missing folders or pagination behavior, but for a read-only listing tool with these annotations, the added context is sufficient.

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 moderately concise and front-loaded: the first sentence states the core purpose. The subsequent sentences add relevant context (IMAP relevance, ID acquisition via email_list_folders, and the warning). It is a bit dense with mixed instructional fragments, but every sentence contributes meaning and there is no fluff.

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

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

For a simple read-only listing tool with no output schema, the description provides purpose and workflow context, but it leaves ambiguity about the input/output contract. The schema has no parameter for a human folder name, yet the description says 'map human names... to exact folder_id' without clarifying that the tool returns a list for the agent to match. The reference to email_list_folders as the source of folder.id is also somewhat confusing about the relationship between the two tools. More explicit guidance on the response shape and how to use the returned data would improve completeness.

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 only 33% (only account_id has a description). The tool description does not mention limit or cursor at all, nor does it add meaning to any parameter beyond the schema. It implies a list operation but does not explain how limit/cursor affect results. With low schema coverage, the description should compensate for undocumented parameters, and it fails to do so.

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 function: listing mailbox folders/labels to map human-readable names to exact folder_id. It identifies the trigger ('before moving/labeling or listing folder messages'), highlights the IMAP relevance, and explicitly warns against passing human names when an ID is required. This distinguishes it from siblings like email_list_folders and email_get_folder by focusing on the resolution workflow.

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 context on when to use the tool ('before moving/labeling or listing folder messages') and emphasizes the IMAP case. It also includes a clear exclusion: 'Never pass: human folder name such as Inbox when an ID is required,' and points to email_list_folders as the source of folder.id. It could be more explicit about when not to use this tool (e.g., when an ID is already known), but the guidance is strong.

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 as a safe, idempotent, closed-world read (readOnlyHint/idempotentHint/destructiveHint=false), so the description doesn't need to restate the safety profile. It adds genuinely useful behavior the annotations can't carry: IMAP ids encode folder+UID and change on move or draft update, so the last returned id must always be reused, plus explicit 'never pass' guidance (subject, stale ids, RFC Message-ID). It still says nothing about result ordering or pagination behavior.

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

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

The purpose sentence and the IMAP fallback are front-loaded and well ordered. However, the bulk of the text is generic provider-ID/reply-reference/thread-ID boilerplate that is repeated across email tools and is only tangentially about a resolution tool, which dilutes the signal for an agent reading this specific definition.

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

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

With no output schema and 0 required parameters, the description does convey what the tool returns (email candidates with provider id and thread_id) and how to obtain each id, which is reasonably complete for a read-only resolver. The remaining gap is parameter-level meaning for the seven undocumented filter/pagination inputs.

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 only 13% (account_id alone) across 8 parameters, so the description carries the burden and does not meet it. It never names or explains to, from, any_email, after, before, limit or cursor, and the words 'sender, recipient, subject or date' are only loosely suggestive of to/from/any_email/date filters. An agent must guess at the filter semantics and at how limit/cursor interact.

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 opening sentence names a specific verb+resource (search/list email candidates) and a concrete outcome (mapping a human reference like sender, recipient, subject or date to an exact email_id) ahead of downstream read/reply/trash/move operations. It is clearly distinct in intent from a plain listing tool. It stops short of explicitly contrasting itself with the very similar email_list_messages sibling, which it only cites as a source of ids.

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 when to use the tool (to resolve a human reference before read/reply/trash/move/attachment operations) and gives an explicit alternative path for one case: on generic IMAP, when account-wide listing is unavailable, use email_list_folders then email_list_folder_messages. There is no general when-not guidance for the non-IMAP case, so no exclusions for Gmail/Outlook users.

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 destructiveHint=true and readOnlyHint=false, so the mutation nature is covered. The description adds valuable context: it must only be used with user consent, and it supports multiple providers. It also hints at reply behavior via reply_to_message_id, which is 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?

The description is two sentences with no filler. It front-loads the core purpose (send/reply) and then adds the reply hint and consent requirement. Every word earns its place, and the structure is clean.

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

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

For a tool with 8 parameters and no output schema, the description is relatively sparse. It does not explain what happens on success or failure, how to handle multiple connected accounts (though account_id is in schema), or edge cases like invalid recipients. It covers the essential 'when' but lacks depth for a complex 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?

Only 2 of 8 parameters (account_id and reply_to_message_id) have descriptions in the schema, which is 25% coverage. The tool description does not explain common parameters like to, cc, bcc, subject, html, or plain_text. It mentions reply_to_message_id but that is already covered in the schema, so it adds no new meaning. With low schema coverage, the description should compensate, but it does not.

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 sends or replies to an email from a connected Gmail, Outlook, or IMAP account. It distinguishes itself from sibling tools like email_create_draft and email_send_draft by emphasizing direct send/reply, and mentions the reply_to_message_id for true replies, which sets it apart from draft workflows.

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

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

It provides clear context on when to use this tool (to send or reply) and includes a critical safety guideline about only sending after user approval. However, it does not explicitly exclude alternatives like email_create_draft or email_send_draft, so the differentiation is implicit rather than 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 mark destructiveHint=true, but the description adds real-world consequence: 'this creates a real external send.' It also instructs the agent to inspect recipients/content before sending, reinforcing that this action is irreversible and has external impact. This goes beyond the bare annotation and provides valuable behavioral 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, no wasted words. The core action is front-loaded ('Send one exact existing draft'), followed immediately by the critical safety instruction. 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 two-parameter destructive action with no output schema, the description covers the essential pre-send verification step and discloses the external-send consequence. It doesn't describe return values, but that is less critical for a send action. Overall, the agent has everything needed to invoke the tool safely and 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 the parameters are already well-documented in the input schema. The tool description itself adds little about parameter semantics; it references draft_id but not account_id. Per the rubric, with high schema coverage the baseline of 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 states a precise verb and resource: 'Send one exact existing draft.' It clearly differentiates from sibling tools like email_create_draft, email_update_draft, and email_send by emphasizing it sends an already-created, exact draft rather than composing or modifying. No ambiguity remains about the tool's 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 provides a crucial operational condition: 'Resolve draft_id and inspect final recipients/content first when not already explicitly approved.' This tells the agent when it is appropriate to execute the send and what preconditions must be met. It does not explicitly name alternative tools or give a contrast to email_send, but the context and phrasing make the intended use clear.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: on IMAP the ID encodes folder + UID and changes when the message moves, so the id from the last operation must be reused. That volatility caveat is real behavioral context 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?

The lead sentence is well front-loaded, but the description then duplicates the long ID-resolution paragraph that already appears in the schema, so several sentences do not earn their place by adding new information. Net effect is redundancy rather than sharp concision.

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 100% schema coverage, destructive annotations, and no output schema required, the definition supplies everything needed to invoke correctly: the target ID source, the required resolve-first step, and the ID-stability caveat. Only the trash-vs-permanent-delete distinction is left 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 description coverage is 100%, and the email_id guidance in the description is essentially a verbatim repeat of the schema text, adding no new meaning. The account_id semantics (multi-account disambiguation) are likewise already fully documented in 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 ("Trash one exact email") with clear single-message scope, which separates it from bulk or move/label operations like email_move_or_label. It does not explicitly name the sibling it differs from, and leaves some ambiguity about whether "trash" means move-to-trash-folder (recoverable) versus permanent removal, so it stops short of a 5.

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

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

Gives one prerequisite ("Resolve email_id first") and flags the destructive nature, which implies when to use it. However, it never names an alternative (e.g., email_move_or_label to relocate instead of trash) or states when-not-to-use, so usage is only implied rather than spelled out.

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 a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral context: on IMAP the draft ID changes and the new ID must be used for email_send_draft, and that reading the draft first is advised to preserve unspecified fields. 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?

The description contains an awkward fragment: 'without sending.' which appears as an incomplete sentence with a double space before it. While the core message is short, the structure is unclear and could confuse an agent. The placement of 'without sending' after the IMAP note seems out of 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 9 parameters, no output schema, and sparse annotations, the description should clarify the update semantics and expected result. It mentions the new draft ID on IMAP but does not describe the return object, how missing fields are handled, or the exact behavior for non-IMAP providers. It also omits guidance on which parameters are typically updated together. The description is incomplete for an agent to confidently call this 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 description coverage is only 33%, with only draft_id, account_id, and reply_to_message_id having descriptions. The tool description provides no additional meaning for the remaining six parameters (to, cc, bcc, html, subject, plain_text). It does not clarify whether the update is a full replacement or a merge, nor which fields are optional. The description fails to compensate for the low schema coverage.

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 verb 'Update' and resource 'exact existing draft', distinguishing it from create/send/delete siblings. The qualifier 'exact existing' implies it targets a specific draft, but it does not explicitly contrast with email_create_draft or email_get_draft. The redundant 'without sending' adds no value but does not mislead.

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 includes a precondition: 'Resolve/read draft first when preserving recipients/content matters.' This is useful guidance for a partial-update scenario. However, it does not explicitly state when to use this tool versus alternatives like email_create_draft or email_send_draft, nor does it list exclusion criteria.

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, idempotentHint=false, so the mutation profile is known. The description adds that it renames/moves an existing folder and that parent_id is an exact folder ID, but doesn't disclose side effects like whether moving changes child folders or whether renaming affects labels. It doesn't 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?

The description is compact and front-loaded with the core action. The repeated ID guidance is somewhat redundant with the schema descriptions, but it's placed efficiently and the critical warning is clear. It earns its place by emphasizing the ID requirement.

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 mutation tool with no output schema, the description covers the key prerequisites (resolve folder_id, use exact IDs) and the main parameters. It doesn't explain return values or side effects, but the annotations cover the safety profile and the schema covers parameters. The main gap is lack of detail on what happens when moving a folder (e.g., does it affect children), but this is a minor gap for a simple rename/move 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?

Schema description coverage is 75%, so the schema already documents folder_id, parent_id, and account_id in detail. The description adds the workflow hint 'Resolve folder_id first' and the 'Never pass human folder name' warning, which reinforces the schema. The name parameter is not described in the schema, but its meaning is obvious from the tool name and description. 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 states a specific verb and resource: 'Rename/move one existing folder.' It clearly distinguishes from email_create_folder and email_delete_folder. However, it doesn't explicitly contrast with email_move_or_label, which is a sibling that also moves/labels messages, though the folder-specific scope is clear.

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 explicit when-to-use guidance: 'Resolve folder_id first' and 'Obtain with: email_list_folders -> folder.id'. It also provides a clear exclusion: 'Never pass: human folder name such as Inbox when an ID is required.' This tells the agent exactly how to prepare inputs and what not to do.

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 are mostly negative hints and do not describe side effects, consent, or data-handling expectations, so the description carries the burden. It discloses that the tool creates a tracked issue, requires user_consent=true, should include exact error codes/details for reproduction, and must never include credentials, message bodies, or third-party personal data. This is meaningful behavioral context 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?

The description is four dense sentences with no filler. It front-loads the purpose, then gives trigger conditions, then data requirements. Every sentence contributes to correct invocation or safe execution.

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

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

For a tool with 13 parameters and no output schema, the description covers the essentials: when to invoke, consent requirements, what evidence to include, and what to exclude. It does not mention how to classify severity or suspected_layer, but those are covered by enum descriptions in the schema and are not critical to deciding whether to call 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?

Schema description coverage is 85%, so the baseline is 3. The description adds value by reinforcing how error_code and error_details should be used ('exact error code and details from the failing result') and by imposing privacy constraints across free-text parameters. It does not elaborate on the two undocumented parameters (actual/expected), but the schema handles most parameter meaning.

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

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

The description states a specific verb and object: 'Report a bug to the Nilyo team as a tracked issue.' It also gives clear triggering conditions ('after a tool failed unexpectedly', TOOL_FAILED, wrong or empty result, broken flow), which helps distinguish it from feature-request or general feedback 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 is explicit about when to use it: after unexpected tool failure, when the user agrees, and when the user says 'ça ne marche pas' or 'report this'. It does not explicitly contrast with the sibling feedback_request_feature, but the bug-specific framing makes the intended context clear.

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

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

The description discloses that this sends a tracked issue to the Nilyo team and requires explicit user consent, which is useful behavioral context beyond the annotations. However, it does not explain what happens after submission, whether anything is reversible, or the lack of immediate resolution, so the behavioral picture is partial.

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 focused sentences front-load the core purpose, then the trigger conditions and consent requirement, with no filler or repetition. 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?

Given the tool's moderate complexity, the description covers purpose, trigger conditions, content expectations, and consent. The main gap is the lack of explicit guidance distinguishing this from the bug-reporting sibling and any description of the outcome after submission.

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 structured schema already documents all seven parameters in detail. The description adds general guidance about capturing the user's goal and why current tools fall short, but it does not add parameter-level meaning beyond what the schema provides.

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 sends a feature request or improvement idea to the Nilyo team as a tracked issue, with concrete examples of what qualifies. It is specific about the resource and action, but it does not explicitly contrast this with the sibling feedback_report_bug tool, so differentiation is implied 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?

The description gives explicit when-to-use conditions: when the user asks for something Nilyo cannot do yet or explicitly wants to suggest an improvement, plus the consent requirement. It does not state when-not-to-use it or mention the alternative bug-reporting sibling, so it falls just short of full routing 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 are all false (not read-only, not idempotent, not destructive), so the description must carry behavioral disclosure. It states that credentials are forwarded once and never stored, which is a security transparency. It also discloses the auto-detection behavior, the failure handling (ask for servers), and the re-authentication use case. This goes beyond the annotations and gives the agent a clear picture of side effects and expectations.

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 long but every sentence adds value: purpose, alternative, security note, step-by-step guidance, and special cases. It is well-structured with clear flow, and the key information (user+password first) is front-loaded. No fluff or repetition.

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

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

Given the complexity (10 parameters, no output schema, no annotations), the description covers many aspects: purpose, alternative, security, usage flow, and re-auth. However, it does not describe the success return value or what the agent should expect after a successful connection (e.g., connection ID or status). It implies a result by mentioning 'if the result says invalid', but doesn't explain the successful outcome. This is a minor gap for a tool with 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 description coverage is only 40%, so the description must compensate. It does clarify that user+password are the primary required fields and that servers are auto-detected, implying host/port are optional. It provides example server settings for OVH and mentions account_id for re-auth. However, it does not explain imap_encryption, smtp_encryption, or other parameters, leaving their semantics unclear. It partially compensates but not fully.

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 purpose: connecting a generic IMAP/SMTP mailbox with credentials. It distinguishes itself from the account_connect browser link as an alternative, and specifies it is for generic mailboxes, not Gmail/Outlook. The verb 'connect' and resource 'mailbox' are explicit, and it is differentiated from sibling connect tools like telegram_connect and whatsapp_connect.

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 when-to-use guidance: it is the alternative to account_connect when the user prefers typing credentials in chat. It also gives an exclusion: Gmail/Microsoft mailboxes should use Google/Outlook connection instead. It further instructs to start with user+password only and to ask for servers if configuration is invalid, plus how to re-authenticate via account_id. This is clear and actionable.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description goes further by disclosing behavior the annotations cannot: unsupported payload features (no attachments, no comment_as) and a hard no-auto-retry rule for failed/partial/timed-out writes with a recovery step. For a non-idempotent public write, that is exactly the operational context an agent needs.

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 and every sentence carries an instruction, but there is mild redundancy: 'approved top-level text comment on one exact Instagram post' and 'publish only the exact user-requested/approved text and target' say substantially the same thing. Still dense and skimmable, 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?

With no output schema, the description covers prerequisites, payload limits and failure handling, which is most of what is needed for a write tool. It does not say what a successful publish returns (e.g. the new comment identifier) or what errors surface, a minor gap given the tool's simplicity.

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, and the schema already specifies post_id format/derivation and account_id provenance. The description adds incremental value by implying the allowed payload shape ('top-level text comment', 'no attachments or comment_as'), warning agents away from parameters that do not exist. It does not restate parameter syntax, which is already covered.

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 precise verb+resource+scope: 'Publish an approved top-level text comment on one exact Instagram post.' The qualifiers 'top-level' and 'This does not reply to a specific comment' carve out a distinct action from reply/comment-update operations in the sibling set (e.g. social_update_comment, linkedin_reply_to_comment). An agent can identify the tool's exact effect 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?

Gives an explicit prerequisite sequence (resolve/read the post first, reuse post.id, read comments for context) and an explicit failure-branch instruction: inspect instagram_list_post_comments before deciding another send. It also bounds the input ('publish only the exact user-requested/approved text and target'), so when-to-use and when-not-to-retry are both stated rather than inferred.

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 it a non-readonly, non-idempotent, open-world write with destructiveHint=false. The description adds behavior beyond that: the approval prerequisite, the native receipt semantics (UserFollowed = followed vs RelationRequest = pending request to a private account, not accepted), and a no-auto-retry policy on failed/ambiguous writes.

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 tight sentences, zero filler, front-loaded with the action and its scope. Each remaining sentence carries a distinct operational rule (prerequisite, receipt interpretation, retry policy), so nothing is wasted.

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