Mailrith Email Marketing

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

Annotations already indicate non-read-only, idempotent, and non-destructive. The description adds valuable details: results expire in 24 hours, row limit of 100, workspace-change effect, retry advice, and permission requirement. 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 extremely concise—five sentences—each providing critical behavioral or usage information. All content is front-loaded and non-redundant. Every sentence earns its place, avoiding any 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 complexity of the input schema (nested object, multiple optional fields) and the presence of an output schema, the description covers all essential behavioral aspects: data source, range limits, queuing, expiration, row limit, side effects, permission, and retry guidance. This is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the description doesn't need to enumerate parameters. However, it adds meaning to date parameters by explaining behavior for ranges ≤31 days vs longer, which goes beyond the schema's format constraint. Other parameters (group_by, source_ids, etc.) are well-defined in the schema.

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

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

The title 'Create or reuse an analytics report' and description clearly state the tool's function. It specifies it creates reports with distinct behavior (rollups, date ranges, expiration, row limits), distinguishing it from the sibling analytics_get_report which retrieves existing 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 provides usage context (30-day inline vs queued longer ranges, expiration, permission requirement) but does not explicitly contrast with alternatives like analytics_get_report or other analytics tools. The sibling list helps infer when to use this tool for creation vs retrieval.

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

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

Adds behavioral context beyond annotations: reports are 'unexpired' and 'bounded', and pagination uses cursors. Annotations already indicate read-only and idempotent.

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: purpose, permission, pagination hint, and reference URL. No superfluous text.

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 permission, pagination, expiration, and includes an API reference link. Output schema exists, so return value details are not needed.

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%, but description links parameters to pagination behavior ('bounded pages' and 'returned cursors'), adding practical context.

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 starts with 'Returns one unexpired bounded analytics report by identifier', specifying a clear verb ('returns'), resource ('analytics report'), and unique qualifiers ('unexpired bounded'), distinguishing it from list or create 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?

Mentions required permission ('analytics:read') and pagination hints, but does not explicitly exclude scenarios or compare to siblings like analytics_create_report.

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 meaningful behavioral context beyond the annotations: 'Effect: workspace-change' discloses the side effect, 'Retry with the same idempotency_key' explains safe retry behavior, and 'Permission: automations:write' exposes an authorization requirement. Since annotations provide no positive hints (all false), this information is valuable. 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 compact and front-loaded: purpose, effect, retry guidance, permission, and API reference each earn their place. No filler or redundant wording.

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 a complex nested schema and output schema, the description covers key selection criteria (purpose, side effect, permission, retry) and points to an API reference. It lacks guidance on preflight validation or relationship to automations_preflight, but the schema and examples fill most 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?

Schema description coverage is 100%, with both body and idempotency_key already documented. The description repeats the idempotency_key guidance but adds no new parameter meaning. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 'Creates an automation in the authenticated workspace', using a specific verb and resource. This distinguishes it from sibling operations like automations_update and automations_list. The scope 'authenticated workspace' adds clarity.

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

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

The description provides some usage context: 'Retry with the same idempotency_key' and 'Permission: automations:write'. However, it does not explicitly state when to use this tool vs alternatives, such as mentioning automations_update for modifications. Usage is implied rather than explicitly contrasted with siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds useful context about the required permission ('automations:read') and workspace scope, exceeding what annotations provide.

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

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

The description is one concise sentence followed by permission and an API reference link. Every element earns its place, with no redundancy or filler.

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

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

This is a simple retrieval tool with one parameter, a rich set of annotations, and an output schema. The description covers the essential additional context (permission, workspace scope) and is complete for its intended use.

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 with automation_id described as 'The automation identifier.' The description adds no additional parameter semantics beyond that, so it does not exceed the baseline of 3 for high schema coverage.

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

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

The description states 'Returns one automation from the authenticated workspace,' which is a specific verb+resource with clear scope. This distinguishes it from automations_list (which would return multiple) and other sibling tools like automations_update.

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

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

The description clearly implies use when retrieving a single automation by ID, stating 'returns one automation.' It does not explicitly mention alternatives like automations_list for multiple automations, but the context is unambiguous and there are no exclusions or misleading statements.

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 safety (readOnly, idempotent, non-destructive). The description adds operational context: the workspace scope and pagination method, complementing annotations without contradiction.

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

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

Three sentences with no fluff: purpose, permission, and pagination. Every sentence earns its place.

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

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

For a simple list tool with full schema coverage and an output schema (inferred), the description covers scope, permissions, and pagination. No missing context for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining pagination cursors and the permission context, going beyond the schema's descriptions.

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

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

The description clearly states 'Returns automations in the authenticated workspace,' using a specific verb and resource. It distinguishes itself from siblings like automations_get by indicating a list operation.

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

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

The description provides the required permission (automations:read) and pagination guidance. While it doesn't explicitly exclude other uses, the context is clear and sufficient for a list tool.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool 'checks ... without running any action', reinforcing safe behavior, and details what is checked (definition and email delivery). It also includes the permission requirement and an API reference, providing additional 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?

The description is extremely concise: two sentences, a permission line, and an API reference. All information is front-loaded and relevant, with no redundant or extraneous content.

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

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

Given the simple single-parameter tool with full schema descriptions, annotations, and an output schema, the description covers the tool's purpose, what it checks, its safety profile, and prerequisites. It is complete for an agent to correctly understand and 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?

There is only one parameter (automation_id) with 100% schema coverage that already describes it as 'The Automation identifier.' The description does not add further semantics or usage details for the parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Checks', the resource 'Automation definition and email delivery prerequisite', and the constraint 'without running any action'. This distinguishes it from sibling tools like automations_send_test or broadcasts_send that execute actions. The purpose is specific and unambiguous.

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

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

The description explicitly notes that the tool checks readiness without running actions, implying its use for validation. It also specifies the required permission 'automations:read'. However, it does not explicitly contrast with siblings (e.g., when to use automations_send_test instead) or provide exclusions, leaving room for improvement.

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, destructiveHint=false, idempotentHint=true. The description adds that it 'does not run actions or write history', which reinforces the read-only nature. It also mentions required permissions and includes an API reference link for further details, adding useful behavioral context beyond the annotations.

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

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

The description is concise with two sentences: one explaining the tool's core functionality, and another listing permissions and an API reference link. No redundant or unnecessary information.

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

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

