Mailrith Email Marketing

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

It discloses important behaviors: 'Runs from compact rollups', 'Results expire after 24 hours', 'never exceed 100 rows', 'Effect: workspace-change', 'Retry with the same idempotency_key', 'Permission: analytics:read'. Annotations include readOnlyHint: false, but description contradicts? No, readOnlyHint=false means it might write, and effect workspace-change indicates mutation, so consistent. It adds value beyond annotations by specifying the workspace-change effect and permission requirement, and the expiration/results limits are useful. Only minor: doesn't mention details about queuing behavior (how to poll?), but overall good.

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 very concise, with 6 short sentences covering key aspects: data source, range limits, expiry, row limit, effect, retry, permission, and API reference. Every sentence adds value, no fluff. Front-loaded with the most important operational detail (rollups and range). Excellent structure.

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 complexity (has nested body schema, output schema, idempotency key), the description covers essential operational details but misses some aspects like what the output schema contains or how to handle queued results (e.g., polling a job ID). However, the output schema exists, so the description doesn't need to explain return values. The description covers expiration, row limit, permission, and retry. It's fairly complete for a creation tool, but doesn't mention that it can reuse existing reports if same parameters? The title says 'Create or reuse' but description doesn't explain when reuse happens. That could be a gap. But overall it's good.

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

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

Schema description coverage is 100%, so the schema already documents body and idempotency_key. The description adds 'Results expire after 24 hours' which indirectly relates to parameters? Not really. It doesn't add additional meaning about the parameters beyond what's in the schema, such as the meaning of 'from', 'to', 'group_by' etc. But the schema itself has descriptions for body and idempotency_key, and the nested object has field descriptions? Actually the schema doesn't include descriptions for individual fields like 'from' and 'to' (only format: date). So the description does not add semantic meaning for the date range or other fields. However, it mentions 'Ranges through 31 days complete inline' which gives context for the date range. That's a small addition. Baseline 3 because schema coverage is high, but the description could have elaborated on the meaning of group_by or source_ids, but it doesn't. So 3 is appropriate.

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

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

The description states 'Runs from compact rollups' and 'Effect: workspace-change', and the title says 'Create or reuse an analytics report', which is specific about the action and result. It distinguishes from sibling analytics_get_report by mentioning creation/reuse. However, it could be more explicit about the difference between creating and reusing, but overall purpose is clear.

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

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

It mentions constraints like 'Ranges through 31 days complete inline; longer ranges are queued' and 'Results expire after 24 hours' which tells when to use it (for short ranges) and implies queuing for longer ones. It doesn't explicitly name alternatives, but the context of siblings like analytics_get_report implies retrieval vs creation. Additional guidance on when to reuse vs create would be helpful, but the description is decent.

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?

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds 'Effect: workspace-change' and permission requirement, which is useful. However, it doesn't disclose details about what happens on creation (e.g., whether it activates immediately, validation behavior) beyond the schema. 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 concise (three sentences) and front-loaded with the primary action. It includes essential operational details (effect, retry, permission, API reference) without fluff. Slightly dense but efficient.

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

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

Given the complex nested schema (AutomationDefinition with many step types) and output schema present, the description is adequate but not complete. It doesn't mention validation rules, activation behavior, or how to construct the definition. The API reference link helps, but the description could provide more guidance on the automation definition structure.

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

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

Schema description coverage is 100% (both body and idempotency_key have descriptions). The description adds the idempotency_key retry semantics, but the body parameter is already described as 'exact JSON request body defined by the Mailrith public API contract.' The description doesn't add much beyond the schema, 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 the tool creates an automation in the authenticated workspace, which is a specific verb+resource. It distinguishes from siblings like automations_update and automations_list, though it doesn't explicitly contrast with them.

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

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

The description mentions retry with idempotency_key and permission requirement, but does not provide explicit guidance on when to use this tool versus alternatives like automations_update or sequences_create. The context is clear but no exclusions or alternative recommendations are 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=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?

