agent-cold-email

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

Annotations set readOnlyHint=true, and description does not contradict. Description adds critical behavioral details: activationState semantics (trust over 'sent' counts), billing model, and what fields like 'teardown' mean when null. Provides transparency 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?

Description is lengthy but each sentence adds value. It is structured with a bullet-like list of fields and explanations. Some redundancy could be trimmed, but overall 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?

No output schema, so description must fully explain return values. It does so comprehensively: lists all key fields (brand, plan, status, billing, activationState, resource counts, usage, quota, deliverability, teardown) and explains the important ones (activationState, billing). Covers all necessary 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?

No parameters (schema coverage 100%), so baseline is 4. Description adds no parameter info because none exist, but that's acceptable.

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?

Title is null but description starts with 'Account overview' and lists specific fields (brand, plan, status, etc.). Clearly states it returns account-level overview data. No sibling tools overlap with this scope, so purpose 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?

Explicitly tells when to use alternatives: 'Use metrics for counts, infrastructure_status for per-mailbox health.' Implicitly, this tool is for account-level overview including billing and activation state.

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 annotation (destructiveHint: false), the description adds essential behavioral context: the tool is idempotent, will return success when re-acking, and will return 404 for non-existent message ids. This exceeds what annotations provide and fully informs the agent of critical side-effect and error behavior.

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

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

The description is exceptionally concise and front-loaded: the first sentence states the core purpose and effect, followed immediately by critical usage and behavioral details. Every sentence serves a distinct purpose with 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?

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description is fully complete. It covers purpose, effect, uniqueness, idempotence, and error behavior. An agent has all necessary information to 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?