Given the presence of an output schema (not shown but noted), the description does not need to detail return values. It covers purpose, behavior, permissions, and a reference link. Could potentially mention error conditions or edge cases, but for a read-only preview tool, this is largely 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 100%, with both parameters clearly documented (automation_id and subscriber_id). The description does not add additional meaning beyond what the schema provides. Baseline score of 3 is appropriate since the schema adequately describes the 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 clearly specifies the verb 'shows' and the resource 'bounded path a selected Subscriber would take through the current saved conditions'. It distinguishes from other automation tools by emphasizing it doesn't run actions or write history, and implies it's a preview/simulation tool, which is distinct from preflight or execution 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 implies usage for previewing without side effects, but it does not explicitly state when to use this tool vs alternatives like automations_preflight or sequences_preview_journey. No 'when to use' or 'when not to use' guidance is provided.

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 useful behavioral context (external-email effect, permissions), but there is a contradiction with annotations: the description suggests idempotency via retry with key, while annotations set idempotentHint=false. This undermines trust.

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 with no redundancy. Each sentence adds distinct information: action, exclusions, and metadata (effect, permissions, idempotency, API reference). Front-loaded with the core purpose.

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

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

Given the output schema exists and annotations provide some info, the description is fairly complete—covering purpose, exclusions, permissions, and idempotency. It lacks details on error handling or rate limits, but is adequate for a test 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%, so the description adds limited value beyond the schema. It reinforces that recipient is a test address and subscriber_id is for personalization, but does not introduce new meaning.

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

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

The description clearly states the tool sends up to five automation email steps to a test address, and explicitly distinguishes from starting the automation. This differentiates it from sibling tools like automations_create or automations_get.

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 explains when to use the tool (testing automation steps without starting) and includes permissions and idempotency guidance. It could be more explicit about alternatives, but the purpose is well-defined.

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 annotations (destructiveHint, idempotentHint), the description discloses critical behavioral details: state restoration, preflight requirements, failure handling ('leave it paused and immediately report the failure'), retry semantics ('Retry after reading the current resource state'), and permission ('automations:write'). This significantly enriches the operational context.

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

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

The description is dense and lengthy, but every sentence conveys essential safety or procedural information. It is front-loaded with the core purpose, though the run-on structure could be improved with bullets or shorter sentences for easier parsing.

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 high complexity (nested schema, status transitions, concurrency checks), the description covers the full lifecycle: reading, pausing, updating, preflighting, restoring, and failure escalation. It also provides permission, effect, and retry guidance. The output schema covers return values, so no additional return description is needed.

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

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

Schema description coverage is 100%, so parameters themselves are documented, but the descriptions are generic ('The automation identifier'; 'The exact JSON request body...'). The tool description adds no parameter-specific meaning beyond the schema's existing field-level documentation, so baseline 3 is appropriate.

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

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

The description clearly states 'Updates an existing draft or paused Automation', specifying the verb and resource. It explicitly addresses running Automations with a distinct safety workflow, which differentiates it from sibling automations_update_status and automations_create.

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 procedural context: for running Automations, it mandates reading, pausing, updating, preflighting, and restoring status. It implies usage for modification of automation content/definition, but does not explicitly mention alternatives or exclusions like automations_update_status.

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 show readOnlyHint=false and destructiveHint=true, but the description adds valuable context: 'Effect: external-email' warns of external side effects, 'Retry after reading the current resource state' gives practical retry guidance, and permissions are listed. This goes beyond the basic annotations without contradicting them.

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

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

The description is concise and front-loaded with the action. It uses compact phrases for effect, retry, permissions, and API reference, with no filler or repetition. Every sentence contributes functional guidance.

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 an output schema, so return values need not be explained. The description covers core behavior, side effects, retry semantics, and permissions. It omits prerequisites like requiring the automation to exist, but that is standard and not a significant gap for a status-update 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 both automation_id and body having descriptions. The description maps the action verbs to status enum values ('starts'='running', 'pauses'='paused', 'returns to draft'='draft'), which is mildly helpful but largely redundant given the schema's enum.

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 starts, pauses, or returns an automation to draft, with the key qualifier 'without changing its definition.' This specific verb+resource+scope distinguishes it from sibling tools like automations_update, which handles definition changes.

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 use by noting it handles status changes only ('without changing its definition'), implying that automations_update is for definition changes. It does not explicitly name alternative tools, but the scope is well-defined enough for an agent to choose correctly.

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

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

Description adds context: cancellation only works if not yet accepted by provider, effect 'external-email', and retry behavior. Annotations already flag destructive hint, but description provides useful nuance.

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

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

Four sentences each add essential info: purpose, limitation, retry guidance, effects, permissions. No wasted words. Could be slightly restructured for even better front-loading.

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 presence of output schema and annotations, description covers usage, limitations, retry, and permissions. Adequate for a cancellation tool. Minor gap: no explicit return value description (but output schema likely covers that).

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 covers both parameters with descriptions (100% coverage). Description adds value by explaining idempotency_key usage for retries when response lost, enhancing practical understanding.

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 'Cancel a broadcast send' and description 'Requests cancellation for delivery work that has not reached the provider' clearly state the action and resource. It distinguishes from siblings like broadcasts_unschedule by specifying the condition (not yet provider-accepted).

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 notes that provider-accepted emails cannot be recalled (when not to use) and recommends retry with idempotency key. Also mentions required permissions. Lacks explicit comparison to alternatives like broadcasts_unschedule.

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

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

Beyond the annotations (which only state the hints are false), the description discloses the effect as 'workspace-change,' the required permission 'broadcasts:write,' and the ability to retry with the same idempotency_key. This adds meaningful behavioral context not present in the annotations.

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

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

The description is extremely concise, using four short sentences (plus a reference link) to cover purpose, effect, idempotency, permission, and API reference. Every sentence adds distinct value with no redundancy, and the purpose is front-loaded.

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

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

Given the complex schema with rich descriptions, annotations, and an output schema, the description provides sufficient high-level context: it creates a draft, requires a workspace change, uses an idempotency key, and needs a specific permission. It could mention relationship to sending/scheduling but that is outside the tool's immediate scope.

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% description coverage, including descriptions for body and idempotency_key, plus detailed nested property documentation. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description explicitly states it 'Creates a broadcast draft in the authenticated workspace,' providing a specific verb, resource, and scope. This clearly distinguishes it from sibling tools like broadcasts_send, broadcasts_schedule, or broadcasts_update.

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

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

The description implies usage for creating a draft, but does not explicitly state when to use this tool over alternatives or mention exclusions. The word 'draft' and the effect/permission hints give some context, but no explicit guidance is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, which covers the safety profile. The description adds valuable context beyond annotations: the required permission (broadcasts:read) and the fact that it returns any broadcast state, which helps the agent set expectations.

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

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