Beyond the annotations, the description discloses the external-email side effect, confirms that the Automation is not started, and explains safe retry behavior with the same idempotency_key. It also lists required permissions. These details give an agent a clear and accurate behavioral profile without contradicting the annotations.

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

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

The main action is front-loaded in the first sentence, followed by compact, high-signal labels for effect, retry semantics, permissions, and API reference. Every part earns its place, and the description is appropriately sized for a tool with a nested request body and three top-level parameters.

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

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

For a mutation tool with an output schema and fully documented schema fields, the description covers the external side effect, the non-start of the Automation, retry behavior, and permissions. The nested request-body details are already fully specified in the schema, so nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents automation_id, body, recipient, message_ids, subscriber_id, and idempotency_key. The description reinforces 'up to five', 'selected saved', and retry behavior, but it adds little semantic meaning beyond what the schema already provides.

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

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

The description clearly states the action: sending up to five selected saved Automation email steps to an explicit test address. It also distinguishes the tool by explicitly saying it does not start the Automation or run other actions, making its purpose unambiguous relative to automation update, preflight, and preview siblings.

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

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

The description gives clear context for when to use the tool: testing saved Automation email steps without starting the Automation. It explicitly states a when-not behavior, but it does not name alternative sibling tools such as sequences_send_test or broadcasts_send_test, so it falls just short of full alternative routing.

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

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

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?

The description adds behavioral context beyond annotations: it mentions 'Effect: external-email,' the limitation that provider-accepted emails cannot be recalled, and retry behavior with idempotency key. Annotations already indicate destructiveHint and idempotentHint, but the description clarifies the idempotency usage for retries without contradicting the hint.

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 (4 sentences) and front-loads the main purpose. It includes relevant details (permissions, effect, retry, API reference) without excessive verbosity. The structure is logical and each sentence earns its place, though the API link could be considered extra.

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

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

The description covers essential aspects for a cancellation tool: purpose, scope (not provider-accepted), retry mechanics, effect, permissions, and references. With an output schema present, it doesn't need to describe return values. It is adequately complete for the complexity, though it could mention error scenarios or prerequisites.

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 parameters are already well-documented. The description reiterates the idempotency key usage for retries but does not add significant new meaning beyond what the schema provides. It meets the baseline for high coverage without adding extra parameter insights.

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

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

The description clearly states the tool's purpose: 'Requests cancellation for delivery work that has not reached the provider.' It uses a specific verb (Requests cancellation) and resource (delivery work), and distinguishes it from other broadcast operations by noting provider-accepted emails cannot be recalled. This differentiates it from similar tools like broadcasts_unschedule.

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 on when to use: cancellation is only possible before provider acceptance. Also gives retry guidance: 'Repeat the same request with the same idempotency key when the response is lost.' However, it does not explicitly name alternatives (e.g., broadcasts_unschedule) or state when not to use it, 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?

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: 'Effect: workspace-change', required permission, and idempotency retry guidance. This goes beyond the annotation hints and offers a clear side-effect profile, though it does not describe return values or validation behavior.

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

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

The description is four short sentences, each with a purpose: defining the action, noting side effects, explaining idempotency, and giving permission/reference. No wasted words or redundant information.

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

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

Given the complex nested body schema, the description adequately covers purpose, side effect, permission, and idempotency, and points to an API reference for deeper detail. However, it does not explain when to use this over similar create tools or clarify that the draft is not sent automatically, though 'draft' implies that. The presence of output schema compensates for not describing 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 description coverage is 100% (both body and idempotency_key have descriptions). The description itself adds minimal parameter-level detail beyond the schema, merely restating that the idempotency key can be retried, which is already in the schema. It correctly does not duplicate schema content.

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 a broadcast draft in the authenticated workspace', using a specific verb and resource, and explicitly notes 'draft' to distinguish from send/schedule tools. This differentiates it from sibling tools like broadcasts_send and broadcasts_schedule.

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 context that this is a create operation and mentions permission and idempotency, but does not explicitly state when to use this vs alternatives (e.g., broadcasts_update, broadcasts_send). It does not reference sibling tools or give exclusion criteria, leaving usage inference to the name.

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 adds significant behavior beyond annotations: it mentions background preparation, subscriber-count calculation, provider readiness checks, durable acceptance semantics, and the need to reuse the idempotency key if the response is lost. The external-email effect and permissions are also explicitly called out, so the agent has a strong model of side effects.

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

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

