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?

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?

The description goes far beyond the destructiveHint annotation by detailing that the HMAC secret is returned only once on create/rotate, that URLs must be HTTPS to public hosts (private IPs rejected), and that deliveries are signed with X-Coldrig-Signature. It also explains that active:true re-enables auto-disabled subscriptions. This level of detail fully discloses critical behavioral traits.

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 that effectively front-loads the main action pattern. While it packs a lot of information, it remains clear and free of redundancy. A more structured format (e.g., bullet points) could improve readability, but it is still concise for the amount of information conveyed.

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 has no output schema, the description adequately explains that create/rotate return the secret once. It covers the signature format and URL constraints. It does not mention error cases or rate limits, but for a mutational configuration tool, the description provides sufficient context for an AI agent to understand the tool's behavior and requirements.

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 86% schema description coverage, the description adds significant meaning: it explains that 'action' determines required fields, that 'id' is required for update/delete, that 'eventTypes' must be specific enum values, that 'secret' can be rotated or auto-generated, and that 'note' is an ignored placeholder. This contextualizes and clarifies each parameter's role 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 manages outbound webhook subscriptions with three actions (create, update, delete), distinguishing it from the read-only sibling tool 'get_webhooks'. The verb 'manage' combined with specific actions makes the purpose explicit.

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

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

The description provides clear guidance for each action: create needs url and eventTypes, update needs id and one changed field, delete needs id. It explains the behavior of the 'active' and 'secret' fields. However, it does not explicitly compare with alternatives (though the only sibling for webhooks is read-only).

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?

The description adds significant behavioral context beyond the readOnlyHint annotation: server-side ramping limits, vendor-reported approximations vs first-party measurements, control loop using local signals only, and the actionHint structure in messages. These caveats are crucial for correct interpretation.

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 fairly long but well-structured: it front-loads the purpose, then details the return fields, messages array, and finally the alternative tool. Each sentence adds necessary value given there is no 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, the description fully documents the return structure: each mailbox field, the messages array with its fields, and important caveats about data sources. It also tells the user where to go for account-wide rollups, making it a complete standalone reference.

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. No parameter information is needed, and the description appropriately doesn't attempt to invent any.

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 'Warmup + provisioning progress per mailbox' which clearly states the resource and scope. It then lists the return fields, confirming it's a status/read operation. It explicitly distinguishes from siblings by saying 'Use account/metrics for account-wide rollups.'

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 an explicit alternative: 'Use account/metrics for account-wide rollups.' It also gives usage guidance on the messages array: 'poll this alongside the mailbox fields so you never miss one.' It doesn't enumerate all siblings, but gives clear enough direction for the main distinction.

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?

Annotations indicate destructive hint (true). The description adds behavioral context: steps schedule up front, suppressed leads are skipped, and idempotency key prevents duplicates. It also clarifies the platform does not write copy. These go beyond the annotation.

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 (two sentences) and front-loaded with the purpose. Every sentence adds value: supplies input list, behavioral notes, return value, and idempotency. Could be slightly more structured, but overall efficient.

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

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

Given 8 parameters, nested objects, destructive annotation, and no output schema, the description covers creation, idempotency, return value, skipped leads, and copy responsibility. It lacks explicit limits (max leads, sequence steps) but schema handles those, so completeness is adequate.

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

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

Schema coverage is only 13% (idempotencyKey). The description compensates by enumerating each parameter (name, offer, leads, sequence, sendWindow, timezone, stopOnReply) and explaining their purpose and interplay (e.g., steps schedule up front, suppressed leads skipped). This adds meaning beyond the schema types.

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

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

The description clearly states 'Create and activate a campaign on a lead list,' specifying a verb and resource. It distinguishes from sibling tools like list_campaigns, campaign_results, pause, which are not creation-oriented.

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 lists required inputs (name, offer, leads, sequence) and mentions idempotency retry behavior, but does not explicitly state when not to use the tool or compare it to alternatives. Prerequisites like infrastructure setup are not mentioned.

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 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?