The description is two sentences: the first conveys the function and scope in a compact list of states, and the second provides permission and an API reference. No wasted words; every sentence adds value.

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

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

For a simple single-parameter retrieval tool with an output schema and rich annotations, the description is complete. It covers what the tool returns (all broadcast states), permission requirements, and links to API docs, leaving no obvious gap.

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

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

Schema description coverage is 100% for the single broadcast_id parameter, so the schema already fully documents the parameter. The description adds no additional parameter-level detail, matching the baseline 3 for high schema coverage.

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

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

The description uses a specific verb 'Returns' with a clear resource 'a broadcast' and enumerates the exact states (draft, scheduled send, active send, completed send), which clearly distinguishes it from sibling tools like broadcasts_list and broadcasts_get_send_progress.

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

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

The description implies a clear usage context: retrieving a single broadcast by ID regardless of its current state. It does not explicitly name alternatives or provide exclusion criteria, but the scope is sufficiently clear for an agent to select it over list/progress 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 already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context not covered by annotations: the exact return fields, the polling cadence, backoff strategy, terminal-state condition, and timeout. It also clarifies the permission requirement. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core purpose and then provides structured polling guidance. It is reasonably concise but contains slight redundancy between the initial polling interval sentence and the later 'Polling:' sentence, which repeats similar information (e.g., 5-10 seconds vs. at least 2 seconds, backoff to 30 seconds). Minor inefficiency but still well-organized.

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

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

For a polling-oriented tool with a terminal-state concept, the description is remarkably complete. It covers return value contents, polling intervals, backoff, timeouts, permission, and even provides an API reference link. The output schema exists, so return structure is already documented; the description fills the operational 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 only one parameter (broadcast_id) and 100% schema coverage, the schema already fully documents the parameter. The description does not add any additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Returns bounded delivery progress') on a specific resource ('broadcast send progress'), distinguishing it from sibling tools like broadcasts_get (which likely returns general broadcast details) and broadcasts_list. The additional details about rates, timing, outcome counts, and pause state further clarify the tool's niche.

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 operational guidance: polling until terminal state, interval recommendations (5-10 seconds, back off to 30 seconds), exponential backoff, and a overall timeout of 15 minutes. It also states the required permission (broadcasts:read). However, it does not explicitly mention when to use this tool versus alternatives, such as when to avoid polling or use a different broadcast-related endpoint.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the description adds value by stating the required permission and pagination behavior. For a read-only list operation, this is sufficient. 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 three concise sentences, front-loaded with the core purpose, and each sentence adds unique information (function, permission, pagination, link). 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?

Given the simplicity of the tool (list operation with 3 parameters, output schema present, annotations covering safety), the description covers purpose, permission, and pagination. It could mention result format briefly, but the output schema handles that. Fairly 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 coverage is 100%, so the input schema fully documents the three parameters (limit, search, starting_after). The description adds no additional parameter-level details, so it meets the baseline but provides no extra value.

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

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

The description clearly states what the tool does: 'Returns broadcast drafts, scheduled sends, active sends, and completed sends.' It uses a specific verb ('returns') and resource ('broadcasts'), and distinguishes from sibling tools like broadcasts_get or broadcasts_cancel.

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 mentions required permission ('broadcasts:read') and pagination guidance ('use bounded pages and returned cursors'), which helps usage. However, it does not explicitly contrast with alternative tools (e.g., broadcasts_get for single item) or provide when-not-to-use advice.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by listing exactly what is checked (subscriber estimate, provider capacity, etc.) and mentions the required permission and API reference, providing helpful 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 cover the tool's purpose and optionality, plus permission and API reference. Every sentence is essential and front-loaded with the core diagnostic function.

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 existence of an output schema (not shown), the description does not need to detail return values. It adequately covers the tool's scope, optional nature, and what is inspected, making it complete for a simple read-only diagnostic 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?

There is one parameter (broadcast_id) with full schema coverage. The description does not add additional meaning beyond the schema's 'The broadcast identifier.' Since schema coverage is 100%, a score of 3 is appropriate.

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

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

The title and description clearly state that this tool inspects broadcast readiness by checking subscriber estimate, provider capacity, sender setup, event tracking, and blocking issues. It is distinct from sibling broadcast tools (e.g., broadcasts_send, broadcasts_schedule) and other preflight tools (e.g., automations_preflight).

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

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

The description explicitly says the tool is optional ('not required before starting a durable send'), indicating when it's appropriate to use. However, it does not specify scenarios where it should be skipped or mention alternative tools for similar purposes.

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 annotations: 'uses Mailrith's durable scheduled-send path,' 'Effect: external-email,' 'Retry after reading the current resource state,' and required permissions. It also clarifies the non-immediate delivery behavior, which is crucial for an agent choosing between this and broadcasts_send.

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

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

The description is three sentences, front-loaded with the primary purpose, and includes only essential details (durable path, effects, retry, permissions, API reference). Every sentence earns its place without redundancy.

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

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

Given the tool's moderate complexity, the description fully covers purpose, behavior, side effects, permissions, and retry guidance. With an output schema present, there is no need to describe return values. The description is complete for an agent to select and 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% for both parameters and the nested scheduled_at field. The description adds no parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Schedules a draft for future delivery, or changes the delivery time of an existing scheduled Broadcast.' This specific verb+resource distinguishes it from siblings like broadcasts_send (immediate) and broadcasts_unschedule (cancels).

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

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

It provides clear context by noting 'does not start delivery immediately' and 'Retry after reading the current resource state,' which implies when to use it for scheduled delivery versus immediate send. However, it does not explicitly name alternative tools or state exclusions, so a 4 rather than a 5.

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

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

The description goes well beyond the annotations, disclosing async behavior ('A 202 response means the durable send was accepted, not that provider delivery is complete'), background checks ('calculates the exact Subscriber total and checks provider readiness in the background'), external side effect ('Effect: external-email'), permissions, and idempotency retry behavior. This is rich behavioral context that annotations alone do not provide.

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

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