The description is compact and front-loaded with the core behavior, but it repeats the idempotency instruction twice: 'Reuse the same idempotency key...' and 'Retry with the same idempotency_key.' This slight redundancy prevents a perfect score, but overall it is still tight and information-dense.

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 side-effecting send operation, the description explains durable vs. provider delivery, asynchronous preparation, idempotent retry, external-email effect, required permissions, and API reference. Combined with a fully documented schema and adequate annotations, this is sufficient for an agent to invoke the tool safely.

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 all parameters well. The description adds useful semantic value by explaining why and when to reuse idempotency_key, which complements the schema's length validation and optionality. It also relates preflight behavior to the send flow, though the schema already covers preflight_proof details.

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

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

The description clearly states this tool 'Immediately creates durable preparation for a broadcast draft or scheduled send' and distinguishes it from other broadcast tools by emphasizing the real external-email effect and asynchronous 202 acceptance. This separates it well from broadcasts_send_test, broadcasts_schedule, and broadcasts_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 gives usable context: it is for sending now, it returns 202 on acceptance, and delivery is not yet complete at that point. It does not explicitly name alternatives like broadcasts_send_test or broadcasts_schedule, but the immediate-send framing makes the intended use reasonably clear.

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

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

Annotations already carry the basic safety profile, but the description adds meaningful behavioral disclosures: 'Effect: external-email', guidance to retry with the same idempotency_key, and required permissions. These go beyond the structured annotations and help an agent understand side effects, retry behavior, and authorization needs. No contradiction with annotations is present.

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 well-structured: core action first, then param guidance, then side-effect/permission/reference details. Each sentence contributes either a required precondition, a usage instruction, or retrieval guidance. There is no redundant restatement of the schema or title.

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 three parameters, one nested object, an output schema, and a sibling set, the description covers the essential operational details: target Broadcast requirement, recipient flexibility, subscriber_id sourcing, idempotency retry behavior, external-email side effect, and required permissions. The API reference supplies further depth. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, putting the baseline at 3. The description adds value by explaining the relationship between recipient and subscriber_id ('does not have to match'), how to source subscriber_id via subscribers_list, and the meaning of idempotency_key for safe retries. Only broadcast_id and the body wrapper receive no extra semantic enrichment, so 4 is appropriate.

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

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

The description opens with a specific verb and resource: 'Sends a test message from an existing Broadcast that has an email delivery connection.' This differentiates it from the broader broadcasts_send and from automations_send_test/sequences_send_test by scoping to Broadcasts and test-only delivery. The 'existing Broadcast' and 'email delivery connection' qualifiers make the tool's purpose unmistakable.

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

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

The description gives clear operational context: this is for testing an existing Broadcast with an email delivery connection, and it explains how to find a Subscriber ID (subscribers_list). It also clarifies recipient flexibility. It does not explicitly state when to avoid this tool in favor of broadcasts_send or other send-test siblings, so it falls just short of a 5.

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

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

Annotations already 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 annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds important behavioral context: it declares an 'Effect: workspace-change' and instructs retrying with the same idempotency_key, which is critical for agents. It also mentions the required permission (email_templates:write), adding value 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 one sentence followed by three concise statements (effect, retry, permission, API link). Every sentence provides essential information without redundancy. It is front-loaded with the primary purpose and then critical operational details.

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 a complex input schema with nested objects and an output schema, so the description does not need to explain return values. The description covers the effect, idempotency, and permissions, but it lacks details on error handling or rate limits that could be useful given the complexity. However, the API reference link and rich schema compensate, making it largely complete.

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

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

