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, destructiveHint=false, idempotentHint=false, so the safety profile is known. The description adds ID resolution context but does not disclose additional behavioral traits like side effects or rate limits. It does not contradict annotations.

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

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

The description is front-loaded with the core action and then provides structured ID resolution guidance. While verbose, the length is justified by the complexity of ID handling; it remains efficient and well-organized.

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 3 params (2 required) and no output schema, the description covers all necessary operational details: ID resolution, what to avoid, and provider-specific nuances. The optional account_id is fully explained in the schema, so no 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%, giving a baseline of 3. The description significantly enhances parameter meaning by detailing how to obtain chat_id and user_id, including LinkedIn-specific resolver chains and explicit exclusions, going beyond the schema's 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 the specific verb 'Add' and resource 'exact provider user to an exact group chat', clearly distinguishing it from siblings like chat_remove_participant and chat_list_participants. The emphasis on 'exact' reinforces the precision 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?

Provides explicit instructions on resolving chat_id and user_id, including what never to pass (person name, URL, etc.). It does not explicitly mention when to use this tool over alternatives, but the purpose is unambiguous and the guidance is highly 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?

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?

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds crucial behavioral nuance: it explains that on IMAP (and Exchange over IMAP) the email ID encodes folder+UID and changes when the email is moved or a draft is updated, so the last returned ID must always be used. It also clarifies that filenames are not valid IDs. This is beyond what annotations convey and is essential for correct invocation.

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 verbose and repetitive. The same warnings about never passing filename/URL and about IMAP ID changes are duplicated for both email_id and attachment_id. The text is not front-loaded; it mixes critical guidance with redundancy. It could be condensed by half without losing information, and the structure (a single long paragraph) makes it hard to scan 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?

The description covers the required chain, ID stability pitfalls, and sources for both IDs, which is comprehensive for the main flow. However, it does not mention the account_id parameter (though the schema covers it with its own guidance) and does not state what the tool returns (e.g., binary data or a URL). Since there is no output schema, a brief note on return type would make it fully complete. Still, given the tool name and context, the missing info is minor.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description enriches both key parameters with explicit acquisition instructions: email_id via email_list_messages/email_list_folder_messages or from email_move_or_label/email_update_draft after a change, and attachment_id from reading the parent email first. It also lists what to never pass (filename, URL, subject, RFC Message-ID). This substantially exceeds the schema's bare definitions.

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

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

The description states a specific verb ('Retrieve'), resource ('attachment'), and scope ('from Gmail, Outlook/Microsoft or IMAP'), and explicitly defines the required chain (resolve/list email -> email_id -> read email -> attachment.id -> retrieve). This clearly distinguishes it from siblings like email_read_message, which fetches the message body, not the attachment. No ambiguity remains.

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 step-by-step usage chain and explicitly warns against passing filenames, URLs, or RFC Message-ID, and against reusing stale IMAP IDs after moves/updates. It even names the source tools (email_list_messages, email_list_folder_messages) and the post-change IDs to reuse, leaving no doubt about when and how to call this tool. This exceeds the typical 'when to use' guidance.

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

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

Annotations already declare 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?

Beyond the readOnlyHint/idempotentHint annotations, the description reveals key behavioral traits: empty pages do not mean zero emails unless no filter is applied; IMAP pages are capped at 50 live messages; limiting to 20 avoids runtime timeouts; and IMAP email IDs change on move/update, so reuse the latest ID. These are essential for correct usage and go well beyond annotation defaults.

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 lengthy but every sentence provides actionable detail: workflow, date format, counting caveats, pagination limits, and ID handling. It is front-loaded with the core purpose and workflow, then deepens into edge cases. While it could be tightened, the density of useful information justifies its length; nothing is filler.

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

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

For a 9-parameter tool with no output schema and low schema coverage, the description covers the most critical aspects: workflow, date semantics, counting, pagination limits, folder_id acquisition, and ID mutability. It does not explicitly explain to, from, any_email, or cursor, but those are simpler and likely self-evident or covered by schema descriptions. Overall, it provides sufficient context for an agent to call the tool correctly.

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

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

Schema coverage is only 33%, so the description carries the burden of explaining parameters. It specifies after/before as ISO 8601 UTC datetimes with a 'today' hint, advises a small limit (20) to avoid timeouts, and details how to obtain folder_id (via email_list_folders -> folder.id) and the distinction from human names. It also explains the email provider ID behavior for related tools, adding context that is not in the schema.

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

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