The description is mostly concise and front-loaded with the main purpose, but contains redundancy: 'Reuse the same idempotency key if the response is lost' and 'Retry with the same idempotency_key' essentially repeat the same instruction. Otherwise it uses efficient sentences with useful details (permissions, API reference).

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, async delivery, idempotency) and the presence of an output schema, the description is remarkably complete. It covers acceptance semantics (202), background processing, retry behavior, permissions, and external effect. It does not need to describe return values since the output schema exists, and it answers the key operational questions a caller would have.

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 100% schema description coverage, the baseline is 3. The description adds value for idempotency_key by explaining its role in retries ('Retry with the same idempotency_key'), and it mentions that preflight_proof is optional and can seed estimates ('A valid proof can seed its checked estimate' though that is in schema). This adds some meaning beyond the schema, especially for idempotency.

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: 'Immediately creates durable preparation for a broadcast draft or scheduled send.' It specifies the resource (broadcast) and the action (immediate send initiation), and distinguishes itself from siblings like broadcasts_schedule or broadcasts_send_test by emphasizing 'durable preparation' and 'before delivery.'

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 this tool: to send a broadcast now, including drafts or scheduled sends. It also gives explicit retry guidance ('Reuse the same idempotency key if the response is lost'). However, it does not explicitly mention alternatives or when NOT to use it (e.g., scheduling vs. sending now), so it lacks explicit 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?

Adds valuable behavioral context beyond annotations: discloses external-email effect, required permissions, and idempotency retry behavior. No contradiction with readOnlyHint/destructiveHint 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?

Concise yet information-dense: action, prerequisite, personalization guidance, recipient flexibility, external effect, retry, permissions, and API reference. Every sentence serves a purpose without redundancy.

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

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

Covers prerequisites (existing broadcast with delivery connection), parameter acquisition (subscriber lookup), external side effect, retry semantics, and permissions. Output schema exists, so omitting return-value details is acceptable; the description is complete for the tool's complexity.

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 covers all parameters with 100% description coverage. The description adds practical guidance on using subscribers_list to find a subscriber and emphasizes the idempotency_key for safe retries, 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?

Clearly states it sends a test message from an existing Broadcast with an email delivery connection, using specific verb and resource. The Broadcast resource is explicit, differentiating it from automations_send_test and sequences_send_test siblings.

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

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

Provides clear context: existing Broadcast with email delivery, saved Subscriber ID for personalization, and that recipient may differ from saved subscriber. It directs users to subscribers_list when needed but does not explicitly contrast with sibling send_test tools, though resource names make the choice apparent.

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 include destructiveHint=true and idempotentHint=true. The description adds context beyond this by stating 'Effect: workspace-change' and specifying required permissions (live_actions:write, broadcasts:write). It also cautions to retry after reading current state, which is useful for concurrency. 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 compact, with the primary purpose in the first sentence. Additional facts (effect, retry, permissions, API link) are each presented in short, standalone segments. Every sentence adds value with no repetition or fluff.

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

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

For a simple one-parameter tool with output schema and annotations, the description covers the action, preconditions, error handling, and permissions. The API reference provides further depth. It is fully sufficient for an agent to select and 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?

The schema only describes broadcast_id as 'The broadcast identifier.' The description implies the identifier must refer to a scheduled broadcast (not draft or sent), adding meaningful semantic context. Since schema coverage is 100%, this extra hint raises the score above the baseline of 3.

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

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

The description clearly states the specific action: 'Returns a scheduled Broadcast to draft state before delivery starts.' This distinguishes it from siblings like broadcasts_cancel, which likely cancels delivery entirely rather than reverting to draft.

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

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

The phrase 'before delivery starts' provides a clear temporal condition for when to use the tool. 'Retry after reading the current resource state' offers operational guidance for handling failures, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already indicate a write and destructive operation, but the description goes far beyond by explaining the exact effect on scheduled broadcasts (unschedule/update/reschedule), the recovery behavior if the schedule cannot be restored, and the mandatory reporting to the user. It also mentions the workspace-change effect and the need to retry after reading current resource state, providing rich behavioral context not available in structured fields.

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

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

The description is longer than ideal, but every sentence carries critical procedural information about handling scheduled broadcasts and failure recovery. It is front-loaded with the core purpose and then logically flows into constraints and detailed workflow. The only minor drawback is the density of instructions in a single paragraph, which could be slightly restructured for readability, but it is still appropriately sized for the tool's complexity.

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

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

Given the tool's complex behavior around updating drafts and rescheduling, the description is remarkably complete. It covers all relevant edge cases: which states are disallowed, how to handle scheduled broadcasts, what to do on failure, and the user reporting requirement. The existence of an output schema means return values need not be described, and the description even includes permission and API reference links, 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 100%, meaning broadcast_id and body both have descriptions (e.g., 'The broadcast identifier' and 'The exact JSON request body defined by the Mailrith public API contract'). The tool description adds some usage context around broadcast_id (e.g., read by ID for scheduled broadcasts) but does not elaborate on the body fields, leaving that to the nested schema. This is adequate but does not exceed the baseline.

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 'Updates an existing Broadcast draft,' clearly stating the action and target. It distinguishes this tool from siblings by explicitly listing which broadcast states cannot be changed here (scheduled, running, completed, failed), making it stand apart from broadcasts_create, broadcasts_schedule, and similar 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 explicit when-to-use guidance: it is for drafts only, and for scheduled broadcasts it prescribes a specific unschedule-update-reschedule workflow, including reading the broadcast by ID first and asking the user for a new time if the saved time is unsafe. It also tells the user what to do if the update fails after unscheduling, effectively covering alternatives and 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by specifying the workspace scope, the required permission (custom_fields:read), and the notable return detail (ready-to-use token), which enriches the behavioral understanding.

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: two sentences. The first sentence front-loads the primary purpose and unique value (token), the second adds permission and an API reference link. Every clause contributes necessary information with no redundancy.

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

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

For a simple get-by-id tool with a single parameter, an output schema, and comprehensive annotations, the description fully covers what an agent needs: the resource scope, the distinctive return value (token), and the required permission. There are no significant gaps in context for correct invocation.

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

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

The input schema provides 100% coverage for custom_field_id with 'The custom field identifier.' The description adds that the field comes from the authenticated workspace, giving some contextual meaning, but does not add parameter-specific semantics like format, example values, or relationships. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool 'Returns one custom field from the authenticated workspace' and uniquely highlights the inclusion of the 'exact ready-to-use email personalization token,' distinguishing it from the sibling custom_fields_list. It specifies the action (returns), resource (custom field), and scope (authenticated workspace).

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 conveys clear context: use this to retrieve a single custom field with its personalization token. However, it does not explicitly mention when-not-to-use or name an alternative like custom_fields_list for fetching all fields, so it lacks a direct exclusion/alternative statement.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: 'bounded page', cursor-based pagination, required permission 'custom_fields:read', and the inclusion of personalization tokens. This goes beyond mere read-only hints.

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 tightly structured sentences cover function, permission, and pagination, with a reference link. Every sentence earns its place; no fluff or redundancy.

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

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