The schema description coverage is 100% and includes detailed descriptions for body_document (size limit, personalization tokens, anti-handlebars warning) and starting_point_id (exclusive with body_document). The description of the overall tool does not add parameter details, but the schema itself is richly documented, so the baseline is 3; however, the description's mention of idempotency_key usage and the schema's constraints push it to 5.

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

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

The description clearly states the tool creates a reusable email template scoped to the authenticated workspace, which distinguishes it from siblings like email_templates_update and email_templates_preview. The verb 'Creates' and resource 'email template' are specific and unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives, but it mentions the workspace scope and provides an API reference link. There is no guidance on when not to use it (e.g., when to use email_templates_update instead), so it is adequate but lacks exclusions.

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

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

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

The description discloses that the operation changes the workspace, and provides idempotency instructions and permission requirements on top of annotations. No contradiction with annotations; idempotentHint false is not contradicted since the instruction is conditional on using the key.

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 each phrase providing distinct information: purpose, effect, retry guidance, permission, and API reference. No unnecessary words.

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

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

For a complex tool with nested request body and personalization details, the description is minimal but relies heavily on schema and API reference. It does not mention the structure of the body or guidance on constructing sequences, but the schema includes examples and descriptions, so completeness is moderate.

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% and description does not add new parameter semantics beyond what the schema already provides; it only reinforces the idempotency_key usage.

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 a sequence in the authenticated workspace' with a specific verb and resource, distinguishing it from siblings like sequences_get or 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 provides guidance on retrying with the same idempotency_key and mentions required permission, but does not explicitly contrast with alternatives like sequences_preflight or sequences_update, so usage context is clear but not exhaustive.

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

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

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

The description substantially expands on the annotations by stating 'Effect: external-email', listing required permissions, and clarifying that no delivery activity is written. This helps reconcile the destructiveHint: true annotation with the actual external side effect rather than implying destructive internal data changes.

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

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

The description is compact and front-loaded with the core operation, then efficiently lists exclusions, external effect, idempotency guidance, permissions, and API reference. Every sentence adds value and there is 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?

The description covers purpose, what the tool does not do, external side effects, retry behavior, required permissions, and includes an API reference. With an output schema present, no essential information for selecting and invoking this tool is missing.

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

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

Schema description coverage is 100%, so sequence_id, body, idempotency_key, and nested fields like recipient, message_ids, and subscriber_id are already well documented in the schema. The description adds no per-parameter detail, but that is acceptable given the schema already carries the semantic load.

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

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

The description uses a specific verb and resource: 'Sends up to five selected saved Sequence emails to one explicit test address.' It clearly identifies what the tool does and distinguishes it from other send_test siblings by scoping to Sequence emails, while also noting what it does not do ('does not enroll a Subscriber, start the Sequence, or write delivery activity').

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

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

The description gives clear context for when to use this test-only tool, including explicit non-actions and a retry instruction: 'Retry with the same idempotency_key.' It does not directly name sibling alternatives like automations_send_test or broadcasts_send_test, but the Sequence scope and the stated exclusions make the appropriate usage clear enough.

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

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

Annotations 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.

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

While annotations and output schema exist, the description covers permissions, effects, and idempotency. However, the inaccurate claim about tags/sequences creates a completeness gap. It adequately describes behavior but lacks clarity on those unsupported parameters.

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 the description claims the tool updates tags and sequence assignments, which are not present in the input schema. This is misleading. The description does add meaning for custom field behavior, but the inaccuracy reduces usefulness.

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 updates profile fields, status, custom fields, tags, or sequence assignments for a single subscriber. This distinguishes it from sibling tools that focus on one specific action (e.g., subscribers_add_tag, subscribers_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 explains that omitted fields remain unchanged and blank optional custom field values are kept, which guides usage. It also mentions retrying after reading current resource state. However, it does not explicitly contrast with dedicated tag/sequence tools, leaving some ambiguity.

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