The description opens with a precise statement of the tool's function: 'List messages inside one exact folder.' It specifies the resource (folder) and the operation (list messages), and provides a concrete workflow (list folders -> select folder.id -> list messages -> email.id -> read/action). This clearly distinguishes it from siblings like email_list_messages (which likely lists across folders) and email_list_folders (which lists folders, not messages).

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: for listing messages in a specific folder after obtaining a folder ID via email_list_folders. It also tells when NOT to use it: for totals, use folder.total_count/unread_count from email_list_folders instead. It does not explicitly name email_list_messages as an alternative for cross-folder listings, but the folder-specific workflow implies the distinction. This is clear and practical.

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 already state readOnly=false, idempotent=false, and destructive=false. The description adds valuable behavioral context beyond that: IMAP IDs encode folder+UID, change on moves/draft updates, and must always come from the last operation. No contradiction with annotations.

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

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

The core purpose is front-loaded, but the description becomes a dense run-on that repeats the schema text nearly verbatim and lacks clear structure, e.g. 'after a change Never pass'. Bulleted caveats would make it much easier to scan.

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 mutation, the description covers the critical resolution workflow, ID acquisition, IMAP ID-staleness, and forbidden input values. Account_id handling is covered in the schema. The only minor gap is no mention of the return shape since there is 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 100%, so a baseline of 3 applies. The description adds extra meaning with 'Resolve human email reference -> email_id first' and reinforces what must never be passed, which helps the agent construct the email_id parameter correctly.

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 'Mark one exact email read', a specific verb, resource, and scope. The word 'exact' plus the read state distinguishes it from siblings like email_mark_unread and email_read_message without needing to name them.

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 workflow: resolve human references to email_id first, obtain IDs from email_list_messages or email_list_folder_messages, and avoid stale IDs on IMAP. It does not explicitly name alternative tools for other read-related intents, 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 indicate this is a mutation (readOnlyHint=false), but the description adds crucial behavioral context beyond that: IMAP IDs encode folder+UID and change on moves/draft updates, so the caller must always reuse the last-operation ID. It also explicitly forbids passing RFC Message-ID, subject, or pre-move IDs. This is valuable, non-obvious behavioral information.

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 and a prerequisite, then presents essential ID-resolution rules. It is longer than strictly necessary because it duplicates the schema's parameter text, but every included caveat ('CHANGES when moved', 'Never pass: RFC Message-ID') carries real operational value.

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

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

For a simple state-change tool with no output schema, this description covers the only genuinely difficult part: how to obtain a valid email_id, under what conditions it goes stale, and which ID forms must never be used. The optional account_id handling is fully specified in the schema. Nothing needed for a 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?

Schema description coverage is 100%, and the property descriptions already fully explain email_id and account_id. The tool description repeats the email_id semantics rather than adding new parameter-level meaning, so a baseline score 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 opens with a specific action ('Mark one exact email unread') and clearly identifies the resource ('one exact email') and the intended state ('unread'). The word 'exact' and the instruction to 'Resolve email_id first' distinguish this from bulk operations and from the sibling email_mark_read without 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?

The description clearly establishes when to use the tool: after resolving an email_id via email_list_messages or email_list_folder_messages, and it warns against using stale or non-provider IDs. It does not explicitly name the alternative email_mark_read or state 'when not to use' conditions, but the workflow context is sufficiently 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 indicate mutation (readOnlyHint=false) and non-idempotence (idempotentHint=false). The description adds critical context: on IMAP the email ID changes after move/update, so the result.id must be reused. It also warns against using stale IDs. This goes beyond annotations and is essential for correct follow-up calls.

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 well-organized, starting with the core purpose and then diving into necessary caveats and resolution steps. It is front-loaded with the key behavior (ID change) and structured into clear sections. While a bit verbose, the complexity of the tool justifies the length; every sentence adds value.

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

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