Given rich annotations, full schema description, and the presence of an output schema, the description covers all necessary aspects: purpose, permission, pagination behavior, and the distinctive token inclusion. Complete for a list operation.

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

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

Schema description coverage is 100%, with clear descriptions for limit, search, and starting_after. The description adds the concept of 'bounded page' and returned cursors, which reinforces starting_after's purpose but does not introduce new parameter-level detail.

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 'Returns' with the specific resource 'custom fields' and the scope 'in the authenticated workspace'. It also highlights the unique value (ready-to-use email personalization tokens), distinguishing it from the sibling custom_fields_get.

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 clear context for when to use: listing custom fields with pagination and required permission. It does not explicitly name alternatives or exclusions, but the sibling custom_fields_get makes the list-vs-get distinction implicit.

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, destructiveHint=false, and idempotentHint=true. The description aligns with these and adds useful behavioral context: the data is scoped to the authenticated bearer credential and no specific permission is required. It also points to an API reference, though it does not mention rate limits or error handling.

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, front-loaded sentence that immediately states what is returned, followed by two brief informative notes (permission and API reference). No filler or redundant wording. Every part earns its place.

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

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

Given the tool has no parameters, has an output schema, and annotations cover safety and idempotency, the description provides sufficient context: it enumerates the exact categories of information returned and notes the zero-permission requirement. It is complete for a simple read-only discovery endpoint.

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 schema describes everything. Baseline 4 applies because there is nothing for the description to add about parameters. The description focuses on return values rather than input semantics, which is appropriate.

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

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

The description uses the specific verb 'Returns' and clearly enumerates the resources returned (workspace context, discovery URLs, shared request conventions, supported webhook events, public resource operations). This distinguishes it from sibling tools like workspace_get, which likely only returns workspace context. The purpose is 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?

No guidance is given on when to use this tool versus alternatives, nor does it mention that it could serve as a discovery prelude to other API operations. The 'Permission: none' note is about auth, not usage context. There is no 'use this for...' or 'instead of...'.

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 'Effect: workspace-change,' clarifying the mutation scope beyond the annotation's false hints. It also mentions idempotency key retry behavior and required permission, which are not evident from annotations. No contradiction found.

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

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

The description is extremely concise, with the core purpose front-loaded and additional metadata in compact clause form. Every clause (effect, retry, permission, API reference) conveys essential information without redundancy.

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

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

For a create operation with a rich nested schema, the description covers the effect, permission, and idempotency behavior. The schema fully documents body parameters and the output schema is present, so return values are covered. It omits discussion of the starting_point_id creation path, but that is documented in the schema.

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

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

Schema coverage is 100% with descriptive comments for the body and idempotency_key. The description's mention of idempotency_key retry behavior essentially repeats the schema text ('Optional idempotency key for safe retries'), so it adds no new parameter semantics beyond the baseline.

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

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

The description states 'Creates a reusable email template scoped to the authenticated workspace,' which is a clear verb+resource+scope. However, it does not explicitly mention alternative sibling tools (e.g., email_templates_list, email_templates_update), so it lacks direct differentiation.

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 operational guidance such as 'Retry with the same idempotency_key' and 'Permission: email_templates:write,' which informs invocation. It also implies usage for creating templates, but it does not explicitly compare with alternatives or state when not to use this tool.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extra context by stating the required permission (email_templates:read) and linking to the API reference. It also confirms the template is 'linked to the authenticated workspace,' which provides operational context beyond the annotations.

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

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

The description is two sentences long, with the primary action stated first. The second sentence provides the permission and API reference, both useful for invocation. No redundant words or filler are present.

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

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

For a simple read tool with one parameter and an output schema, the description covers the core behavior, workspace scope, permission, and API reference. The annotations already handle safety attributes, and the output schema covers return values. Thus the description is complete for selecting and invoking the tool.

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

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

The input schema covers 100% of the parameter documentation; template_id is described as 'The email template identifier.' The description does not add any further semantic detail about the parameter itself. Since schema coverage is high, the baseline is 3, and the description does not elevate it.

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

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

The description clearly states the tool returns a reusable email template linked to the authenticated workspace. It uses a specific verb ('Returns') and identifies the resource ('email template'), distinguishing it from list or preview operations. The scope is also clear, noting the workspace association.

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 that this tool is for retrieving a single email template by ID, and notes the required permission. However, it does not explicitly mention alternatives like email_templates_list or email_templates_preview, nor does it state when not to use this tool. Thus it has clear context but lacks explicit exclusions or 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 indicate safe read-only behavior. The description adds permission scope and pagination details, enhancing 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?

Three concise sentences covering purpose, permissions, and pagination. No redundant information; each sentence earns its place.

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

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

With output schema present, the description sufficiently covers purpose, permissions, and pagination. Lacks a brief note on response structure but 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 covers all parameters with descriptions; description does not add new parameter meaning beyond what schema provides. 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 tool returns email templates for the authenticated workspace. It uses a specific verb ('Returns') and specifies the resource, but does not explicitly differentiate from sibling tools like 'email_templates_get'.

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 pagination guidance and permission requirement, but lacks explicit guidance on when to use this tool versus alternatives (e.g., get a single template).

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 destructiveHint=false. The description adds value by stating 'without sending or saving anything' and listing required permissions, reinforcing the read-only, preview nature.

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 plus a reference link. The purpose and behavior are front-loaded in the first sentence. 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?

The tool has 2 parameters and an output schema. The description covers purpose, effect (no save/send), and permissions. It is complete given the complexity and existing structured fields.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds minor context about using subscriber fields for personalization but doesn't provide new information beyond the schema.

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

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

The description clearly states the verb 'renders' and the resource 'one template using a saved Subscriber', distinguishing it from sending or saving. Sibling tools include email_templates_get/list/create/update, so the preview function is unique.

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

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

The description explains when to use (preview with subscriber data) and lists required permissions. It does not explicitly state when not to use or name alternatives, but the context of sibling tools implies it's for previewing, not sending.

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

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

The annotations already indicate this is a write, destructive, and idempotent operation. The description adds value by specifying the effect (workspace-change), the retry protocol, and the required permission, which go beyond the structured annotations. No contradiction detected.

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 remarkably concise, with the core action first followed by essential operational details (effect, retry, permission, API reference). Every sentence earns its place and no information is redundant or padded.

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 nested object parameters, an output schema, and rich annotations. The description covers the what, the workspace effect, the retry strategy, and the required permission. It does not describe the return value or when to use it vs create, but the output schema and clear purpose mitigate that. Missing explicit contrast with sibling tools is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description itself does not elaborate on parameters beyond naming content and enabled state, but the schema already documents the parameters and their constraints. The description adds no new parameter semantics, so a score of 3 is appropriate.

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

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