Schema description coverage is 100%, so the schema already documents the single parameter. The description adds value by telling the agent exactly where to get the message id (from list_messages or infrastructure_status's messages[]) and that it is a string. A minor deduction because the schema already provides the same relational hint in the parameter description, so the added value is marginal but still helpful.

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 ('Acknowledge a message by id'), the resource ('message'), and the desired outcome ('sets it read so it stops surfacing as unacked'). It distinguishes the tool from siblings like list_messages and infrastructure_status by emphasizing that only this tool processes the acknowledgment.

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 when to use this tool ('to set readAt'), what not to rely on instead ('reading or listing messages never marks them'), and critical behavior ('the only thing that sets readAt'). This is exemplary guidance for an AI agent deciding between tools.

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

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

Discloses pagination (cursor-based), response shape (items[], nextCursor, item fields), and filters. Annotations already declare read-only, but description adds substantial 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 efficient sentences: first conveys merged feed types, second covers pagination, item structure, filters, and sibling alternative. 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?

Covers input filters, output structure, pagination, and alternative tool. Could mention cursor optionality or error handling, but sufficient for a simple list 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?

Despite 0% schema coverage, description adds meaning: default limit (50), max (200), that kind filters by event/deliverability, and that cursor enables pagination.

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

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

Clearly states it is a unified activity feed merging campaign events and deliverability actions, and distinguishes from sibling 'inbox' which is for replies only.

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

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

Explicitly tells when to use this tool vs alternative ('Use inbox for replies only') and describes filtering by kind, limit, and cursor pagination.

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 provide readOnlyHint, but description adds specifics: bounce is hard only, soft_bounce is separate, opens not tracked, and 404 for unknown campaign.

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

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

Three concise sentences front-load the purpose, then detail output fields and behavior, with no unnecessary words.

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

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

For a simple tool with no output schema, the description fully specifies return fields, error case, and behavioral quirks. Annotations add safety 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 already describes campaignId fully, but description adds context that it comes from launch_campaign, enhancing understanding beyond the schema's 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?

Clearly states it provides outcome counts for a single campaign, distinguishing from sibling tools like metrics (account-wide totals) and list_campaigns (all campaigns).

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?

Specifies input requirement (campaignId from launch_campaign) and explicitly tells when not to use: use metrics for totals and list_campaigns for multiple campaigns.

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 behavioral details beyond annotation: e.g., 'poll_dns advances pending_dns → active, or → abandoned after 7 idle days', 'acknowledge_consent does not remove your business's exposure', and that request_managed_mailboxes returns a billing projection. These provide crucial state machine and side-effect 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 long but efficiently packed with action-specific details using parentheses and vertical bars. It is front-loaded with the overall purpose. Minor improvement would be to break into bullet list, but it's still understandable.

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 10 parameters, no output schema, and destructive hint, the description covers all actions, required parameters, state transitions, billing, and transport options. It provides a complete mental model for the agent to invoke 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?

With 90% schema coverage, the description adds significant value by explaining parameter groupings per action, the meaning of domainRelationship enum values, the transport shapes, and the quoteOnly preview semantics. It provides a complete narrative of how parameters are used together.

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 handles 'Register or advance a BYO domain/mailbox intake' and enumerates five distinct actions each with a specific verb and resource. It distinguishes from sibling tools like get_byo_domains (read-only list) and configure_dashboard (different topic).

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?

For each action, the description specifies required parameters and context (e.g., 'register needs domain + domainRelationship', 'poll_dns needs id'). It also states that acknowledge_consent is REQUIRED before proceeding past pending_consent. However, it doesn't explicitly mention when not to use this tool versus 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?

Discloses destructiveHint=true via annotations and adds behavioral details: CAS for updates, conflict return format, and the need to fetch current state first. No contradictions with annotations.

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

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

Two concise sentences front-load the core purpose and action rules. No wasted words; each sentence serves a clear 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?

Covers actions, required params, CAS behavior, and prerequisite reading. Lacks detail on success response format (no output schema), but for a write tool with such rich schema, the description is largely 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?

Description adds significant value beyond the schema: clarifies required parameters per action (e.g., create needs name+layout, update needs id+rev+layout, promote/delete need id) and explains the rev parameter's CAS role. Schema coverage is high (83%), but description compensates for any gaps.

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

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

Description explicitly states 'Write a saved dashboard view' and enumerates four actions (create, update, promote, delete) with required parameters per action. Clearly distinguishes the tool's purpose from read-only siblings like get_dashboard.

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: 'Read the current rev+layout via get_dashboard first' and explains CAS conflict resolution for updates. Defines when each action is appropriate and how to handle stale revisions.

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 destructiveHint annotation, the description discloses that secrets are returned only once, URLs must be https to public hosts with private/metadata IPs rejected, and deliveries are signed with HMAC-SHA256. It also clarifies that the 'note' parameter is an ignored placeholder. This adds significant behavioral 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 dense but well-structured, using a pipe-delimited format to separate actions. Each sentence conveys actionable information: requirements, side effects, and security constraints. No redundant padding.

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

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

For a multi-action tool with seven parameters and no output schema, the description covers all necessary operational details: action-specific requirements, secret handling, URL constraints, signature scheme, and the re-enable/pause behavior. It is sufficiently complete for an agent to select and invoke correctly.

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

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

The schema already describes most parameters (86% coverage), but the description adds operational semantics: how action determines required fields, that rotating secret is done via update, that active:false pauses, and that create/rotate returns the secret once. This enriches understanding 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 tool's function: 'Manage an outbound webhook subscription' and enumerates the three actions (create, update, delete) with their specific conditions. This distinguishes it from sibling 'get_webhooks' which is presumably read-only.

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 conditions for each action: create requires url + eventTypes, update requires id + one changed field, delete requires id. It explains special cases like active:true re-enabling and secret rotation. However, it doesn't explicitly contrast with alternatives, so it's clear context without exclusions.

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 thoroughly discloses side effects and constraints beyond annotations: it creates a ticket, notifies an operator, deduplicates identical requests within an hour, and is subject to rate limiting. It also explains the 'needs_human' urgency bypasses the throttle. This is highly transparent.

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 excessively verbose and repetitive. It repeats the deduplication and throttle explanations multiple times, and the overall length is disproportionate to the simple functionality. It could be condensed into a few sentences without losing substance.

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 its verbosity, the description covers all necessary context: purpose, when to use, side effects, deduplication rules, rate limits, and account state handling. It leaves no ambiguity about the tool's behavior and limitations, making 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?

The description adds meaningful context to both parameters: 'body' is the message content, and 'urgency' influences behavior (e.g., 'needs_human' bypasses throttle). It clarifies default values and edge cases, fully enriching the schema which only provides types and constraints.

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: 'Reach a human operator' and 'Files a support ticket and notifies the operator'. It also provides specific examples of when to use it, distinguishing it from sibling tools like list_messages and infrastructure_status.

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 states when to use the tool ('for anything list_messages/infrastructure_status can't handle') and gives concrete examples like 'why is my account suspended?'. It also explains deduplication and rate-limiting constraints, which are crucial usage guidelines.

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 readOnlyHint=true. Beyond that, the description enriches transparency by detailing the output fields for both cases, the progression of byoStatus, and the additional data returned with an id. No contradictions.

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

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

Front-loaded with main purpose, then efficiently covers output differences, status progression, and sibling tool reference. Every sentence adds value with no waste.

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 lacking an output schema, the description fully explains return values for both invocation patterns, status lifecycle, and the relationship to the sibling tool. Complete for a read-only list/detail 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 100% with clear explanation of the 'id' parameter. The description restates the same semantics without adding new parameter-specific meaning, meeting baseline 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 clearly states the verb 'List' and the resource 'BYO domains', and distinguishes two use cases (listing all vs. getting full detail with id). It differentiates from sibling tool 'configure_byo_domain' which is for registration/advancement.

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

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

Explicitly tells when to use the sibling tool 'configure_byo_domain' instead ('to register a new one or advance it'), providing clear alternative guidance for 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?

The readOnlyHint annotation already declares it read-only. The description adds detailed return structure (list summary vs. full layout + rev) and explains the rev field's role in updates via configure_dashboard, exceeding the annotation baseline.

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 purpose, and every sentence adds unique value. No redundancy or waste.

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 (one optional parameter, no output schema), the description fully covers behavior, return structure, and relationship with sibling tool. Nothing significant 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 covers the id parameter with 100% description coverage. The description adds context by explaining the rev usage for updates, providing extra 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 it reads saved dashboard views and distinguishes two modes: list all without id, and get full layout with id. It also differentiates from the sibling configure_dashboard tool by stating it is for writing.

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 specifies when to use each mode (no id vs. with id) and points to configure_dashboard for writing. It could be stronger by explicitly stating when not to use it, but the context is sufficient.

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

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

Annotations indicate readOnlyHint=true, which aligns with a read operation. The description adds valuable behavioral context: secrets are never returned on reads, only shown at creation/rotation. It also details the exact structure of responses for both modes, going 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 is three sentences, each serving a clear purpose: stating the overall function, detailing output without id, detailing output with id, and an important security note. It is front-loaded, efficient, and contains no unnecessary 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?

Given the tool's complexity (two modes, delivery logs, secrets handling), the description covers all necessary aspects: purpose, parameter usage, response structures, and security behavior. There is no output schema, but the description adequately describes return values.

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

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

The input schema has 100% coverage for the single parameter 'id' with a description. The tool description adds further meaning by explaining the behavioral difference between omitting and providing the id, which enriches the semantic understanding beyond the schema's static 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 lists outbound webhook subscriptions, with two distinct modes: without an id returns a list with specific fields; with an id returns the subscription plus recent deliveries and attempts. It also distinguishes itself by noting secrets are never returned. This is specific and differentiates from 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 clear guidance on when to omit the id (to list all) and when to pass an id (to get a specific subscription with logs). It does not explicitly mention alternatives or when not to use the tool, but the guidance is sufficient given no similar sibling tools.

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

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

Annotations declare readOnlyHint=true, and the description confirms read-only behavior. It adds behavioral details like cursor-based pagination, the exact response fields, and default values for filters (includeNonreply, archived). No contradictions.

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

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

The description is a single dense paragraph with no fluff. Every sentence adds value: pagination format, response fields, filters, and sibling tool recommendation. Well-structured and front-loaded.

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

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

Despite no output schema, the description specifies the response structure. It covers all 8 parameters adequately, notes pagination behavior, and provides sibling differentiation. For a read-only list tool, it is 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 0%, so the description compensates by explaining all filter parameters (mailbox, campaign, label, read, includeNonreply, archived) and their meanings (e.g., includeNonreply includes bounces/OOO, archived enum values). It adds value beyond the bare schema.

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

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

The description clearly states the tool is a 'Unified reply inbox across mailboxes' that lists threads, and distinguishes it from the sibling tool 'thread' by saying 'Use thread for one thread's history.' It provides a specific verb and resource.

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

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

Explicit guidance on when to use this tool vs. the 'thread' tool is provided: 'Use thread for one thread's history.' The description also lists all available filters, helping the agent choose appropriate 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 only declare readOnlyHint=true, so the description carries the burden of behavioral disclosure. It thoroughly covers ramp limits, vendor-reported null semantics, feed-invisible vendor warmup, message severity/action semantics, idempotent retry behavior, and the fact that reading messages here does not mark them read. 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 description is long but front-loaded with the core purpose and densely packs necessary caveats. There is minor redundancy around message ordering and list_messages being the full surface, but the structure is logical and each major section earns its place given the complexity and lack of an output schema.

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

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

With no output schema and an empty input schema, the description must fully explain the return shape and semantics, and it does: domains, mailboxes, sendReady, mailboxHealth, messages, nextSteps, plus per-field meanings and edge cases. It also names related tools for follow-up actions, making it complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter semantics because none exist, but it richly documents the response fields and their meanings, which is the relevant semantic content for this parameterless tool.

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: 'Warmup + provisioning progress per mailbox.' It clearly distinguishes itself from siblings by naming account/metrics for account-wide rollups and list_messages for full message history, so the agent understands exactly what this tool reports.

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 and when-not-to-use guidance: poll it alongside mailbox fields, use account/metrics for account-wide rollups, use list_messages for complete history, and use ack_message to mark messages read. It also explains that sendReady is not a send gate, preventing misuse.

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

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

Annotations declare destructiveHint=false; description adds that labels are free-form categories and explains clearing via null, providing context 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 concise sentences, front-loaded with primary action, no wasted words.

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

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

Covers core functionality, parameter behavior, and sibling distinction. Lacks mention of potential errors or permissions, but sufficient for this simple tool.

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

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

Description adds meaning to both parameters: threadId context from inbox/campaign, label behavior including null to clear, and visual reference to dashboard chip. Schema coverage is 50% but description compensates 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?

Description clearly states 'Set or clear a triage LABEL on an inbox thread' with specific verb and resource, and distinguishes from sibling 'mark' tool.

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

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

Explicitly contrasts with 'mark' tool and mentions filterability via inbox label param, but lacks explicit when-not-to-use or alternative scenarios.

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

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

Discloses critical side effects: campaigns send real mail, identical launches are duplicate-refused, idempotency key replays original results, and the platform does not write copy. This goes far beyond the destructiveHint annotation and informs safe 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?

Every sentence serves a purpose: purpose, parameter list, scheduling behavior, return value, duplicate prevention, idempotency retry, and edge-case exception. The description is front-loaded with the core function and remains efficient despite its length.

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

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

Covers purpose, required inputs, return value, duplicate prevention, retry semantics, and when launches are allowed or blocked. For a destructive tool that sends real mail, this provides sufficient operational context for an agent to act 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?

With only 13% schema coverage, the description compensates by enumerating all eight parameters and explaining the structure of 'sequence[] (per step: subject, body, delayDays)' plus the idempotencyKey behavior. However, sendWindow, timezone, and stopOnReply are merely listed without additional semantic detail, leaving some meaning to inference.

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

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

The opening sentence clearly states the action ('Create and activate a campaign on a lead list') with a specific resource. It distinguishes itself by adding that campaigns 'send real mail' and that suppressed leads are skipped, making the tool's primary function 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?

Explicitly defines when a launch is refused (duplicate within 60 seconds), advises 'check that campaign instead of relaunching' as an alternative, explains idempotency retry behavior, and states that deliberate relaunches after the window are never blocked. These are clear when-to-use and when-not-to-use guidelines.

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. The description adds behavioral context: returns specific fields and sorted newest first. While useful, it does not significantly go beyond what annotations already imply (safe read operation).

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 waste. First sentence delivers core function and output format. Second sentence provides usage alternatives. Efficient and well-structured.

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

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

For a tool with no parameters and no output schema, the description explains the output format, sort order, and alternatives. It is fully sufficient for an agent to understand and correctly invoke the tool.

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

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

No parameters in schema (100% coverage), so baseline is 4. The description does not need to add param info, but it mentions output fields which is not required for this dimension. No issues.

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 'List every campaign at once' and specifies the exact fields returned and sort order. It distinguishes from sibling tools by mentioning 'no per-campaign lookup needed' and explicitly naming alternatives (campaign_results, metrics).

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

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

Explicitly provides guidance: 'Use campaign_results for one campaign's counts, metrics for account-wide totals.' This tells the agent when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description adds value by detailing cursor-pagination, return structure, and available filters. There is no contradiction; the behavior is fully disclosed.

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

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

The description is about four sentences, front-loaded with action and pagination, followed by return structure, filters, and sibling guidance. It is efficient but could be slightly more concise by omitting the full field list (though no output schema exists).

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 list tool with 6 parameters, no output schema, and no nested objects, the description provides complete context: purpose, pagination method, return format, filters, and relationship to siblings. No gaps remain.

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 carries the burden. It lists four filters (campaign, interestStatus, suppressed, replied) that map to four of the six parameters. The remaining two (limit, cursor) are pagination parameters implied by 'cursor-paginated', but not explicitly described. This is sufficient but not perfect.

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

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

The description clearly states the action (list/export leads) and the resource (leads with contact-level disposition). It distinguishes from siblings by mentioning update_lead and suppress_lead as alternatives for write operations, and explicitly notes this is the export surface without a separate CSV endpoint.

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

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

The description provides explicit guidance on when to use this tool (for listing/exporting leads) and when to use alternatives (update_lead for writing disposition, suppress_lead for opting out). It also implies when to paginate to dump the full book.

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

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

Annotations already declare readOnlyHint=true, and the description adds significant behavioral context: listing never marks messages as read, null readAt means not acked (not unseen), sorting order, and detailed severity semantics. No contradictions.

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

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

The description is long but front-loaded with the main purpose. It efficiently packs sorting, return structure, and severity meanings. Slightly verbose but each sentence adds value. Could be tightened by separating severity details, but overall well-structured.

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

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

Given no output schema, the description explains the full return structure and behavior. It covers sorting, severity meanings, and readAt semantics. The only gap is the missing explicit description of the limit parameter, but the schema covers its constraints. Mostly complete for a complex 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 0%, so the description must compensate. It mentions cursor-paginated and implies cursor usage via nextCursor, but does not explicitly describe the limit parameter or its constraints. The schema provides default/min/max but the description adds no extra meaning for 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 it lists system and operator messages with cursor pagination. It distinguishes from sibling infrastructure_status by noting that tool only shows the newest 5 unacked messages, while this is the full paginated surface.

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

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

Explicitly tells when to use this tool (to list all messages) versus ack_message (to acknowledge one by id) and mentions infrastructure_status as a quick alternative. Also provides behavioral guidance on how to handle different severity values, including retry advice for 'operator_pending' and warning against retries for 'terminal'.

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 destructiveHint=false, which aligns with updating read state. Description discloses 404 for unknown thread, but could explicitly mention idempotency or safe behavior.

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

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

Concise, well-structured description with clear purpose, inputs, outputs, error case, and sibling differentiation. No unnecessary 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?

Given the tool's simplicity and annotations present, the description covers all necessary context: inputs, outputs, error handling, and when to use alternatives.

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% (only threadId has description). Description provides meaning for status enum values and clarifies threadId source (from inbox or campaign events), compensating for schema gaps.

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

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

The description clearly states the tool sets a thread's READ-STATE for inbox triage, specifies valid status values, and distinguishes it from sibling tools like label_thread and reply.

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

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

Explicit usage guidance: explains when to use this tool (for read/archive flag) and when to use alternatives (label_thread for labels, reply to respond). Also explains how to refetch archived threads.

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

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

Description adds context beyond readOnlyHint annotation, specifying it is summed tenant-wide, includes only hard bounces, and notes opens are not tracked. No contradiction.

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

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

Two concise sentences front-loading the main purpose and immediately adding usage alternatives. 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?

Even without output schema, description fully explains what data is returned (list of outcome totals) and scope. No gaps.

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

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

With 0 parameters, description does not need to add parameter info, meeting baseline. No missing details.

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

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

Description clearly states it provides account-wide outcome totals across all campaigns, listing specific metrics. It directly distinguishes itself from sibling tools like campaign_results and list_campaigns.

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

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

Explicitly tells when to use this tool versus alternatives: 'Use campaign_results for one campaign, list_campaigns per-campaign, or account for billing/quota.'

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

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

Description explains that status becomes 'paused', tick scheduling stops, already-sent mail is unaffected, and there is no resume tool. This adds behavioral context beyond the destructiveHint annotation, which is consistent with the tool's effect.

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

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

Three sentences: first gives purpose and effect, second specifies input and output, third covers error case and alternative. Front-loaded and efficient with no superfluous words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, effect, input, output, error case, and alternate tool. Missing are potential side effects (e.g., notifications) or permissions, but these are not critical. Sufficiently 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 single parameter campaignId is fully described in the schema (100% coverage). The description only restates 'Input: campaignId' without adding new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Pause ONE campaign'. It specifies the status change to 'paused', explains the effect on scheduling, and explicitly distinguishes from sibling tool pause_all. No 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 context for when to use this tool (single campaign) vs pause_all, notes that already-sent mail is unaffected and that there is no resume tool. Also mentions 404 error if campaign not found. Could be improved by stating when not to use (e.g., if wanting to resume later).

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 include destructiveHint: true, and description elaborates: changes status of all active campaigns to 'paused', returns { pausedAll: true }. No contradiction. Full behavioral 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?

Extremely concise: two sentences plus sibling note. Every sentence provides essential information. Front-loaded with action.

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

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

Covers purpose, effect, return value, and alternative tool. No output schema but return described. Sufficient for an agent to use correctly.

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

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

No parameters exist, so schema coverage is 100%. Description adds no parameter info, which is acceptable. Baseline for 0 params is 4.

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

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

Clearly states verb (pause), resource (all active campaigns), and effect (status to 'paused'). Distinguishes from sibling 'pause' by specifying scope (EVERY vs single).

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

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

Explicitly mentions alternative tool 'pause' for single campaign, providing guidance on when to use each. Could be more explicit about when not to use, but enough context is given.

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

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

The description goes far beyond the destructiveHint annotation. It discloses that the release is irreversible, immediate for provisioning but no mid-cycle credit, that releasedCount can be less than requested, that failedCount mailboxes remain live and billed, that deduplicated means no re-release, and that idempotency keys freeze the mailbox set. This is exemplary transparency for a destructive operation.

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 earns its place given the complexity of the operation. It is front-loaded with the core purpose and then systematically covers return values, idempotency, retries, and error handling. Slightly verbose but justified for a destructive, irreversible operation with subtle idempotency semantics.

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 (destructive, irreversible, idempotency, partial failures, billing implications) and the lack of an output schema, the description is remarkably complete. It explains all return fields (releasedCount, failedCount, unreleased, billing, deduplicated), error handling (409), and edge cases (deduplicated after 30-day window). No gaps identified.

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% (only idempotencyKey has a description), but the description compensates richly. It explains count is RELATIVE (releases that many more, not sets fleet size), acknowledged must be true and is a consent, and idempotencyKey semantics are fully detailed (first call resolves set, retries finish stragglers, new key for second downgrade). This far exceeds 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's purpose: 'Downgrade: release your N NEWEST live mailboxes now and lower the billed quantity.' It specifies the verb (release/downgrade), the resource (mailboxes), and the scope (N newest, relative count). It also distinguishes from siblings by explicitly noting 'To ADD mailboxes use setup_infrastructure / configure_byo_domain (request_managed_mailboxes).'

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 extensive usage guidance: when to use (downgrade), when not to (adding mailboxes), prerequisites (acknowledged must be true, minimum 5 mailboxes/$99), and alternatives (setup_infrastructure, configure_byo_domain). It also explains retry behavior, idempotency key usage, and 409 handling, which is critical for correct invocation.

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?

Despite the destructiveHint annotation already indicating mutation, the description goes far beyond by detailing side effects (daily cap counting, refusals with specific error codes), idempotency mechanics (same-key retries collapse), and deduplication nuances (what deduplicated:true/false actually means, the 10-minute body-hash window, and the possibility of deduplicated:false on a long-delayed repeat). This is rich behavioral disclosure that prevents misuse. 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 description is long but every sentence provides non-redundant information. It front-loads the core purpose, then logically progresses from send consequences, to refusal conditions, to idempotency, to deduplication semantics. There is no fluff or repetition; the density is justified by the complexity of the tool's behavior. Each clause earns its place.

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

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

The tool has no output schema, so the description must fully explain return values, which it does: it explains messageId and deduplicated semantics, error codes, and retryability. It also covers prerequisites (mailbox on thread), side effects (cap increments), and edge cases (provider-side dedup). For a tool with this level of subtlety, the description is comprehensive and leaves no critical 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?

The schema covers threadId and idempotencyKey with descriptions, but body lacks one. The description compensates by explicitly listing 'Inputs: threadId, body' and explaining how body is used (it can be varied to avoid deduplication) and how idempotencyKey works in detail (body hash fallback, need for stable key). It adds meaningful context beyond the schema, especially for idempotencyKey, though it doesn't individually describe each parameter. Given the 67% schema coverage, the description fills the gap well.

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 clear, specific verb+resource statement: 'Send a reply on an existing thread, from the mailbox that sent it.' This immediately distinguishes the tool from siblings like launch_campaign or ack_message, and the scope is well-defined. It also states the return shape, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool (to reply to an existing thread), conditions that cause refusals, and clear advice on retry behavior (e.g., 'stop retrying and don't loop replies to manufacture volume'). It also contrasts with campaign sends ('governed exactly like campaign sends'), which clarifies its place among alternatives, and notes the 404 condition when no sending mailbox exists.

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 minimal (destructiveHint:false only), so the description carries the full burden. It discloses billing semantics, idempotency behavior, no background retry, no job store, deterministic addressing, domain adoption, ramp limits, and refusal-before-spend conditions. 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?

Front-loaded and information-dense, but written as one massive paragraph with repeated caveats around idempotency, billing, and retry behavior. Every detail matters, but the presentation is heavier and more redundant than needed.

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

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

No output schema exists, so the description compensates by specifying the return shape ({ jobId, billing }), provisioning state meanings, nextSteps behavior, partial-capacity billing, and error codes such as 400 registrar_optin_missing and 503 registrar_unarmed.

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 8%, but the description compensates richly. It explains quoteOnly, slots semantics for domains/inboxesEach, distribution as an alternative, registerDomains consent/revocation, registrant persistence/defaults, persona determinism, and idempotencyKey replay-only behavior.

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 leads with a specific action: 'Provision sending infrastructure: buy branded lookalike domains, create mailboxes, start warmup.' This clearly scopes the tool and distinguishes it from siblings like infrastructure_status and configure_byo_domain.

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: preview with quoteOnly:true, poll infrastructure_status for dailyCap/nextSteps, call contact_operator for capacity_pending, and do not poll jobId. It also explains when retries are safe and when an error is self-correctable versus operator-facing.

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 it cancels pending sends, marks campaign-lead rows as suppressed, and that last-write-wins relabels reasons to 'manual'. This goes beyond the destructiveHint annotation, providing actionable behavioral details like note not being persisted.

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 with 5 sentences, no fluff, and front-loads the core purpose. Each sentence adds value, covering cause, effect, limitations, and parameter usage efficiently.

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 destructive tool with no output schema, the description is thorough: it covers the action, side effects, exclusivity of reason, non-persisted note, and irreversibility. All critical context is 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?

With 0% schema description coverage, the description compensates well: email is implied as the target, reason is clarified as fixed to 'manual', and note is stated as accepted but not persisted. The description adds meaning beyond schema but could elaborate slightly more on email validation.

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 suppresses an email address tenant-wide for all campaigns, specifying it as the manual opt-out path for emails missed by typed-unsubscribe matcher. It provides a specific verb and resource, and distinguishes itself from automatic opt-out methods.

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 when to use this tool (manual opt-outs) and when not to use it (bounce/complaint/unsubscribe are handled automatically). It also warns of irreversibility with 'There is no un-suppress tool' and explains the reason field is fixed to 'manual'.

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. Description adds behavioral details: returns oldest first, mailboxEmail null before first send, and 404 behavior. This adds value beyond annotations.

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

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

Front-loaded with purpose, then return structure, then usage guidelines. Every sentence is necessary and efficient, 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?

Given no output schema, description provides full return structure and field details. Covers edge case (404) and input source. Sibling tools are referenced. Complete for a simple read tool.

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

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

Schema coverage is 100% with description for threadId. Description adds that threadId comes from inbox, providing context beyond schema for a single parameter.

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

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

Description clearly states 'Full message history for ONE thread' with a specific verb (get history) and resource (thread). It distinguishes from siblings by directing to use 'inbox' for listing, 'reply' for responding, etc.

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

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

Explicitly tells when to use this tool vs alternatives: 'Use inbox to LIST threads; reply to respond; mark/label_thread to triage.' Also mentions 404 for unknown threads.

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

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

The description adds significant behavioral context beyond the sparse annotations (only destructiveHint=false and title). It details the partial patch semantics, required field combinations, and server-enforced enum. However, it does not mention whether the tool creates a new lead if the email is not found or what happens on validation errors, which prevents a score of 5.

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

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

The description is a single paragraph that front-loads the core purpose and then provides details. It is not overly verbose, but could be slightly more structured (e.g., bullet points) for easier parsing. Every sentence adds value, so it scores above average but not maximal.

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 lacks information about return values or success/failure indicators (no output schema). It does not describe error cases (e.g., email not found, invalid enum). Given the tool has 4 parameters and no output schema, the description should at least hint at the response behavior to be fully complete. Sibling tools like suppress_lead are mentioned but not in context of return values.

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 0% schema description coverage, the description compensates well by listing each parameter, its type, constraints (e.g., max length, max items, enum values), and the fact that interestStatus is server-enforced. It clarifies that email is required and at least one of the other three must be provided. However, it does not repeat all schema constraints precisely (e.g., tags minLength=1), which would have earned a 5.

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

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

The description clearly states the tool's purpose: 'Record what you learned about a contact... as a durable, contact-level disposition — keyed by email, visible across every campaign that lists them.' It uses specific verbs ('record', 'update') and names the resource (lead disposition). It distinguishes itself from sibling tools by explicitly mentioning suppress_lead for 'do not contact' and list_leads for filtering.

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 and when-not-to-use guidance. It explains the partial patch behavior, required fields, and enum constraints. It directly tells the agent to use suppress_lead instead for 'do not contact' dispositions. This makes the decision boundary clear.

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