With no output schema, the description explains the return value ('the email after the change') and the critical ID mutation. It covers ID resolution for both email and folders, warns about common pitfalls, and clarifies account_id handling. It lacks explicit error conditions or edge cases, but covers the primary use cases and traps. Slightly incomplete for specifics parameter, but overall strong.

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 50% (email_id and folders_ids have descriptions; specifics and account_id lack them). The description compensates by providing detailed instructions for email_id and folders_ids, including how to obtain and what not to pass. For specifics and account_id, the description offers some guidance (e.g., account_id resolution), but specifics remains underdocumented. Overall, the description adds significant 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?

States a specific verb ('Move/label') and resource ('one exact email') with scope. Clearly distinguishes from siblings like email_trash, email_update_draft, and email_send by focusing on moving/labeling. The description also mentions the result is the email after the change, which is unique.

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 on how to resolve email_id and folder IDs, including specific sources (email_list_messages, email_list_folders) and what to avoid (RFC Message-ID, human folder names). While it doesn't explicitly compare to alternatives like email_trash, it clearly scopes the operation and offers procedural steps. Lacks explicit 'when not to use' but strong on how to use correctly.

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 establish the read-only, idempotent, non-destructive profile, and the description's 'Read' is consistent with that. The description adds useful scoping (body/headers, provider support) but does not disclose behavior such as whether fetching marks the email as read, how attachments are handled, or response shape. Since annotations cover the safety profile, this is acceptable but not exemplary.

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 scope in the first sentence and workflow placement in the second. There is no filler, repetition, or needless detail; each 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?

The schema carries the complex ID caveats and account-selection rule, while the description supplies workflow placement and a high-level return description ('body/headers') in the absence of an output schema. It could be more complete by explicitly excluding attachments or pointing to email_get_attachment/email_get_thread, but the tool remains callable with the information provided.

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

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

Both parameters have 100% schema description coverage, with the email_id description going into depth about provider IDs, IMAP ID instability, and what not to pass. The prose description adds no extra parameter semantics beyond that, 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 concrete action ('Read'), the resource ('a specific email'), and the payload scope ('body/headers'), plus supported providers (Gmail, Microsoft/Outlook, IMAP). It is clear enough to be picked over list/resolve tools, but it does not explicitly contrast itself with sibling getters such as email_get_thread or email_get_draft.

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

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

The second sentence is explicit workflow guidance: 'Use after email_list_messages and before a contextual reply or cross-channel decision.' This tells an agent the appropriate position in a multi-step task. It does not, however, name exclusions or alternative tools like email_get_thread for thread-level reads, so it stops short of full when/when-not 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 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses critical behavioral traits: IMAP IDs encode folder+UID and change when emails are moved or drafts updated, so the last returned ID must always be reused. It also explains how to obtain correct IDs (via email_list_messages or email_list_folder_messages) and what never to pass (RFC Message-ID, subject, stale ID). This adds significant value over 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 well-structured into sections (overview, provider ID, reply reference, thread ID) and front-loads the core purpose. However, it is quite long and somewhat dense, with technical caveats that could be condensed. Every sentence carries relevant information, but the length may reduce scannability 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?

Given the 8-parameter schema with no output schema, the description covers many important edge cases: provider differences (Gmail/Outlook vs IMAP), ID stability, and alternative tools. However, it does not describe the return format (e.g., whether output is a list of candidates with id, subject, sender fields), which is needed since there is no output schema. It also leaves parameter semantics for from/to/before/after/limit/cursor unexplained, so completeness is good but not perfect.

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% (only account_id is described), so the description must compensate for the other seven parameters. It mentions 'sender, recipient, subject or date' as human references, but does not explicitly map them to schema properties (from, to, any_email, after, before). It also does not explain limit, cursor, or the meaning of any_email. The description provides no concrete parameter-level semantics, leaving agents to guess.

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: 'Search/list email candidates so a human reference such as sender, recipient, subject or date can be mapped to exact email_id before read/reply/trash/move/attachment operations.' This distinguishes it from siblings like email_list_messages or email_read_message by focusing on resolving references to IDs. It also names the specific use case and alternative tool, making it easy for an agent to select correctly.

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 usage guidance: 'For generic IMAP, if account-wide listing is unavailable, use email_list_folders then email_list_folder_messages instead.' It also gives detailed do/don't instructions for obtaining and passing email provider IDs, reply references, and thread IDs, including warnings about IMAP IDs changing after moves/draft updates. This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare 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 the description reinforces that with 'destructive mailbox action.' It adds valuable context about ID instability: the ID changes on move/update, and it must be the latest one. It also warns against passing RFC Message-ID or stale IDs. These are beyond annotations and help avoid misuse.

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 long, dense paragraph, especially for email_id, mixing prerequisites, warnings, and ID acquisition steps. It front-loads the core action but then becomes a wall of text without bullets or clear sectioning. While informative, it is not concise or well-structured for quick consumption.

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

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