Clearly states the tool updates the content or enabled state of an existing email template. The verb 'updates' and resource 'email template' are specific and distinguish it from sibling tools like email_templates_create, email_templates_get, and email_templates_list.

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 actionable usage guidance by instructing to retry after reading the current resource state, which is important for conflict resolution. It also mentions the required permission and the workspace-change effect. However, it does not explicitly contrast with alternatives or give a when/when-not to use, though the purpose makes this largely implicit.

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, idempotentHint, and destructiveHint. The description adds context by specifying the required permission, which is a behavioral requirement not covered by annotations.

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

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

The description is two sentences with no wasted words. The purpose is front-loaded in the first sentence, and additional information (permission, reference) is in the second.

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 get-by-ID tool with a complete output schema and full schema description coverage, the description is sufficient. It includes permission requirements and an API link, leaving 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?

The input schema fully describes the single parameter (segment_id) with a clear description. The description does not add additional parameter meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Returns' and resource 'saved segment' with clear scope 'from the authenticated workspace'. It distinguishes from siblings like 'segments_list' and 'segments_preview'.

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

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

The description includes the required permission 'segments:read' and provides an API reference link. While it doesn't explicitly say when not to use this tool, the context is clear for retrieving a single segment by ID.

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 behavioral context beyond annotations, such as the required permission ('segments:read') and pagination behavior ('use bounded pages and returned cursors'). Annotations already mark the tool as read-only and idempotent, so the description complements these nicely without contradiction.

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

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

The description is extremely concise at three sentences. It front-loads the purpose, then adds permission and pagination details, and ends with an API reference link. Every sentence serves a 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?

For a simple list tool with three parameters and an output schema, the description covers the core aspects: what it returns, required permission, and pagination. It could mention that results are paginated with opaque cursors, but the schema already covers 'starting_after'. The presence of an output schema reduces the need to explain return values. Overall, it is 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 input schema has 100% parameter description coverage, so the description does not need to add much. The description mentions pagination but does not elaborate on individual parameters (e.g., 'search', 'starting_after'). The schema already provides adequate semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states that the tool returns saved segments from the authenticated workspace. It uses a specific verb ('returns') and resource ('saved segments'), and distinguishes itself from sibling tools like segments_get (which retrieves a single segment) by implying a list operation.

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

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

The description mentions the required permission ('segments:read') and provides pagination guidance. However, it does not explicitly state when to use this tool over alternatives (e.g., segments_get for a single segment) or when not to use it. The guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds specific return value (subscriber counts) and behavior (rejecting circular references). No contradiction, adds useful 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 sentences, zero waste. Includes permission and API reference efficiently. Front-loaded with purpose.

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

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

Given simple tool with rich schema and output schema present, description covers all needed context: purpose, parameter usage, permissions, and API reference. Sibling tools are differentiated.

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% (only body parameter fully defined). Description adds usage guidance for current_segment_id sub-field, clarifying its role in edits. Adds slight value beyond 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?

Description clearly states 'Returns subscriber counts for an unsaved segment definition' with specific verb+resource. Distinguishes from siblings like segments_get (saved segment) and segments_list by focusing on unsaved definition preview.

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

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

Provides explicit guidance on including current_segment_id for edits to avoid circular references. Mentions required permission (segments:read). Could be improved by stating when not to use, but context is clear.

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

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

The description adds value beyond annotations by specifying the exact fields returned and explicitly stating that provider credentials and configuration are never returned. This complements the readOnlyHint, idempotentHint, and destructiveHint annotations by detailing the data exposure.

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 three sentences, each providing distinct information: what the tool does, what it does not return, and permission/API reference. It is front-loaded with the core functionality.

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 presence of an output schema, the description satisfactorily covers the tool's purpose, limitations, and permission. It omits potential error cases or prerequisites, but for a simple get operation, this is acceptable.

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 100% schema description coverage, the description adds minimal additional meaning beyond the schema. The phrase 'by stable identifier' is already implied in the parameter description. The baseline score of 3 is appropriate.

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

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

The description clearly states it returns one enabled sender identity by stable identifier, listing the specific fields returned (name, address, provider type) and explicitly noting what is not returned (credentials and configuration). This distinguishes it from the sibling tool 'sender_identities_list', which presumably returns multiple identities.

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

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

The description implies usage when a specific sender identity is needed by identifier, but it does not explicitly state when not to use it or mention alternatives like 'sender_identities_list'. It provides clear context for its single-item retrieval purpose.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that provider credentials and configuration are never returned, and clarifies pagination uses bounded pages and cursors.

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: purpose, behavioral disclosure, and permission/reference link. No fluff, front-loaded with key purpose.

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

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

Given the simple parameters, annotations, and presence of an output schema, the description covers pagination, safety, and field exclusions completely. 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?

Schema coverage is 100% with clear descriptions for both parameters. The description adds 'bounded pages' context but does not significantly enhance parameter meaning 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 returns a bounded page of sender identities with specific fields (names, addresses, provider types) that can be used for Broadcasts and Sequences, distinguishing it from the sibling get 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?

The description implies usage for selecting sender identities in Broadcasts/Sequences and mentions permission and pagination, but does not explicitly contrast with alternatives like sender_identities_get or state when not to use.

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 hint flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description adds meaningful behavioral context: 'Effect: workspace-change' clarifies the mutation, 'Permission: sequences:write' identifies the required auth scope, and 'Retry with the same idempotency_key' explains safe retry behavior despite idempotentHint=false. 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 five short, declarative sentences, each providing distinct value: purpose, effect, retry behavior, permission, and API reference. It is succinct, front-loaded with the primary action, and contains no redundant or filler text.

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

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

For a complex create operation with a rich nested schema and an output schema, the description covers the essential operational context: what is created, the workspace-changing effect, required permission, safe retry, and a link to full API documentation. It does not mention calling sequences_preflight for validation, but the schema and output schema carry most of the structural detail, making this 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?

Schema description coverage is 100%, with the schema already describing the body as the 'exact JSON request body defined by the Mailrith public API contract' and idempotency_key as 'Optional idempotency key to make retries safe.' The description's mention of idempotency_key adds no new semantics beyond the schema, so it meets the baseline without needing to compensate.

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 'Creates a sequence in the authenticated workspace,' a specific verb+resource statement that clearly distinguishes this from sibling tools like sequences_update, sequences_get, and sequences_list, as well as other *_create tools. The scope 'authenticated workspace' adds useful context about where the operation applies.

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?