Beyond the destructiveHint annotation, the description discloses that release is immediate, there is no mid-cycle credit, the lower price takes effect next renewal, and the minimum is 5/$99. It also specifies the return value structure (releasedCount, quote).

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 and information-rich within two sentences, but the use of parentheses and dashes makes it slightly less readable. However, every part adds value, so it earns a high score.

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 has only 2 parameters, no output schema, and a destructive annotation, the description covers behavior, parameter meaning, return values, and usage context completely. An AI agent can confidently invoke 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?

With 0% schema description coverage, the description fully explains both parameters: 'count' as the number of newest mailboxes to release, and 'acknowledged' as mandatory irreversible consent. It also adds billing context not in the schema (minimum 5/$99).

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 ('release your N NEWEST live mailboxes now') and the resource ('live mailboxes') with the specific verb 'downgrade'. It also distinguishes from sibling tools by naming alternatives for adding 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?

Explicitly states when to use this tool (to release mailboxes for downgrade) and provides clear alternatives for adding mailboxes. Details prerequisites like the mandatory acknowledgment, irreversibility, no mid-cycle credit, and minimum billing constraints.

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 is exceptionally transparent, detailing real sending volume, daily cap effects, refusal conditions with exact error codes, retryability, idempotency behavior, and a 404 case. This far exceeds the annotation's destructiveHint and gives the agent a complete behavioral model.

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?

Although the description is long, every sentence contributes essential behavioral details. It is logically structured: purpose, inputs/outputs, send-side effects, refusal behavior, idempotency, and error condition. No filler or repetition; it earns 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?

The description covers purpose, inputs, return shape, side effects, error handling, retry semantics, idempotency, and a 404 edge case. There is no output schema, but the description explicitly states the return shape. For a send operation with such nuanced constraints, this is 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?

With 67% schema description coverage, the schema already documents threadId and idempotencyKey. The description adds meaningful context: threadId must refer to a thread with a sending mailbox on record (404 otherwise), and idempotencyKey can be omitted but a body hash is used. This enriches the parameter semantics beyond the raw 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 'Send a reply on an existing thread, from the mailbox that sent it,' which uses a specific verb and resource, and clearly distinguishes this from sibling tools like launch_campaign or inbox. It also states the expected inputs and return value, making the purpose immediately obvious.

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 for when to use the tool (existing thread, mailbox that sent it) and includes warnings such as 'don't loop replies to manufacture volume.' However, it does not explicitly name alternative tools or state 'use this instead of X,' 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 only provide destructiveHint: false, so the description carries the full burden. It discloses async behavior, billing projections, idempotency convergence, domain adoption, DNS pending states, de-duplication, failure mode (400), and consent semantics for registerDomains. This is far beyond the minimal annotation and provides critical operational detail.

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 densely information-packed; every paragraph covers operational essentials such as rate limits, billing, idempotency, and edge cases. It front-loads the purpose and then details behaviors, making it structured logically despite its length. The word count is high, but no content is wasted.

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 11 parameters, nested registrant object, async execution, and billing side effects, the description covers the full lifecycle: provisioning, polling, retries, billing preview/actual, edge cases (adopted domains, pending DNS), and consent. It also references infrastructure_status for progress and currentDailyCap. No output schema is present, but the description specifies the response shape {jobId, billing} and billing fields, making it self-sufficient.

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

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

Schema description coverage is only 9% (idempotencyKey only), so the description must compensate. It explains the meaning of quoteOnly, registerDomains, registrant (full object fields), and idempotencyKey in detail, while listing all main inputs. It does not deeply explain persona or senderIdentity, but these are relatively self-evident from the schema names. Overall, the description adds significant meaning to key parameters.

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 'Provision sending infrastructure: buy branded lookalike domains, create mailboxes, start warmup,' a specific verb+resource+scope. It clearly differentiates from siblings like infrastructure_status (status polling) and remove_mailboxes (removal) by focusing on provisioning. This makes the tool's 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 usage guidance: 'pass quoteOnly:true first to preview' and 'Resend the SAME idempotencyKey to retry safely... send a NEW idempotencyKey when you genuinely want ADDITIONAL infrastructure.' It also tells the agent to 'poll infrastructure_status for progress' and warns about rate limits. It does not explicitly compare with all sibling tools, but the context is clear for when to use this tool vs status 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?

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.