Despite verbosity, it covers all critical operational details: how to resolve the ID, when it becomes invalid, what to never pass, and how to handle the optional account_id with multiple accounts. With no output schema, it explains the return behavior implicitly via 'destructive action.' An agent can safely invoke it correctly after reading this.

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 essentially repeats the same text for email_id and adds a concise account_id explanation. It does not add meaning beyond the schema; it mirrors it. Since the schema already documents the parameters thoroughly, a baseline of 3 is appropriate; no extra semantic value is provided by the 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 states a clear verb and resource: 'Trash one exact email.' It also flags it as a 'destructive mailbox action,' which sets expectations. It does not explicitly contrast with sibling tools like email_move_or_label, but the purpose is unambiguous and not a tautology.

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?

No guidance on when to use this tool versus alternatives. It does not mention that email_move_or_label could be used for moving to trash, or that this is a permanent action, nor does it specify prerequisites beyond resolving the ID. The only context is 'destructive mailbox action,' which implies but does not state selection 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 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds no behavioral details beyond the purpose (e.g., no mention of return shape or authentication requirements), but it doesn't contradict annotations either. It provides minimal additional 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?

A single concise sentence that precisely captures the tool's function. There is no wasted text, and the key qualifier ('owner of the connected Instagram account') is front-loaded, making it immediately clear what this tool does.

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 getter with an optional parameter fully documented in the schema, the description is adequately complete. It doesn't specify the return format (e.g., current profile fields), but that is often implied for a 'get profile' tool, and the annotations cover safety. Slight improvement could be mentioning that it returns the profile data, but not essential.

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

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

The description does not mention the account_id parameter, but the schema has 100% coverage and a detailed description explaining when to provide it and how to handle multi-account cases. Since the schema already carries that burden, the description doesn't need to add more.

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') and a precise resource ('the profile of the owner of the connected Instagram account'), which clearly distinguishes it from sibling instagram_get_profile. The phrasing 'owner of the connected Instagram account' signals this is the authenticated user's own profile, not an arbitrary profile lookup.

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 stating 'owner of the connected Instagram account' – this suggests the tool is for retrieving the connected account's own profile, but it doesn't explicitly contrast with instagram_get_profile (which presumably fetches other profiles) or provide when/when-not advice. The guidance is implied 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the 'where supported' caveat and the intended pre-action usage, which adds minimal but relevant context. It does not disclose error behavior or rate limits, but given the annotation coverage, a mid-range score 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 exactly two sentences with zero fluff. The purpose is front-loaded, and the usage note follows directly. It is appropriately sized for a simple read operation.

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 tool with no output schema, the description and schema together provide sufficient information: how to call it, what input to provide, and when to use it. Missing details like return format or error handling are not critical for a read-only, idempotent operation, so it is complete enough.

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%: both parameters have detailed descriptions, including the user_id guidance (exact provider ID, never display name/URL) and account_id disambiguation logic. The tool description itself does not add parameter-specific details, but since the schema already carries the full burden, the baseline of 3 is warranted.

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

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

The description clearly states the action ('Get an Instagram user profile') and the target resource (Instagram user), and specifies the input type ('provider user ID/username'). It also adds a usage context ('Use before follow/unfollow or identity-sensitive actions') that distinguishes it from the sibling instagram_get_my_profile and list tools. The verb-resource pair 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?

The description provides explicit when-to-use guidance: before follow/unfollow or identity-sensitive actions. It implies the need for a provider user ID rather than a display name, which is reinforced by the schema description. However, it does not explicitly name alternatives (e.g., instagram_get_my_profile for own profile), though the sibling tool names make that differentiation obvious.

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, and non-destructive behavior, so the safety profile is covered. The description adds the 'from the user's own account' scoping detail, which is useful, but it does not disclose pagination, ordering, or response format beyond that.

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 no filler. The action and scope are front-loaded, and the second sentence earns its place by stating the intended use case.

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