Usage guidance is only implied by the verb 'creates' and the sibling tool names; the description does not explicitly state when to use this over sequences_update or sequences_preflight, nor does it exclude cases like editing an existing sequence. The retry and permission notes are operational, not selection guidance, so the description meets the baseline but lacks explicit when/when-not direction.

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 destructiveHint=false, so the safety profile is covered. The description adds value by specifying the required permission (sequences:read) and providing an API reference link, which are not present in annotations.

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

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

The description is a single, front-loaded sentence stating the action, followed by useful permission and reference details. Every word earns its place; no filler or redundancy.

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

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

For a simple get-by-ID tool with an output schema, the description is sufficiently complete. It states the return scope, permission, and provides a reference for deeper details. It lacks explicit error/not-found behavior, but that is beyond the needs for this simple read operation.

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

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

Schema description coverage is 100% for sequence_id, and the description does not add any additional meaning beyond the schema's 'The sequence identifier.' The baseline of 3 is appropriate since the schema carries the full parameter documentation.

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 'Returns one sequence from the authenticated workspace,' which is a specific verb + resource + scope. It distinguishes from siblings like sequences_list (which would return multiple sequences) and mutation tools like sequences_update.

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

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

The description implies usage for fetching a single sequence by ID but does not explicitly contrast with sequences_list or state when not to use it. No exclusions or alternatives are named, so guidance is inferred rather than explicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds pagination behavior and permission requirement, enhancing 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?

Three sentences efficiently cover purpose, permission, and pagination. No fluff, 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?

With complete schema and output schema, description covers key aspects (permission, pagination). Could include note on filtering but schema covers it.

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 has 100% coverage with descriptions for all parameters. Description does not add significant parameter semantics beyond what 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?

Title 'List sequences' and description 'Returns sequences in the authenticated workspace' clearly state the verb and resource. Distinct from sibling tools like sequences_get or sequences_create.

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?

Description mentions required permission 'sequences:read' and pagination usage. However, it doesn't explicitly state when not to use or compare with other list 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 provide readOnlyHint=true and destructiveHint=false. The description adds that it checks published emails and delivery connection without sending email or changing data, which aligns with and supplements the annotations. 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?

Three sentences efficiently convey purpose, permission, and reference. The API reference line is slightly extraneous but not excessive. The key information is upfront.

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 simple input and presence of an output schema, the description covers the tool's purpose, non-destructive nature, and scope. It lacks sibling differentiation but is otherwise adequate for a preflight check tool.

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

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

The schema covers the single parameter 'sequence_id' with a description. The tool description does not add additional meaning beyond implying the parameter is the target sequence. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states it checks the saved Sequence, its published emails, and email delivery connection without changing data or sending email. The verb 'Checks' and resource 'saved Sequence' are specific, and the scope is well-defined.

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 mentions the tool is read-only and requires permission 'sequences:read', but it does not provide explicit guidance on when to use this tool versus other preflight tools (e.g., automations_preflight, broadcasts_preflight) or alternatives like sequences_get.

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 value beyond annotations by detailing the non-destructive, idempotent nature ('without enrolling or sending email') and specifying permissions. It does not contradict annotations and provides behavioral context (returns timeline, eligibility).

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 three sentences: main action, permissions, API reference. It is front-loaded with essential information, no fluff, but could be slightly more 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 the presence of annotations, full schema description, and an output schema, the description provides sufficient context for a preview tool. It explains the read-only preview behavior and permissions, covering completeness without needing to detail 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?

Schema coverage is 100% with clear parameter descriptions. The tool description does not add extra parameter details beyond the schema, but it is not needed. Description mentions 'selected Subscriber' and 'personalization and targeting' which adds minimal extra context.

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 returns the bounded saved email timeline and shows eligible messages without enrolling, using specific verbs ('returns', 'shows') and resource ('timeline', 'messages'). This distinguishes it from siblings like sequences_preflight or sequences_send_test.

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

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

The description implies usage for previewing without enrollment, but does not explicitly compare to sibling tools like sequences_preflight or sequences_send_test. No when-not-to-use or alternative names are provided, leaving guidance implicit.

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=true, and the description adds context about external email effects, permissions, and idempotency, 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, front-loads the main action, and includes necessary caveats without redundancy.

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

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

With output schema present and annotations provided, the description covers purpose, limitations, permissions, and API reference, making it complete for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor clarification about 'up to five' and 'explicit test address' but does not significantly enhance 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 explicitly states the tool sends up to five saved Sequence emails to a test address, clearly distinguishing it from siblings like automations_send_test and other sequence actions.

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 clarifies what the tool does not do (enroll, start, write delivery) and advises retrying with idempotency_key, but does not explicitly compare with 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 provide readOnlyHint, destructiveHint, and idempotentHint, but the description goes far beyond by disclosing the necessary multi-step behavior: reading by ID, pausing, bounded reads until is_updating is false, running preflight, restoring prior status only under conditions, and the safety failure handling. It also states the effect (workspace-change), permission required, and retry guidance—all extra context beyond the annotations.

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

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

The description is lengthy but each sentence carries essential operational information. It is front-loaded with the core purpose, then builds a clear cause-and-effect workflow. No sentences are wasted; even the retry and permission notes are valuable. It is structured to be read sequentially as a safe-update procedure, which suits the complexity.

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

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

Given the tool's complexity (nested object schemas, multiple potential states, and an output schema), the description is exceptionally complete. It covers the full lifecycle of an update, including failures, restoration, and never activating a non-running sequence. It also provides permission and API reference. Since an output schema exists, return values are handled separately, so no major 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?

The schema already provides descriptions for both parameters (sequence_id and body), giving 100% coverage. The description does not add further meaning to these parameters; it focuses on the procedural workflow rather than the argument semantics. The body parameter's complex structure is fully documented by the nested schema definitions, so the description rightfully leaves parameter details to the schema.

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

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

The description opens with 'Updates an existing paused Sequence,' which clearly states the verb and resource. It proceeds to differentiate the tool by describing its behavior for running sequences, making clear this is a full update tool rather than a status-only toggle. This distinguishes it from siblings like sequences_update_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?

The description gives explicit when-to-use guidance: it targets existing sequences and provides a detailed protocol for handling running sequences (pause, update, preflight, restore). It tells the agent when not to activate a sequence (never activate a non-running one) and recommends retry only after reading current state. However, it does not explicitly name alternative tools like sequences_update_status or sequences_preflight, though the workflow implies them.

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

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

Annotations include readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds valuable behavioral context beyond these: 'Effect: external-email' indicates real-world side effects, 'Retry after reading the current resource state' suggests concurrency considerations, and permissions are explicitly listed. It does not contradict annotations.

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

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

The description is four compact sentences, front-loaded with the primary action, then providing effect, retry guidance, permissions, and an API link. Every sentence adds information without redundancy.

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

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

Given the output schema exists and the tool is simple (2 parameters, one nested with an enum), the description covers purpose, usage context, behavioral effects, permissions, and retry guidance. It lacks explicit error scenarios or return value details, but those are partially covered by the output schema and the retry hint.

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 baseline is 3. The description adds minimal parameter-level detail—it implies that the body status field controls start/pause, but does not describe parameters beyond what the schema already provides. The body description in schema is generic ('exact JSON request body'), and the nested enum is self-explanatory.

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

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

The description uses a specific verb phrase 'Starts or pauses' with a clear resource 'one Sequence', and explicitly states it does not change content or delivery settings, which distinguishes it from sibling tools like sequences_update. This is unambiguous.

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

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

It provides clear context: 'without changing its content or delivery settings' implies it is for status-only changes, and 'Retry after reading the current resource state' is a specific usage instruction. However, it does not explicitly name alternative tools or provide a when-not-to-use exclusion beyond the implied scope.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description adds the effect 'external-email', retry guidance, and required permissions. This provides actionable behavioral context not covered by annotations.

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

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

The description is four sentences long, covering purpose, idempotency, effect, retry guidance, permissions, and a link. It is efficient but could be slightly more concise by omitting the API link or combining sentences.

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 presence of an output schema (not shown but flagged), the description covers idempotency, effect, retry guidance, and permissions. It is complete enough for a simple two-parameter tool with good annotations.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds no additional meaning beyond the schema. 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 uses a specific verb ('Adds') and resource ('Tag to a Subscriber'), clearly distinguishing this from sibling tools like 'subscribers_remove_tag'. The idempotency note further clarifies the exact behavior.

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?

While the description states what the tool does and its idempotent nature, it does not explicitly state when to use it over alternatives (e.g., when not to use it or prerequisites). The sibling tool 'subscribers_remove_tag' provides contrast, but usage context is implied rather than stated.

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

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

Adds behavioral details beyond annotations: idempotency, 'Effect: external-email', retry advice, and permissions. Annotations already indicate idempotentHint=true, so this adds value.

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

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

The description is concise (4 sentences) and front-loaded with the main action. Includes extra context but without excessive verbosity.

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 2-param tool with good annotations and an output schema, the description covers idempotency, effect, retry, and permissions. A reference to API docs further enhances completeness.

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

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

Schema coverage is 100% with clear descriptions. The description restates parameters without adding new semantic information, so baseline score applies.

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

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

The description clearly states the verb 'Adds' and the resources 'subscriber' and 'sequence', and indicates idempotent behavior, distinguishing it from sibling tools like 'subscribers_remove_from_sequence'.

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 retry guidance and permissions, but lacks explicit when-to-use or when-not-to-use instructions beyond the idempotency hint. It is clear in context of siblings.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds permission requirement ('subscribers:read') which is useful behavioral 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 sentences, all essential information included. No fluff. Front-loaded with purpose.

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

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

Given simple tool (single parameter, no nested objects, output schema present), description covers purpose, permission, and reference. Fully 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 covers 100% of parameter with description 'The Subscriber identifier.' Description does not add additional semantics like format or example. Baseline score due to high schema coverage.

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

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

Clearly states it returns one subscriber by stable identifier from authenticated workspace. Use of 'one' and 'stable identifier' distinguishes from list or update tools. Permission and API reference add specificity.

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

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

Implies usage for fetching a single known subscriber, but does not explicitly state when not to use or mention alternatives like subscribers_list. Still provides clear context.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds valuable behavioral context: sorting order (newest to oldest), pagination via cursors, and permission requirement. 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 extremely concise with three sentences covering purpose, permission, and pagination. Every sentence adds value, 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?

Given the presence of an output schema, the description does not need to detail return values. It covers purpose, scope, sorting, pagination, and permissions. Could mention that it returns a list, but the output schema likely handles that. Adequate completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add any parameter-specific guidance beyond the schema, but also does not detract. It passes the burden to 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 returns subscribers in the authenticated workspace, sorted from newest to oldest. It uses a specific verb 'Returns' and specifies the resource 'subscribers', distinguishing it from single-subscriber retrieval 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 mentions required permission ('subscribers:read') and pagination instructions, but does not explicitly guide when to use this tool versus alternatives like subscribers_get or other filter tools. Guidance is present but not comprehensive.

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=false, destructiveHint=true, idempotentHint=true. Description adds useful context: 'Effect: subscriber-change', permissions (live_actions:write, subscribers:write), and an API reference link. 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?

Description is four sentences, front-loaded with the primary action. Additional info (effect, retry, permissions, link) is relevant and non-redundant. Could be slightly more concise 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?

The tool has an output schema (not shown but flagged), so return value details are not required in description. Behavioral aspects (idempotency, effect, retry) are covered. No mention of error handling or rate limits, but sufficient for a focused mutation 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?

Input schema has 100% coverage with clear descriptions for both parameters (sequence_id, subscriber_id). The description adds no new information about their meaning or format beyond what the schema provides.

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

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

The description clearly states 'Removes the selected subscriber from the selected sequence', using specific verb and resource. It distinguishes from sibling tools like subscribers_add_to_sequence by focusing on removal.

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 says when to use (to remove a subscriber from a sequence) and what happens if the subscriber is absent (idempotent return). Provides retry guidance: 'Retry after reading the current resource state.' Does not explicitly list alternatives, but sibling context implies them.

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

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

Description adds value beyond annotations: idempotency (no change if tag missing), effect (external-email), retry guidance, permissions. 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?

Four sentences: core action, edge case, effect+retry, permissions+reference. Front-loaded, no redundant information.

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

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

Complete for a simple removal operation. Edge case, idempotency, effect, permissions, and output schema present. All necessary details 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?

Schema coverage is 100% with basic descriptions for both parameters. Description does not add further semantic detail beyond what 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?

Title and description clearly state the action (remove tag from subscriber). Description covers edge case (subscriber without tag) and distinguishes from sibling 'subscribers_add_tag'.

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?

Implied usage from sibling tools and description mentions retry advice and permissions. Does not explicitly state when not to use, but 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 already indicate destructiveHint=true and idempotentHint=true. The description adds behavior on omitted fields, blank values, and rejection of invalid values, which is helpful. 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 well-structured with the main action first. However, it contains seven sentences, some of which are redundant (e.g., effect and retry advice). Could be more concise.

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