Courier

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

Annotations already indicate this is not read-only but not destructive; the description adds nothing beyond the operation itself. It does not disclose whether users are appended or replaced, whether duplicates are allowed, whether the job must be in a draft state, or any effects on an already-running job.

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 with no filler. It is efficient, though the brevity comes at the cost of behavioral and workflow context.

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

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

For a simple two-parameter mutation with no output schema, the description is minimally adequate, especially since the schema covers both parameters. It omits the lifecycle relationship with create_bulk_job/run_bulk_job and any constraints, leaving an agent to guess the intended workflow.

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 coverage is 100%, with descriptions for both job_id and users, so a baseline of 3 applies. The description adds no additional parameter semantics beyond restating that users are added to an existing job.

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

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

The description states a clear action ('Add users') and the target resource ('an existing bulk job'), which distinguishes it from creation and execution tools such as create_bulk_job and run_bulk_job. It does not, however, clarify what a 'bulk job' is or how this differs from list/tenant/user bulk operations, leaving some ambiguity.

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

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

The word 'existing' conveys that this must be used only after a bulk job has been created, which is an implicit usage condition. No alternative tools or when-not-to-use guidance are provided, so an agent must infer placement in the create→add→run workflow from the sibling names.

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

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

Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds one useful behavioral guarantee—existing subscribers are preserved—but does not disclose duplicate handling, failure modes, or response behavior. This is acceptable given the annotations but not rich.

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 with no wasted words. It states the action, the target, and the key non-destructive qualifier in eleven 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 simple two-parameter schema, 100% parameter documentation, and safety-relevant annotations, the description is largely complete for selecting and invoking the tool. It could mention duplicate behavior or the response format, but for a straightforward append operation this is not a critical 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%, so the schema already documents list_id and recipients. The description adds little beyond framing recipients as subscribers. Notably, the schema's 'Recipients to set on the list' wording slightly conflicts with the append semantics, but that is a schema issue, not compensated by the description.

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

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

The description states a specific verb ('Append'), a resource ('subscribers to a list'), and the key behavioral qualifier 'without removing existing subscribers.' This clearly conveys the core operation, though it does not explicitly distinguish itself from sibling tools like bulk_subscribe_to_list or subscribe_user_to_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?

The phrase 'without removing existing subscribers' implies this tool is appropriate when preservation of existing list membership matters, and not for replacement-style updates. However, it provides no explicit when-to-use guidance or mention of alternatives among the many sibling list/subscription tools.

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

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

The description provides no behavioral traits beyond the annotation block: it only restates the action. It does not explain idempotent behavior, whether existing memberships are replaced, or what profile overrides do; the annotations already supply the read-only/destructive hints but the description adds no extra 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 a single sentence with no filler or repetition, and the core action is front-loaded. It is not overly verbose, though its brevity comes at the cost of useful context.

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

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

With no output schema, a nested profile object, and ambiguous sibling operations, the description leaves users without return-value expectations, membership semantics, or profile-override behavior. It is barely adequate for a tool with only two required scalar fields but insufficient given the surrounding toolset.

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 user_id, tenant_id, and profile. The description adds no parameter-specific meaning beyond echoing the roles of user and tenant, which keeps it at 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 is a plain-language restatement of the tool name — 'Add a user to a tenant' adds no information beyond the name/title. It gives no detail about tenant-scoped profiles or how this differs from add_bulk_users and bulk_add_user_tenants, so it does not achieve sibling differentiation.

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

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

No guidance is given about when to call this tool instead of add_bulk_users, bulk_add_user_tenants, or remove_user_from_tenant. The core operation can be inferred from the name, but the description does not state contexts, prerequisites, or 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 only indicate destructive, idempotent, and non-read-only behavior. The description adds the specific impact not present in annotations: archived journeys cannot be invoked and existing runs continue. This is valuable extra context for a destructive operation.

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

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

Two tightly written sentences: the action first, then the key consequence. No filler, no redundant restating of schema or annotations.

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 single-required-parameter archive operation with no output schema, the description covers the essential behavior and outcome: the journey is archived, future invocations stop, and running executions finish. It could add reversibility or permanence details, but the destructiveHint annotation already signals that risk.

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 documents journey_id with 'The journey template ID to archive' and has 100% coverage, so the description need not repeat parameter details. It adds no additional parameter-level nuance beyond what the schema provides, so a 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 and resource ('Archive a journey') and clarifies the consequence of archiving: future invocations are blocked while existing runs continue. It does not explicitly differentiate from the sibling 'archive_journey_template', whose name overlaps, but the resource naming is still clear.

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

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

The phrase 'cannot be invoked but existing runs continue to completion' explains the scenario where this tool applies: you want to stop new invocations without interrupting active runs. It does not explicitly name alternatives like cancel_journey or archive_journey_template, but the behavioral context is enough to guide selection.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description does not need to re-state those traits. It adds genuine behavioral context by warning that archived templates cannot be sent, which is not present in the annotations or schema. No contradiction exists between the description and 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 short sentences with the action and scope front-loaded, followed by the most important behavioral consequence. Every sentence earns its place, with no filler or redundant restatement of the tool name.

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

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

For a two-parameter archive operation with no output schema, the description plus the fully documented input schema provides enough context to call the tool safely and correctly. It could be slightly richer by mentioning whether archiving is reversible or how it relates to siblings, but nothing essential 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%: both journey_id and notification_id already have meaningful descriptions in the input schema. The tool description only reinforces that the notification is journey-scoped and does not add new parameter-level meaning, so the schema-driven baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Archive') and identifies the resource as 'a journey-scoped notification template,' which clearly differentiates it from siblings like archive_journey and archive_notification. It also states the practical consequence ('Archived templates cannot be sent'), making the tool's purpose unambiguous.

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

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

The 'journey-scoped' qualifier implies this tool is for notification templates owned by a journey, but the description does not explicitly name alternatives or state when not to use this tool (e.g., using archive_notification for standalone templates). Usage guidance is therefore more implied than explicitly contrasted with sibling tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description aligns with those. However, the description adds no extra behavioral context beyond the annotations—it does not mention irreversibility, soft-delete semantics, or what happens to the notification template after archiving.

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 tight sentence with no filler. The verb, resource, and selection mechanism are all present and front-loaded, making it efficient and easy to parse.

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

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

The tool is simple and the annotations cover the destructive profile, but the description still leaves gaps: no return/output information, no postcondition details, and no differentiation among the many archive_* siblings. It is minimally adequate but not fully complete.

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

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

Schema description coverage is 100%, and the parameter description already states the notification template ID is to be archived. The tool description adds no new parameter semantics, so the baseline 3 is appropriate.

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

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

The description uses a specific verb, 'Archive', and a clear resource, 'notification template', with the selection method 'by ID'. This distinguishes it from other archive_* siblings such as archive_journey_template or archive_routing_strategy without opening their schemas.

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?

There is no guidance about when to use this tool versus alternatives like archive_journey_template or archive_request. The description states only the action and resource; no when-not conditions, prerequisites, or alternative references are 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable behavioral context beyond those annotations by stating that non-empty sections cause a 409 and that topics must be removed first. This operational constraint is not inferable from the annotations alone.

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 just two sentences with no filler. The core action is stated first, followed immediately by the critical precondition. Every word contributes to effective tool invocation.

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

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

For a single-parameter mutation with no output schema, the description covers the essential operational context: what the tool does, what must be true before calling it, and what happens if that condition is violated. The annotations cover idempotency and destructiveness, so nothing important 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?

The schema already provides full coverage for the single parameter, section_id, with a clear description. The tool description does not add extra parameter-level detail, but the schema handles that sufficiently, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Archive') and a clear resource ('a preference section'), making the tool's function immediately identifiable. It also distinguishes itself from sibling tools like create_preference_section, replace_preference_section, and archive_preference_topic by naming the exact object being acted upon.

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

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

The description gives an explicit precondition: the section must be empty, and topics must be deleted first. It also specifies the failure mode (409) if this precondition is not met. It does not explicitly name an alternative tool such as archive_preference_topic, but the guidance is clear enough for an agent to understand the required workflow.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds only the section-scoping context, not extra behavioral detail such as whether archiving affects subscribers or is reversible.

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

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

A single sentence with no filler; the verb and object are front-loaded and the sentence is easy to parse.

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

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

For a two-parameter mutation with full schema coverage and safety annotations, the description is minimally sufficient. However, there is no explanation of what archiving does semantically or what a successful call returns, and the wording is thin for a destructive 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%, so the schema already documents both topic_id and section_id. The description's 'within a section' conveys a slight relationship hint but does not add meaningful parameter semantics beyond the schema.

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

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

States a specific verb ('Archive') and a specific resource ('topic within a section'), which already separates it from archive_preference_section and archive_journey. It does not explicitly name the sibling for section archiving, so it doesn't fully earn a 5.

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

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

No guidance on when to use this tool versus sibling archive_preference_section, get_preference_topic, or delete_user_preference_topic. No exclusions or prerequisites are mentioned.

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

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

The annotations already carry idempotentHint=true and destructiveHint=true, lowering the description's burden. The description adds useful context by stating that archiving affects 'all associated messages', not just the request. It does not explicitly mention irreversibility or post-archive effects, but the annotation coverage mitigates that gap.

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 12-word sentence with a clear verb-object structure and no filler. It is front-loaded with the action and resource, making it easy for an agent to quickly parse.

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

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

With one well-documented parameter and annotations declaring destructive and idempotent behavior, the description covers the operation's scope adequately. It lacks an explicit note about irreversibility or return value, but this is a simple operation and the schema plus annotations fill most gaps.

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

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

The input schema documents the sole parameter request_id with a clear description ('The request ID (requestId returned from /send)'), so schema coverage is 100%. The description only rephrases 'by request ID' and adds no format, source, or validation detail beyond the schema.

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

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

The description states a specific action ('Archive'), a resource ('a send request'), and the scope ('all its associated messages'), with the lookup method ('by request ID'). It is clear enough to distinguish from sibling archive_* tools that target journeys, templates, notifications, and preferences, though it does not explicitly name an alternative.

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 when-to-use guidance, prerequisites, or exclusions are provided. It does not tell an agent to prefer this tool over related message tools like cancel_message or resend_message, nor when not to use it. The only usage signal is the inherent action of archiving, requiring the agent to infer applicability.

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 destructive and non-read-only behavior. The description adds that archiving is gated on absence of notification templates and tells the caller to unlink first, which is meaningful context beyond annotations. It doesn't discuss reversibility or failure cases, but the annotation coverage lowers the burden.

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, action first, precondition second, and no filler. The clause about unlinking templates is essential and 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 single-parameter archive operation with annotations covering destructiveness and idempotency, the description covers the action and the central precondition. It doesn't identify the tool used to unlink templates or describe the response, but these are minor for this simple 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 covers routing_strategy_id at 100%, so the parameter is fully documented in the schema. The description adds no extra detail about ID format, source, or how to obtain it, so the baseline 3 applies.

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

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

States a precise verb and object: 'Archive a routing strategy.' The resource is specific and uniquely identifies this operation among sibling archive_* tools, distinguishing it from archive_notification, archive_journey, and similar.

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

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

Gives a clear prerequisite: the strategy must not have associated notification templates and instructs to unlink templates before archiving. It doesn't name alternative tools or explicitly say when not to use it, but the precondition provides usable call-condition guidance.

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

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

The annotations already communicate that this is a mutating but idempotent, non-destructive operation. The description adds the useful detail that a custom profile can be applied per tenant, but does not disclose anything about partial failures, existing associations, or what happens after the operation. No contradiction exists between text and annotations.

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

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

Two short sentences with no filler. The first states the core action and scope; the second adds the optional per-tenant profile behavior. Every word contributes useful information.

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

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

For a two-parameter mutation with fully described schema fields and an idempotency annotation, the description covers the essential invocation context. The only nuance not addressed—such as behavior when the user already belongs to a tenant—is not necessary to make a correct first call.

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 user_id and the tenants array, giving 100% coverage. The description's mention of a custom profile per tenant slightly reinforces the schema's 'Tenant-scoped profile overrides', but does not add substantial meaning beyond what the schema already states.

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 action ('Add a user to multiple tenants at once') and clearly distinguishes this tool from the single-tenant sibling add_user_to_tenant by emphasizing the bulk, multi-tenant nature. It also adds the per-tenant custom profile capability, which makes the purpose unmistakable.

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

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

The description implies this is the right choice when multiple tenants need to be handled in one call, but it does not explicitly name add_user_to_tenant as the alternative for single-tenant operations or state any exclusion criteria. An agent must infer the usage boundary from the tool name and wording.

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 operation, so the description adds value by disclosing that matching existing tokens are overwritten rather than appended, preventing duplicate accumulation. It does not cover failure modes or what counts as a 'matching' token, but the overwrite behavior is a meaningful disclosure 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 exactly two sentences: the first delivers the primary action and scope, and the second adds the critical overwrite behavior. There is no filler or redundant restatement of the tool name.

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 bulk mutation with a nested token schema and no output schema, the description covers the core semantics but leaves gaps: it does not explain the key used to match existing tokens, how duplicates inside the same request are handled, or what response/error behavior to expect. It is serviceable for basic invocation but not fully complete.

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

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

The input schema fully documents both parameters and nested fields like token, provider_key, expiry_date, and device metadata, so the description does not need to repeat them. The description adds only the generic framing of 'push/device tokens,' which does not elevate it beyond the schema baseline.

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

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

The description states a specific action—adding multiple push/device tokens for a user in one request—and distinguishes it from singular token tools like create_or_replace_user_push_token by emphasizing batch operation. The overwrite note further clarifies the operation's semantics.

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 the batch use case with 'multiple tokens in one request' and upsert behavior with 'overwrites matching existing tokens,' but it never explicitly names alternatives or states when to prefer this over a singular token tool. No exclusions or conditions are provided.

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

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

The description discloses destructive behavior in detail: omitted overrides are reset to defaults and an empty array clears all overrides, going beyond the annotations' destructiveHint=true. It also adds the validation-atomicity trait, which annotations do not convey, and there is no contradiction with readOnlyHint=false or idempotentHint=true.

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 short sentences plus one atomicity tag; each sentence carries a distinct fact (scope, reset behavior, empty-array behavior, transactional guarantee). The purpose is front-loaded and there is no filler.

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

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

The description is complete enough for a destructive bulk replace: it explains the full replacement contract, the empty-array edge case, and atomicity, while annotations and full schema coverage handle safety and parameter meaning. It does not mention an alternative for partial updates or describe the response/return value, but given no output schema and a clear mutation contract, those are minor 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 already documents all parameters (100% coverage), so the description does not need to repeat definitions. It adds meaningful behavior for `topics`—listed topics are created or updated, omitted ones are reset to defaults—which goes slightly beyond the schema's 'complete set' summary. Other parameters like `user_id` and `tenant_id` are adequately covered by schema descriptions.

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

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

The description opens with a specific verb and object ('Replace a user's complete set of preference overrides'), and the second sentence clarifies the exact scope of replacement ('entire override set', 'every existing override not included is reset'). This clearly distinguishes the full-replace semantics from partial-update siblings even without naming 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 makes the use case explicit: use this tool when the caller wants to set a user's full override set in one atomic request. It implies that partial updates or single-topic changes belong elsewhere, though it does not explicitly name alternatives like bulk_update_user_preferences, so the routing guidance is slightly 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 destructiveHint=true and idempotentHint=true. The description adds useful context by specifying that the destructive effect is replacing all existing subscribers with the supplied recipients, which is consistent 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 a single concise sentence that front-loads the core behavior ('Replace') and the object ('all subscribers on a list'). Every word earns its place, with no redundant 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?

Given the low complexity, complete parameter schema, and annotations covering destructive and idempotent behavior, the description fully enables an agent to call the tool correctly. No critical usage detail, such as the replacement semantics, 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%, with list_id and recipients documented. The tool description reinforces that recipients become the full replacement set, but it adds no parameter-level detail beyond what the schema already provides, such as format, constraints, or edge cases.

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 ('Replace') and clearly identifies the resource ('all subscribers on a list') and the action ('with the given recipients'). This immediately distinguishes it from additive siblings like add_subscribers_to_list or subscribe_user_to_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?

'Replace all subscribers' clearly conveys that this tool is for setting the exact subscriber set rather than incrementally adding subscribers. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select the correct operation.

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 carry the basic safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds genuinely valuable behavior on top: the partial-success contract ('valid topics are written and returned in items, unapplicable ones collected in errors') and the non-destructive scoping to only topics present in the body. It does not contradict annotations; 'create or update' aligns with readOnlyHint=false.

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, roughly 40 words, each earning its place: core purpose, scoping behavior, and partial-success behavior. The most decision-relevant fact (additive, not replace) is front-loaded in the first clause.

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 bulk mutation with partial-success semantics, the description covers the essential facts: additive create-or-update behavior, touched-topic scoping, and the items/errors result split that compensates for the absent output schema. Minor gaps remain — it does not route explicitly to bulk_replace_user_preferences for replacement needs, explain tenant_id's effect, or detail the exact shape of items/errors entries — but none block correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents user_id, topics, and tenant_id with individual descriptions; baseline 3 applies. The description reinforces that topics entries are processed individually via the partial-success split but adds no syntax or format details 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?

Begins with a specific verb+resource ('Additively create or update a user's preferences') and bounds the scope to 'one or more topics in a single request.' The phrase 'Only the topics in the body are touched; existing overrides for other topics are left untouched' clearly differentiates it from the sibling bulk_replace_user_preferences without needing to open either schema.

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

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

The 'Additively' qualifier and 'existing overrides for other topics are left untouched' effectively convey when this tool is appropriate: partial, additive updates rather than wholesale replacement. However, it stops short of explicitly naming bulk_replace_user_preferences as the alternative for full-replacement scenarios or stating a when-not-to-use condition.

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 valuable behavioral details beyond annotations: it reveals that cancellation works by invoking a second ad-hoc automation with a single cancel step, which is non-obvious and useful. The spelling note also helps avoid invocation errors. Annotations already cover idempotence and non-destructive nature, so the bar is partially lowered.

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 core purpose. Four sentences are used, but each earns its place: the cancellation mechanism, the token matching prerequisite, and the spelling note are all relevant. Minor redundancy exists between 'cancelation_token' appearing in the first and third 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?

For a simple one-parameter tool, the description is largely complete: it explains the action, the mechanism, and the token requirement. The lack of an output schema is acceptable since return values are not critical for invocation. It could briefly mention when not to use it, but this is not a significant gap.

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

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

The input schema already documents the single parameter with 100% coverage. The description reinforces the matching requirement and adds a spelling clarification, but does not substantially expand parameter semantics beyond what the schema provides.

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

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

The description states an unambiguous action ('Cancel a running automation') and specifies the exact resource and identifier mechanism ('cancelation_token'). It clearly differentiates from sibling tools like cancel_journey and cancel_message by targeting automations specifically.

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: use this tool to cancel a running automation, and the token must match the original cancelation_token. It does not explicitly exclude other scenarios or name alternatives, but the context is clear enough for correct selection.

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

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

Annotations already provide destructiveHint and idempotentHint, but the description goes further by spelling out what idempotency means in practice: already-finished or already-canceled runs are left unchanged. It also discloses that cancelation_token affects every run associated with the token, which is key behavioral context beyond the annotation flags.

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

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

Two short sentences deliver the essential information in order: what the tool does, the parameter selection rule, and idempotency behavior. There is no filler, repetition, or unnecessary elaboration.

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

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

For a two-parameter cancellation tool with strong annotations and full schema coverage, the description is sufficient. It covers the action, the parameter constraint, and the idempotency behavior. No output schema exists, but none is needed for an agent to invoke this tool correctly.

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

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

The input schema already documents both parameters and their mutual exclusivity with 100% coverage. The description adds value by emphasizing 'EXACTLY ONE' as a hard invocation rule and summarizing the semantic difference between canceling a single run and canceling every run tied to a token, which helps an agent select the right parameter without opening the schema definitions.

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

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

The description names a specific verb and resource: 'Cancel journey runs,' which distinguishes this tool from siblings like cancel_automation, cancel_message, and cancel_notification_submission. It also clarifies the two scopes of cancellation (token-wide vs single run), making the tool's purpose unambiguous.

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

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

The description gives explicit invocation guidance: supply EXACTLY ONE of cancelation_token or run_id. It also explains the consequence of each choice. It does not explicitly state when to prefer this tool over sibling cancel tools, but the resource-focused name and 'journey runs' phrasing make the intended context clear.

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

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

Annotations already signal destructive and idempotent behavior. The description adds meaningful context by specifying the in-delivery precondition and stating that the return value contains the message details with updated status. This goes beyond what annotations and schema provide, with no contradiction.

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

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

Two short sentences with no filler. The core action and precondition are front-loaded, and the return behavior is stated efficiently in the second sentence.

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 single-parameter destructive action, the description covers the action, the valid precondition, and the return value. Annotations cover idempotency and destructiveness, so nothing essential 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?

The schema describes message_id as 'The message ID to cancel' with 100% parameter coverage, so the schema already carries the meaning. The description adds no additional syntax, format, or source guidance for the parameter, which lands at the expected 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?

States an explicit action ('Cancel'), a specific resource ('a message'), and a precondition ('currently being delivered'). This clearly differentiates it from sibling tools like cancel_automation, cancel_journey, and cancel_notification_submission without needing to inspect their schemas.

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 'currently being delivered' gives a clear condition for when this tool applies, which helps an agent decide whether cancellation is appropriate. It does not explicitly name alternatives or exclusions, but the precondition is contextually strong enough for basic routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered by structured data. The description adds no additional behavioral context, such as whether cancellation is reversible or what happens to the submission, but it does not contradict 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?

One short sentence with no filler, redundant modifiers, or irrelevant context. The action and resource are front-loaded, and every word contributes.

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

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

For a simple two-parameter destructive operation with annotations and full schema coverage, the definition is minimally sufficient. However, it is cryptic about what a 'notification template submission' is and what cancellation means in the overall workflow, with no output schema or additional context to clarify.

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 notification_id and submission_id documented in the input schema. The description adds no parameter-level detail, but the schema already carries the burden of explaining each parameter.

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

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

States a specific verb, 'Cancel', and a distinct resource, 'notification template submission,' which clearly differentiates it from sibling tools like cancel_automation, cancel_journey, and cancel_message. There is no ambiguity about which object is acted upon.

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

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

The description provides no guidance on when to use this tool vs. alternatives, no prerequisites, and no workflow context. It does not mention under what conditions a notification template submission should be cancelled or how it differs from similar cancellation operations.

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

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

Annotations already set readOnlyHint=true, so the description only needs to add extra context. It discloses that client-side SDKs generate a sample JWT, which is a behavioral trait beyond a simple read operation and helps the agent understand side outputs.

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 with no filler. The main purpose is front-loaded, and the JWT detail is a useful supplement rather than repetition.

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

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

For a simple read-oriented tool, the description covers the essential behavior: what it returns (installation guide) and the extra output for client-side platforms (sample JWT). No output schema exists, but the description provides enough for an agent to infer the basic return value.

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

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

Schema description coverage is 100%, so the schema already documents both platform and user_id clearly. The description reiterates the client-side/JWT behavior, which is helpful context but doesn't add meaning beyond what the schema already states.

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

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

The description states a specific verb ('Get') and resource ('Courier SDK installation guide') scoped by platform. It also names the client-side platforms that trigger JWT generation, which clearly distinguishes this from other get_* tools in the sibling 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?

The description implies use when an installation guide is needed, and it notes that client-side SDKs also produce a sample JWT. However, it does not explicitly address alternatives such as generate_jwt_for_user, which could create ambiguity for agents trying to decide between standalone JWT generation and this tool.

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

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

The description discloses a 400-on-omitted-settings behavior and a safe default, but the two statements contradict each other: it first says omitting settings returns 400, then says omitting settings uses a safe default. The schema already documents the default, and the annotations carry little behavioral content, so the contradictory claims reduce transparency rather than add it.

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

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

The description is appropriately short at three sentences with an example, and it front-loads the core purpose. However, the self-contradictory middle sentence harms clarity, keeping this from a higher score.

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

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

With nested settings/colors objects and no output schema, the description needed to clearly explain when settings are required and what happens if omitted. Instead it gives conflicting answers, so an agent cannot reliably decide whether to send settings. The schema fills some gaps, but the tool-level description is not complete enough on its own.

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

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

Schema description coverage is 100%, so the baseline is 3. The example adds a concrete structure for settings.colors, and the second sentence offers a heuristic for omitting settings, but the contradictory 'requires settings' statement undercuts that guidance and prevents a higher score.

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

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

The opening phrase 'Create a new brand' clearly states the verb and resource, and 'new' distinguishes this from update_brand, delete_brand, get_brand, and list_brands. Even without naming siblings, the purpose is unambiguous.

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

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

The description implies when to use the tool—creating a new brand—and offers guidance about when to omit settings (when no specific brand colors are available). However, it never explicitly states the alternative for updating an existing brand or gives a clear when-not-to-use condition.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false, but carry limited detail. The description adds the multi-step workflow context, implying the created job is not yet ready to send until users are added and run. However, it doesn't disclose behaviors like persistence, auth requirements, or side effects beyond creating a job. Without additional context, this is adequate but not rich.

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 fluff. It front-loads the primary purpose and immediately follows with the workflow, which is essential context. Every sentence earns its place, making it highly concise and well-structured.

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

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

For a creation tool with one parameter and no output schema, the description is fairly complete. It explains the tool's role in the overall process via the workflow, which is crucial for an agent. However, it doesn't mention what the response looks like (e.g., job ID), which agents might need for subsequent steps. The open-ended message structure is also not detailed, but this is partially a schema issue. Overall, it's sufficient for basic usage.

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

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

The single parameter 'message' has a schema description: 'Bulk message definition with event/template and content.' Schema description coverage is 100%, so the schema already documents the parameter. The tool description adds little beyond this—only the workflow context. The description of 'message' is vague (additionalProperties open), so no extra clarity is provided. Baseline 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the tool's purpose: 'Create a new bulk job for sending messages to multiple recipients.' It uses a specific verb (create) and resource (bulk job), and the mention of sending messages distinguishes it from sibling tools that add users or run the job. The purpose is unambiguous and distinct from other bulk-related tools like add_bulk_users and run_bulk_job.

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 an explicit workflow: 'create_bulk_job → add_bulk_users → run_bulk_job.' This tells an agent exactly when to call this tool (as the first step in a multi-step bulk-sending process) and gives context for how it fits with siblings. It doesn't explicitly state alternatives to avoid, but the workflow sequence is clear and actionable.

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

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

The description says "Re-sending an identical call changes nothing," implying idempotent behavior, but the annotations set idempotentHint to false. This is a direct contradiction on a critical behavioral property, so the description cannot be trusted as transparent.

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

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

The description is long but information-dense; nearly every sentence adds operational detail or error-handling context. It is well front-loaded with the core draft-only and node-order rules, though the verification paragraph is verbose enough that it could be tightened.

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

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

With no output schema, the description does a strong job explaining the verification object, mismatch categories, unauthorized errorKind handling, and the relationship to replace_journey. However, the conflict between the stated idempotence and idempotentHint:false leaves an unresolved, operationally important inconsistency.

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 still adds meaning beyond the schema: nodes must be trigger then exit, exit is required even though only name and nodes are in the schema's required list, node ids are server-generated and must be omitted, and verification failure modes map to specific node/template parameters.

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

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

The description opens with "Create a new journey," naming a clear verb and resource, then sharpens scope with "Always created as a draft; making it live is a separate step this tool cannot perform." It distinguishes itself from replace_journey by noting send/delay nodes are added there, so an agent can separate create from modify.

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

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

The description explicitly states when to use this tool versus replace_journey: send and delay nodes are added later by replace_journey once journey-scoped templates exist, and publishing is a separate step. It also gives corrective guidance for failed verification: fix only the named mismatch and resend.

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 only provide basic flags, all false. The description goes well beyond them: it discloses draft-only creation, the separate publication step, verification semantics for the returned id, and the meaning of errorKind 'unauthorized' including the partial-failure case where the template was actually created. This is unusually transparent.

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

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

The description is front-loaded with the core action and draft limitation, then adds only high-value context: usage in send nodes, a concrete example, and essential verification/error behavior. Every sentence earns its place despite the length.

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

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

There is no output schema, so the description compensates by explaining the verification object, verified true/false meanings, and unauthorized errorKind. It does not document the full response shape, but it gives an agent enough information to invoke the tool correctly and interpret the critical post-call result.

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 all parameters and nested fields. The description's example illustrates the expected shape but does not add meaningfully new semantics for parameters beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Create a notification template scoped to a journey.' This distinguishes it from standalone notification tools like create_notification. It also clarifies a key distinguishing constraint, that the template is always created as a draft and cannot be made live by this 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 gives clear context: use this for journey-scoped notification templates, and it explicitly warns that making the template live is a separate step this tool cannot perform. It does not name an alternative sibling directly, but the context is strong enough to route an agent to publish_journey_template for publication.

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 convey that the tool mutates (readOnlyHint=false), is idempotent, and is not destructive. The description adds the upsert behavior ('create or update'), but it does not disclose what happens to unspecified fields or whether update is a full replacement. This is modest additional context beyond the annotations, with no contradiction.

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

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

A single sentence that front-loads the action and resource while identifying the key parameter. There is no redundant or filler text; every word contributes to the tool's 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?

For a simple two-parameter tool with full schema coverage and annotations, the description plus schema are enough to invoke it correctly. It could be more complete by stating the update semantics explicitly (e.g., 'This is an upsert'), but the current wording already conveys that reasonably well.

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

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

Schema description coverage is 100%, and both list_id and name already have clear descriptions. The description only restates the role of list_id ('by list ID') and does not add format, constraints, or relationship details beyond the schema, so it earns the baseline score.

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

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

The description states a specific action (create or update), the resource (a list), and the key identifier (list ID), which clearly separates it from CRUD siblings like get_list, delete_list, and restore_list. The action is unambiguous and not a tautology of the tool name.

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

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

The description implies an upsert usage—use it to create a list or update an existing one by providing its list_id—but it does not explicitly state when to prefer this over sibling tools or what conditions trigger update vs. create. No alternatives or exclusions are mentioned, so guidance is only implied.

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

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

Annotations only indicate non-readonly, non-idempotent, non-destructive behavior, so the description carries the behavioral burden. It discloses that templates start as drafts, cannot be sent until published, and that content can be provided inline or later. This is meaningful behavioral context beyond the schema.

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

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

The description is information-dense with no filler. It front-loads the core purpose, then covers key constraints, workflow, and a realistic example. Every sentence adds necessary guidance, and the structure flows logically from purpose to parameters to example.

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 nested objects and no output schema, the description covers the critical decision points: required name, draft vs published state, inline vs later content, and routing strategy linkage. It does not detail every nested subfield, but the schema already documents those. The description is sufficient for an agent to construct a valid initial request.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by noting that name is required, content may be set later, and routing.strategy_id controls channel selection. The included example concretely illustrates how state, branding, routing, and content map into the request body.

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: 'Create a V2 notification template.' It clearly distinguishes this tool from siblings like create_journey_template and send_message by scoping to notification templates. The V2 qualifier and draft/publish details further pin down exactly what is created.

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 the draft-to-publish workflow, stating that a newly created template cannot be sent until published and that publishing is a separate operation or can be done via state: 'PUBLISHED'. It gives context for when to use this tool versus later publishing. It does not explicitly name the alternative sibling 'publish_notification', but the workflow 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?

Annotations already indicate this is a mutating, idempotent, non-destructive operation. The description adds valuable behavioral detail beyond those flags by explaining that omitted fields are preserved, which clarifies the upsert semantics. It does not disclose response behavior or error conditions, but the annotations cover the core safety profile.

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

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

A single sentence conveys the core action, the update behavior, and the crucial preservation guarantee. Every clause earns its place, with no filler or repetition of schema 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 only two parameters and a clear behavior, and the description plus schema cover what an agent needs to invoke it correctly. There is no output schema, so return-value details are absent, but that gap is not critical for an upsert operation whose inputs and semantics are well specified.

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 user_id and profile with an example. The description's phrase 'supplied values' loosely maps to the profile parameter but adds little new semantic detail beyond what the schema provides. Baseline 3 is appropriate given full 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 identifies the action (create or merge), the resource (user profile), and the critical merge behavior ('Existing fields not included are preserved'). This also distinguishes it from sibling tools like replace_profile and patch_profile without naming them, because preservation semantics are explicit.

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

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

The description provides clear context for when the tool is appropriate: when creating a new profile or updating an existing one with a partial set of values. However, it does not explicitly state when to use an alternative (e.g., patch_profile or replace_profile) or list exclusions, so it stops short of full guidance.

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

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

The description discloses the 'replace' behavior, which is not explicitly stated in the annotations (they only mark idempotentHint true). However, it does not add context about auth requirements, side effects beyond replacement, or rate limits, so it adds only marginal 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?

A single, compact sentence with no filler. The core action and target resource are front-loaded, making it easy for an agent to quickly scan and understand the tool's 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?

The tool is relatively simple and the schema covers all parameters, while annotations cover safety and idempotency. However, the description omits any mention of when to use this instead of the closely related 'patch_user_token' or bulk token operations, and it does not clarify expected outcome or error scenarios, leaving room for ambiguity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning about parameters, such as how 'provider_key' or 'device' interact with the replace behavior. This 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 'Create or replace a push/device token for a user' states a specific action and resource, clearly identifying what the tool does. It avoids tautology and is distinct from siblings like 'delete_user_token' or 'patch_user_token', though it does not explicitly name any alternative.

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 provided on when to use this tool versus alternatives such as 'patch_user_token' or 'bulk_add_user_tokens'. The description only restates the core functionality, leaving the agent to infer selection criteria from the tool name alone.

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

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

Annotations already establish that this is a mutating, idempotent, non-destructive operation. The description adds the 'create or replace' framing but does not explain what replacement does to existing tenant data, child objects, users, or preferences. It is consistent with annotations and provides some context, but the burden of detail is left to the schema.

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

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

The description is two short sentences with no wasted words and the action is front-loaded. It is concise but thin, lacking operational detail that would make it truly excellent.

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 7 parameters, nested objects like default_preferences and user_profile, and no output schema, the description is incomplete. It does not clarify what 'replace' means in practice, whether updated fields are merged or reset, what the tool returns, or how existing tenant state is affected.

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

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

Schema description coverage is 100%, so the schema fully documents the parameters. The description adds no parameter-level guidance and merely provides background context about tenants, placing it at 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 names a specific action ('Create or replace') and resource ('a tenant'), then defines what a tenant is. It clearly identifies the tool among siblings like get_tenant and delete_tenant, though it does not 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?

No usage guidance is provided. The description does not say when to use this tool versus alternatives such as add_user_to_tenant, update_tenant_preference, or delete_tenant, leaving the appropriate context entirely to inference.

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

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

The description discloses a concrete behavioral detail beyond the annotations: the section id is generated and returned. It also scopes the operation to 'your workspace.' The annotations already signal the mutation profile, so the description adds useful output-behavior context without needing to repeat safety 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?

Two short sentences with no filler. The action and resource come first, followed by the key output behavior and a pointer to the relevant sibling tool. 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 straightforward create tool with three well-documented parameters, the description covers the essential action, the returned id, and the next step in the workflow. It does not describe the full response shape or compare against replace_preference_section, but the id mention partially compensates for the missing output schema.

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

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

Schema description coverage is 100%, so the parameters name, routing_options, and has_custom_routing are already fully documented in the schema. The description adds no parameter-level meaning of its own, which lands it at the baseline 3.

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

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

The description names a specific action and resource: creating a preference section. It also differentiates itself from the sibling create_preference_topic by explicitly pointing topic creation to that tool, and the note that the section id is generated and returned further clarifies the tool's purpose.

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 workflow context by instructing the agent to add topics afterwards with create_preference_topic, which implies this tool is only for creating the section itself. It does not enumerate alternatives like replace_preference_section, but the creation-focused verb and the follow-up pointer provide sufficient orientation.

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

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

Annotations only set readOnlyHint, idempotentHint, and destructiveHint to false, leaving the description to carry behavioral detail. The description adds that the topic id is generated and returned and that a missing section causes a 404. This is useful, though it does not cover duplicate-name behavior or the full response shape.

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

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

Two sentences with no filler: the first states the action and scope, the second reports the generated id and the key failure mode. All information earns its place and the purpose is front-loaded.

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

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

For a creation tool with seven parameters and no output schema, the description covers the essential context: creation inside a section, the generated id being returned, and the 404 error case. The remaining details are handled by the fully documented schema, so nothing critical is missing, though duplicate handling is not addressed.

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 explains every parameter including required fields, enums, and defaults such as routing_options defaulting to empty. The description adds no parameter-specific meaning beyond the schema, matching the baseline for full coverage.

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

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

The description opens with a specific verb-and-resource statement — 'Create a subscription preference topic inside a section' — which clearly distinguishes this from section-level operations like create_preference_section. It also adds the unique outcome of a generated, returned topic id.

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

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

The description establishes the parent context by requiring an existing section and explicitly calling out the 404 failure when the section is missing, which signals a prerequisite. It does not explicitly name alternatives such as create_preference_section, but the context makes the routing decision 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 only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds meaningful behavioral context: the created config can affect live sends once referenced, so credential/settings mistakes have real consequences. It also stresses pre-save validation, which is useful risk disclosure.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence carries information: what it does, why caution is needed, and a hard validation requirement. No filler or repetition of annotation fields.

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

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

For a mutating tool with no output schema, the description covers the essential prerequisites: valid provider key, catalog validation, settings correctness, and downstream consequences. It does not describe the response shape, but the risk warning and validation guidance are the key missing context that an agent needs before invoking.

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 four parameters. The description reinforces that provider must be a known Courier catalog key and that settings contain credentials, but it does not add material meaning beyond the schema's own descriptions.

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

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

Description opens with a specific verb and resource: 'Create a new provider (integration) configuration.' This clearly distinguishes from siblings like update_provider, get_provider, and list_provider_catalog, and the word 'new' signals creation semantics.

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 the tool is appropriate—creating a fresh provider config—and advises validating against list_provider_catalog before saving. It does not explicitly name exclusions or alternatives such as update_provider for existing configs, so it stops short of a full routing guide.

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 only negative hints (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the behavioral burden. It adds no context about duplicate-name handling, validation failures, default routing behavior, or what the created strategy implies operationally. No contradiction with annotations, but also no added disclosure.

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

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

A single, front-loaded sentence with zero filler: the action verb comes first, followed by the purpose clause. It is appropriately sized, though the available space could have been used to add usage or behavioral 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?

For a tool with 6 parameters, a nested routing object, free-form channels/providers configuration objects, and no output schema, the description is thin. It does not say what the call returns, whether the name must be unique, or how channel/provider references relate to existing resources, leaving an agent uncertain about post-creation outcomes.

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 each parameter is already documented inline. The tool description's phrase 'across channels and providers' adds slight reinforcement to the channels and providers objects, but it does not clarify their free-form structure. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description states a specific verb ('Create'), a specific resource ('routing strategy'), and the scope ('how notifications are delivered across channels and providers'). This is clearly distinct from get/list/archive_routing_strategy siblings and from other create_* tools (create_provider, create_notification). However, it does not explicitly differentiate from replace_routing_strategy, leaving the create-versus-replace boundary to inference.

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

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

There is no guidance on when to use this tool versus its alternatives, particularly replace_routing_strategy. It also omits practical context such as prerequisites (e.g., whether referenced channels or providers must already exist) or when a routing strategy is needed versus sending a notification directly.

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 merely restates the action and gives no additional behavioral context such as irreversibility, side effects on related entities, or permission requirements. The annotations already declare destructiveHint=true and idempotentHint=true, so the description adds nothing beyond 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 a single, focused sentence that is concise and front-loaded with the action and resource. No unnecessary words 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 delete operation with one parameter and no output schema, the description is complete. The annotations cover safety and idempotency, and the schema handles parameter details. An agent can safely invoke this tool based on the provided information.

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 provides full coverage (100%) for the single required parameter, including its description 'The audience ID to delete'. The tool description does not add extra meaning, so a baseline score of 3 is appropriate since the schema already documents the parameter adequately.

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 (delete) and the target resource (audience), and specifies the identifier (ID). It is unambiguous and distinguishes from sibling tools like delete_list or delete_brand because it names 'audience' explicitly.

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

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

There is no explicit mention of when to use this tool versus alternatives, but the intent is obvious from the name and description. The lack of any exclusion or alternative hint is acceptable for a straightforward delete operation, though a sentence about not using it for soft-deletion or restoring would be better.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description only restates the action without adding context such as irreversibility, cascading effects, or permission requirements. It does not contradict the annotations, but it adds no behavioral depth beyond 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 a single, front-loaded sentence with no filler. It conveys the action, target, and required input in the fewest possible words, and every word 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 one-parameter delete operation, the description plus schema and annotations are largely complete. The destructive and idempotent hints cover the main operational expectations, and no output schema is specified. It could mention irreversibility or side effects, but the existing information is sufficient for correct invocation.

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

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

Schema description coverage is 100% and the single parameter brand_id is already documented in the schema as 'The brand ID to delete.' The description's 'by its ID' adds no meaningful semantic value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states an unambiguous action ('Delete') on a specific resource ('a brand'), with the identifier mechanism ('by its ID'). It clearly distinguishes this from sibling tools like update_brand, get_brand, and create_brand without needing to open the schema.

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

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

The description gives no guidance on when to choose this tool over alternatives such as update_brand or the other delete_* siblings. There are no conditions, exclusions, or explicit statements about when this operation is appropriate.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds no behavioral context beyond the word 'Delete'. It does not disclose whether deletion is permanent or soft-deletable, whether restore_list can undo it, or what happens to list subscriptions. No contradiction with annotations exists.

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

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

The description is a single, well-structured sentence with the action and object front-loaded. Every word earns its place, and there is no unnecessary elaboration.

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 one-parameter tool with annotations covering destructiveness, the description is adequate for basic selection and invocation. However, it omits potentially useful details about reversibility (especially given the restore_list sibling) and downstream effects such as subscriber associations, so it is not fully complete.

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

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

The schema already provides 100% coverage for the single list_id parameter. The phrase 'by its ID' simply reinforces the schema and adds no new semantic, format, or constraint information.

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

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

The description states a specific action ('Delete'), a precise resource ('a list'), and the identifying method ('by its ID'). It is unambiguous and clearly distinguishes this tool from siblings like get_list, create_list, and delete_user_list_subscriptions.

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?

There is no guidance on when to prefer this tool over related operations such as delete_user_list_subscriptions, unsubscribe_user_from_list, or delete_audience. It also does not mention prerequisites or caveats, leaving the selection logic entirely to the agent.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to restate the destructive nature. It does add the qualifier 'permanently,' which communicates irreversibility beyond the boolean annotation. However, it does not disclose what associated data is removed or whether special permissions are required.

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 with no filler. Every word contributes meaning, and the most important qualifier, 'permanently,' appears immediately after the verb.

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 one-parameter destructive tool, the description covers the action, target, and irreversibility. The absence of an output schema is acceptable given the simplicity of the operation. It could additionally note cascading effects or permission requirements, but this is not a significant 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%, and the user_id parameter is already described in the schema as 'The user ID to delete.' The tool description adds no further semantic detail about the parameter. This matches the baseline for a fully documented schema.

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

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

The description states a specific verb and resource: 'Delete a user profile permanently.' It clearly identifies the action and target. The qualifier 'permanently' also distinguishes this from sibling non-destructive profile operations like patch_profile and replace_profile.

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

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

The description provides no guidance on when to use this tool versus alternatives such as patch_profile, replace_profile, or delete_user_list_subscriptions. There are no exclusions, prerequisites, or alternative routing suggested, so an agent must infer usage solely from the tool 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 indicate destructiveness, non-read-only, and idempotency. The description adds a valuable behavior beyond annotations: the 409 conflict when the provider is still referenced by routing or notifications. This is meaningful operational context for an agent.

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

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

A single, front-loaded sentence states the core action and the key failure condition with zero waste. Every clause earns its place.

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

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

For a simple one-parameter delete operation with rich annotations, the description covers the main invocation need and the critical conflict case. It does not describe the success response, but the absence of an output schema makes that less critical.

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 the single parameter provider_id is fully described in the schema. The tool description does not add additional meaning beyond what the schema already provides, 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 names the exact action ('Delete') and resource ('provider configuration') with a specific verb. It is clearly distinguishable from sibling tools like update_provider, create_provider, and other delete_* 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 as the destructive counterpart to create/update provider, but it does not explicitly state when to choose this over alternatives, nor does it mention any conditions for when deletion makes sense. The 409 note is behavioral context, not usage guidance.

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

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

The description is consistent with the annotations (destructiveHint=true, readOnlyHint=false) but adds no behavioral context beyond what the annotations already convey. It does not disclose whether deletion is permanent, whether it cascades to related records (users, preferences, templates), or whether special authorization is required, and the idempotentHint=true is neither confirmed nor explained. No contradiction with annotations exists.

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

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

A single six-word sentence, 'Delete a tenant by its ID,' with zero filler and the action front-loaded. It is appropriately sized for a one-parameter tool where every word 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 one-parameter, no-output-schema tool whose annotations already carry the safety profile, the description is nearly sufficient. However, a destructive tenant operation would benefit from at least a note on permanence or cascade effects — for example, whether deleting a tenant also removes its users, preferences, and templates — to fully inform an agent's decision.

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%: tenant_id is already documented as 'The tenant ID to delete' and marked required. The description's phrase 'by its ID' reinforces the parameter but adds no format, source, or validation detail beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Delete') and a specific resource ('tenant') and identifies the targeting mechanism ('by its ID'). It distinguishes cleanly among the many sibling delete_* tools, since 'tenant' unambiguously names the entity itself rather than tenant preferences, templates, audiences, brands, or providers.

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 provided on when this tool should be used, what preconditions exist (e.g., removing tenant users or associated data first), or how it relates to alternatives in the sibling set. An agent receives no context to decide between delete_tenant and related operations like remove_user_from_tenant or archiving tools, nor any warning about the consequences of calling 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description aligns with these and adds specificity about what is removed, but it does not disclose additional behavioral traits such as whether deletion cascades, whether it is reversible, or what happens when the preference does not exist.

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 with no filler. Every word earns its place, and the verb 'Remove' immediately conveys the action.

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

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

For a simple two-parameter deletion operation with strong annotations (destructive and idempotent hints), the description is sufficient. The schema fully covers parameters, and the description clearly states what is being deleted.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description maps 'topic' to topic_id and 'tenant' to tenant_id but adds no extra format, constraints, or relationships 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 uses a specific verb ('Remove') and names the exact resource ('default notification preference for a topic') and scope ('from a tenant'). It clearly differentiates from related siblings like update_tenant_preference and delete_tenant.

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 no guidance on when to use this tool versus alternatives such as update_tenant_preference or delete_tenant. It does not state exclusions, such as when a preference should be updated instead of removed.

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 convey destructive and non-idempotent behavior, so the description needs to add context beyond that. It does add the HTTP response semantics (204 on success, 404 if the template does not exist for this tenant), which is useful but does not discuss irreversibility or permission requirements.

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

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

The description is a single sentence that front-loads the core action and then provides the most relevant response outcomes. Every clause earns its place with zero 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 two-parameter delete operation, the description covers the essential call semantics and expected success/failure statuses. The absent details, such as authentication requirements or broader error codes, are not critical given the low complexity and strong schema coverage.

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

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

Schema description coverage is 100%, so the parameter descriptions already fully explain tenant_id and template_id. The tool description adds no additional parameter detail beyond what the schema provides, leaving the baseline of 3 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 ('Delete') and resource ('tenant notification template'), making the tool's function immediately clear. It also distinguishes this from sibling deletes like delete_tenant and delete_tenant_preference by naming the exact entity type.

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 provided about when to use this tool versus alternatives such as archive_notification or replace_tenant_template. The description states only what the tool does, not under what conditions an agent should choose it or avoid 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 declare destructiveHint=true and idempotentHint=true, so the description need not repeat that. It does not add extra behavioral context such as side effects, permission requirements, or return conventions. It is consistent with annotations and minimally sufficient, but adds no new information beyond the scope ('all') that the name already suggests.

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

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

A single, direct sentence that gets straight to the action and scope. No wasted words, and the key constraint ('all') is front-loaded.

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

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

For a one-parameter destructive tool with annotations covering safety and idempotency, the description is nearly complete. It clarifies the full scope ('all' subscriptions) which is essential. However, it does not mention what happens to responses or whether it should be used cautiously, but that's beyond what's needed given the simplicity.

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

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

Schema coverage is 100% and the only parameter, user_id, is already described as 'The user ID'. The description does not add any additional meaning about how the user_id is used or any format expectations, so it provides no value beyond the schema.

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

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

The description uses a specific verb ('Delete'), a clear resource ('list subscriptions'), and scope ('all' and 'for a user'). It clearly distinguishes from sibling tools like unsubscribe_user_from_list (which implies a single list) and get_user_list_subscriptions (a read 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention when to choose this over unsubscribe_user_from_list or bulk_subscribe_to_list, nor does it state any prerequisites or context. The name implies bulk removal, but the description alone does not explicitly instruct the agent.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description adds value by clarifying the exact behavioral effect: the preference is not merely removed but 'reverted to the topic's default status.' This complements the annotations without repeating 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?

A single sentence that is front-loaded with the action and includes the key behavioral consequence. Every word earns its place; there is 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?

For a two-parameter, no-output-schema tool with annotations covering destructive and idempotent behavior, the description is largely complete. It could explicitly state what happens when no preference exists, but the idempotentHint annotation covers that implication.

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 straightforward descriptions for user_id and topic_id. The tool description does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('delete'), the resource ('a user's preference for a specific subscription topic'), and the resulting behavior ('reverting it to the topic's default status'). This distinguishes it from siblings like update_user_preference_topic, archive_preference_topic, and delete_tenant_preference.

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 a clear context: use this when you want to remove a user's custom preference and restore the topic default. It does not explicitly name alternatives or exclusions, but the effect is stated plainly enough for an agent to infer when it applies.

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 provide destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the specific object of destruction ('a specific push token'), but does not disclose extra behavioral details like irreversibility, auth requirements, or cascading effects. It does not contradict 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 a single, front-loaded sentence with no filler or redundancy. Every word contributes meaning: 'Delete', 'specific', 'push token', and 'for a user' together define the tool's purpose clearly.

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

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

For a simple two-parameter destructive operation, the description, combined with full schema documentation and the annotations coverage, gives the agent enough to invoke the tool correctly. A brief note about absence behavior when the token does not exist would improve completeness, but it is not essential for correct invocation.

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

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

Schema coverage is 100% and both parameters have clear descriptions ('The token identifier to delete' and 'The user ID'). The description adds no additional semantic nuance beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Delete') and a specific resource ('a specific push token for a user'), which clearly distinguishes it from sibling tools like list_user_push_tokens or create_or_replace_user_push_token. It is not a tautology and immediately conveys the tool's exact 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?

There is no guidance about when to use this tool versus alternatives such as patch_user_token, create_or_replace_user_push_token, or bulk_add_user_tokens. The description only states what the tool does, leaving the agent to infer the appropriate context without explicit routing or 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 are all false/neutral, so the description carries the behavioral burden. It clarifies the intended use but does not disclose details like whether the token is returned directly, how it is signed, or if generation has side effects. Still, the core behavior is clear.

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

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

Two short sentences with no filler. The action is front-loaded and the use case adds practical context 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 low parameter count, full schema coverage, and annotations, the description is mostly complete for selection and invocation. The main gap is the absence of an output schema and no description of what the tool returns, but the name and action make the result reasonably inferable.

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?

All three parameters have schema descriptions, so schema coverage is 100%. The description adds no extra parameter-level meaning beyond naming the user and the client-side SDK 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?

States a specific verb and resource: 'Generate a JWT authentication token for a user.' The use case ('client-side SDK auth') further disambiguates it from the many user/token-related sibling tools.

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

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

Provides a clear context for when to use this tool: client-side SDK auth for Inbox, Preferences, etc. It does not explicitly mention alternatives or exclusions, but no sibling tool performs JWT generation.

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

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

Annotations declare readOnlyHint=true, so no side effects need restating. The description adds one behavioral detail: the response includes the filter definition. That is useful because no output schema exists, but the description does not go further into error cases or data shape.

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

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

A single sentence with no filler. The verb, resource, and distinguishing return detail are all front-loaded and every word 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 single-parameter read operation, this is complete. The readOnlyHint covers safety, the ID parameter is fully documented, and the description tells the agent what the response will include. No output schema exists, but the low complexity does not demand more.

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 the schema already documents audience_id as 'The audience ID'. The description only restates the ID-based lookup without adding format constraints or validation semantics, so it meets the baseline but adds little over the schema.

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

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

States a specific verb ('Get'), a specific resource ('an audience by its ID'), and adds a meaningful detail ('including its filter definition') that distinguishes the response from a plain metadata fetch. This clearly differentiates it from list_audiences and update_audience among the 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 phrase 'by its ID' clearly indicates the tool is for fetching a single audience when the ID is known, and contrasts implicitly with list_audiences. It does not name alternatives explicitly, so it misses the top score, but the usage context is unambiguous for a simple getter.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Get' is consistent with a safe read operation. The description adds little beyond the annotation and does not disclose error behavior, not-found handling, or return format.

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

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

A single, front-loaded sentence that clearly conveys the action and target with no filler. Every word 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 single-parameter read operation with a read-only annotation, the description is largely sufficient. An agent knows the required input and that the operation is non-mutating, though no return shape is described since no output schema exists.

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

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

The only parameter, audit_event_id, is fully documented in the schema as 'The audit event ID,' giving 100% schema coverage. The description does not add additional 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 states a specific verb and resource: 'Get a specific audit event by its ID,' making the tool's purpose clear and distinguishing it from list_audit_events. However, it does not explicitly name or contrast the sibling list 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 phrase 'by its ID' implies this tool is for retrieving a single known event rather than listing events, but the description provides no explicit when-to-use guidance or mention of alternatives. Usage context is only implied.

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 declare readOnlyHint=true, matching the non-mutating nature of 'Get'. However, the description adds no behavioral information beyond this — no mention of return shape, error cases, permissions, or data scope. With annotations present, the bar is lower, but the description still contributes no extra 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 a single clear sentence with no filler. It is appropriately sized for a simple by-ID retrieval operation.

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

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

For a simple get-by-ID tool with a fully documented required parameter and a readOnly annotation, the description is nearly complete. It does not explain return values or output shape, but no output schema exists and the operation name conveys the expected result adequately.

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 brand_id documented as 'The brand ID'. The description only restates the parameter usage ('by its ID') without adding format, source, or behavioral semantics. Baseline 3 applies because the schema already fully documents the parameter.

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

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

The description states a specific verb ('Get'), resource ('brand'), and retrieval criterion ('by its ID'). It clearly differentiates from siblings like list_brands, create_brand, update_brand, and delete_brand.

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 usage is implied through the description and tool name, but there is no explicit guidance on when to choose this tool over list_brands or other brand-related tools. It is minimally sufficient but does not state 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 declare readOnlyHint=true, and the description's 'get' phrasing aligns with that. The description adds no further behavioral context such as whether polling is safe, what status values may appear, or how long jobs typically take. This is acceptable but not rich.

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, front-loaded sentence that communicates the exact purpose without wasted words. It earns every word.

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 getter with readOnlyHint=true, the description plus schema is sufficient for an agent to invoke it correctly. It does not describe possible status values or error behavior, but those are not necessary for basic invocation.

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

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

The schema fully documents the single required parameter, job_id, including its description ('The bulk job ID'). The tool description adds no additional parameter-level detail, so the schema carries the burden.

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

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

The description states a specific verb ('Get') and resource ('the status of a bulk job'), making the tool's purpose immediately clear. It also distinguishes itself from sibling tools like create_bulk_job and run_bulk_job, which represent different lifecycle stages.

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 intended use is implied: an agent would call this when it needs the current status of a bulk job, likely after creating or running one. However, no explicit guidance is given about when to prefer this tool over related siblings 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?

The readOnlyHint annotation already establishes that this is a safe read, and the description adds behavior beyond it: how draft, historical, and default published versions are resolved. It does not describe invalid-version or not-found behavior, but for a read-only getter with this annotation, the added transparency is meaningful.

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 short sentences and no filler. The core action is front-loaded, followed by the conditional version behavior and the default, so an agent can parse the essential behavior immediately.

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

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

For a simple two-parameter read tool, the description covers required ID and version selection, including the default. The main remaining gap is clarifying the relationship between a journey and a journey template, which is relevant because multiple sibling getters exist and the parameter is described as a template ID.

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 fully documents both parameters. The description's version wording ('draft', 'vN', defaults to published) mostly restates the schema's version values, adding only 'working draft' as a minor clarification.

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

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

The description states a specific action ('Get a journey by ID') and provides concrete version semantics. However, it does not distinguish get_journey from the closely related sibling get_journey_template, and the schema's journey_id is described as a 'journey template ID', which adds ambiguity about exactly which resource is returned.

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 version instructions ('Pass version=draft... vN... Defaults to published') give useful invocation context. The description never says when to choose this tool over list_journey_versions, get_journey_template, or get_journey_template_content, so tool-selection guidance is mostly 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 declare readOnlyHint=true, and the description adds the behavioral nuance that draft retrieval is required before publication and that published is the default. This goes beyond structured fields by explaining template lifecycle state.

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

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

Two tight sentences front-load the operation and resource, then clarify version behavior. No filler or redundant restatement.

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 three-parameter read with full schema coverage and a readOnly annotation, the description covers retrieval target, version selection, and default behavior. It does not specify response shape, but the tool name and 'Get' semantics make that unnecessary.

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 version, journey_id, and notification_id already described. The description restates notification ID and version semantics, adding only the lifecycle hint about needing draft before publication; it does not materially expand parameter meaning.

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

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

States a specific operation ('Get'), a resource ('journey-scoped notification template'), and the lookup key ('by notification ID'). The 'journey-scoped' qualifier distinguishes it from generic notification getters, and the name aligns with the description.

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 concrete guidance on selecting version=draft for unpublished templates and notes the published default. It does not explicitly name alternative tools, but 'journey-scoped' signals when this read is appropriate versus generic notification getters.

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, matching the 'Fetch' verb, so there is no contradiction. The description adds useful version/default behavior beyond the annotation, but it does not describe the return structure or define 'elemental content'.

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 short sentences with the core verb and resource front-loaded. Version logic is presented compactly, and every sentence contributes 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?

The description covers the key decisions an agent must make: what to fetch, the journey scope, and which version to request, including defaults. Required parameters are documented in the schema and read-only safety is in annotations. The main gap is the lack of output shape and explicit sibling differentiation, but this is adequate for a 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%, so the baseline is 3. The description adds light clarification by calling 'draft' the working draft and 'vN' a historical version, but the schema already documents draft, published, version strings, and the default.

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

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

States a specific action ('Fetch') and resource ('elemental content of a journey-scoped notification template'). The 'journey-scoped' qualifier helps distinguish it from generic get_notification_content tools, though it does not explicitly name siblings.

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

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

Provides explicit version handling instructions: pass 'draft' for the working draft, 'vN' for historical versions, and it defaults to published. This is clear context for invocation, but it does not explicitly compare against alternative get_content tools, so exclusions are 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds no behavioral context beyond that, such as handling of missing or archived lists, authentication needs, or response characteristics.

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

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

A single, front-loaded sentence communicates the operation with no filler or redundancy. Every word contributes to understanding the tool's 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?

For a low-complexity read operation with one fully documented parameter and a readOnly annotation, the description is largely sufficient. It does not explain what a 'list' represents in this API or describe return values, but the simplicity of the tool makes this a minor gap.

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

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

The schema provides 100% coverage for the single list_id parameter with 'The list ID'. The description merely restates this concept ('by its ID') without adding format, type, or usage nuance 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 (get), the resource (a list), and the identifying mechanism (by its ID). It is unambiguous as a single-resource retrieval operation, though it does not explicitly differentiate itself from sibling tools like get_list_subscribers or list_lists.

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 provided about when to use this tool versus alternatives such as list_lists when enumerating lists or get_list_subscribers when retrieving subscribers. The intended context must be inferred entirely from the tool name and ID-based parameter.

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 supply readOnlyHint=true and the description does not contradict it, so the read-only safety profile is covered. However, the description adds no behavioral nuance beyond the tool name; notably, it does not disclose that results are paginated despite the cursor parameter, and it does not describe what the response contains.

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 terse and front-loaded: one sentence with no filler. It could be improved by noting pagination, but as written it is efficiently scannable and 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 retrieval with readOnlyHint=true and a fully documented two-parameter schema, the core invocation is clear. The missing pagination and return-behavior details are a real gap because there is no output schema, and 'all' could reasonably be read as a single unpaginated response; a brief note about cursor paging would make it 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 covers 100% of parameters with clear descriptions ('The list ID', 'Pagination cursor'), so the description need not repeat them. The 'all subscribers' phrasing loosely relates to the cursor's purpose but does not add concrete parameter semantics 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?

Description states a specific read operation ('Get') on a specific resource ('subscribers of a list'), making it immediately distinguishable from siblings like get_list, get_user_list_subscriptions, and subscribe_user_to_list. The 'all' qualifier adds scope. Minor ambiguity around pagination exists, but the purpose itself is unambiguous.

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

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

The description provides no explicit when-to-use guidance or alternatives, but 'all subscribers of a list' makes the intended use inferable: retrieve subscriber membership for one list. It does not mention exclusions or explicitly distinguish it from related tools like get_user_list_subscriptions or list_audience_members.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds minor context by mentioning 'full details and status' but does not disclose return shape, error behavior, or other operational traits.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the core purpose, making it easy to scan and parse.

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

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

For a one-parameter, read-only lookup with no output schema, the description is mostly sufficient for an agent to understand the tool's role. It could be slightly richer by describing what 'status' includes or what response shape to expect, but the low complexity keeps the gap small.

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 message_id as 'The message ID to retrieve' with 100% coverage. The description merely repeats 'by its ID' without adding new meaning or format expectations.

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 ('Get') and identifies the resource ('a single message') and key ('by its ID'). It loosely distinguishes from list_messages and content/history getters via 'full details and status', but does not explicitly name or disambiguate sibling tools.

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

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

No guidance is given about when to use this tool versus alternatives like get_message_content, get_message_history, or list_messages. The description is purely declarative and leaves selection criteria to inference.

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

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

Annotations declare readOnlyHint=true, so the read-only nature is already covered. The description adds a bit of useful context by naming the exact output facets (HTML, text, subject) and the 'rendered' nature. It doesn't disclose edge-case behavior such as behavior for unsent messages or errors, but this is a simple read operation with the safety profile already captured.

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

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

A single, front-loaded sentence with zero filler. Every word adds information: the action, the resource type, the exact data returned, and the lifecycle constraint.

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 one-parameter read-only tool with no output schema, the description covers the essential purpose and the target object. It could have mentioned the response format or how to handle missing messages, but given the low complexity, nothing critical 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 coverage is 100%, so the message_id parameter is already documented in the schema. The tool description adds only the lifecycle context ('previously sent message'), which slightly enriches what message_id refers to, but does not introduce format, type, or usage details beyond the schema. Baseline 3 applies.

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

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

The description uses a specific verb ('Get') and identifies a distinct resource: 'rendered content (HTML, text, subject) of a previously sent message.' It clearly differentiates from siblings like get_message, get_message_history, and get_notification_content by specifying the exact payload and lifecycle stage.

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 'previously sent message' provides clear context for when to invoke this tool—only for messages that have already been sent—but it does not explicitly exclude alternatives or reference sibling tools. It stops short of demonstrating full routing logic, though the context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that. It adds value beyond the annotations by describing the returned information as a sequence of delivery stages, which tells the agent what kind of lifecycle data to expect.

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 entire description is one focused sentence that front-loads the core action and immediately clarifies the return content with examples. 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?

For a simple read-only lookup with fully documented parameters and a safe annotation, the description is nearly complete. It gives enough examples to understand the output even without an output schema, though it does not specify ordering or pagination.

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 message_id and type both documented in the schema. The tool description adds no additional parameter semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get the event history for a message.' It also adds concrete examples of the pipeline stages (enqueued, sent, delivered), which clearly distinguishes this from sibling tools like get_message or get_message_content.

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 makes it clear this is the tool for delivery-pipeline event history, giving enough context for an agent to select it over get_message or get_audit_event. It does not explicitly name alternatives or exclusions, but the use case is strongly implied.

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, so the safe read-only nature is already disclosed. The description adds version-selection detail, but this largely mirrors the schema parameter description and does not reveal additional behavioral traits such as return format or error behavior. 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?

Two short sentences with the core action front-loaded and the optional version behavior in the second sentence. No unnecessary words or repetition.

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

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

For a simple read-only getter, the description covers the essential inputs: notification ID and optional version. It doesn't describe the return payload, but with no output schema and a readOnlyHint annotation, the definition is reasonably complete; only minor ambiguity about what 'template' includes versus content endpoints remains.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description restates the version options ('draft, published, or a version such as v001') but adds little 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 uses a specific verb ('Retrieve') and resource ('notification template by ID'), making the core purpose clear. It distinguishes from list-oriented siblings by emphasizing by-ID lookup, though it does not explicitly differentiate from get_notification_content or get_notification_draft_content.

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 use by ID and optional version selection, but gives no explicit guidance on when to choose this tool over alternatives like get_notification_content, get_notification_draft_content, or list_notifications. Given the large sibling set, this is a meaningful gap.

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

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

The readOnlyHint annotation is consistent with the 'Get' action, so there is no contradiction. The description adds that the result is the published content blocks, but offers no details beyond that, such as return value structure, pagination, or access requirements.

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 compact sentence with no filler. Every word contributes meaning, and the key differentiator ('published') is placed near the start.

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, read-only tool with no output schema, the description is largely sufficient: it identifies what is returned and which entity it applies to. It could improve by explicitly routing to the draft-content sibling or clarifying what 'content blocks' means, but those gaps are minor.

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

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

The schema has 100% coverage and already documents notification_id as the notification template ID. The tool description adds no new parameter behavior, format, or example, so it meets the baseline without exceeding it.

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

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

The description states a specific verb and resource: get the published content blocks of a notification template. It differentiates from draft-related tools through the word 'published', though it does not explicitly name or contrast sibling tools like get_notification_draft_content.

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

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

Usage context is implied by the word 'published', suggesting the tool is for published content rather than drafts. However, there is no explicit when-to-use versus alternative guidance, so the agent must infer the distinction from sibling names.

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, covering the main safety profile. The description adds the scoping detail that only draft/unpublished content is returned, but discloses no further behavioral context such as auth requirements or response format.

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

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

The description is a single sentence with no filler. The key qualifier 'draft (unpublished)' is included and the sentence is appropriately sized for a simple one-parameter read tool.

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

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

For a read-only tool with one required parameter and a clear resource description, this is sufficiently complete. There is no output schema, so the agent infers the return shape from 'content blocks', but all core selection and invocation information is present.

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

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

Schema coverage is 100%: notification_id is already described as 'The notification template ID' in the schema. The description reinforces that this is a notification template but adds no new meaning beyond the structured 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 uses a specific verb and resource: 'Get the draft (unpublished) content blocks of a notification template.' The 'draft (unpublished)' qualifier distinguishes it from the sibling get_notification_content, which presumably returns published content.

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 frames the intended use case: retrieving unpublished draft content blocks rather than published notification content. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for an agent to select it appropriately.

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 annotation already declares readOnlyHint=true, so the read-only nature is covered. The description adds useful behavior beyond the annotation by specifying that topics are included in the result, but it does not disclose return shape, possible errors, or other behavioral details.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase adds value: the action, the target, the lookup key, and the included topics.

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 one-parameter, read-only get-by-id tool, the description is sufficient for an agent to select and invoke it correctly. It specifies the required input, identifies the resource, and even clarifies what the response includes ('including its topics'). No essential information 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?

The input schema has 100% description coverage and section_id is already described as 'Id of the preference section'. The description does not add meaningful parameter semantics beyond restating the by-id concept, so the baseline of 3 applies.

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

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

The description states a specific verb ('Retrieve'), a specific resource ('preference section'), and the key qualifier 'by id'. It also notes that topics are included, which distinguishes this from get_preference_topic and list_preference_sections.

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 'by id' qualifier makes the intended use clear: fetch one specific preference section when its id is known. It does not explicitly name alternatives like list_preference_sections, but the context clearly implies a targeted get-by-id operation.

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

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

The annotations already declare readOnlyHint=true, so the description's main contribution is the 404 behavior: it specifies that a missing section or topic, or a topic owned by a different section, results in a 404. This goes beyond the annotation and helps the agent anticipate failure states. It does not describe the success response format, but given the read-only nature and no output schema, the 404 details are valuable and add transparency.

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

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

The description is two short sentences, effectively front-loaded with the core action ('Retrieve a topic within a section') followed by the key error condition. There is no redundant wording or filler, and every sentence contributes useful information.

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

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

For a simple retrieval tool with two required parameters and readOnly annotation, the description covers the access scope and failure modes. However, it does not state what a successful call returns (e.g., the topic object), which is notable since there is no output schema. An agent might infer it returns the topic, but explicit mention of the success payload would make it more complete. The 404 details are helpful, but the absence of success-response description 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%, with both parameters having clear ID descriptions. The description adds the contextual relationship that the topic must belong to the given section, which is a semantic hint beyond the schema's simple ID labels. However, it does not elaborate on parameter formats, types, or constraints beyond what the schema states, so it only marginally supplements the schema.

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

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

The description states a specific verb ('Retrieve') and resource ('a topic within a section'), clearly distinguishing it from sibling tools like get_preference_section (retrieves a whole section) and list_preference_topics (lists topics). The phrase 'within a section' clarifies the hierarchical relationship, leaving no ambiguity about what the tool does.

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

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

The description gives clear context that the tool requires both a section and a topic, and implies it is used when you have both IDs. However, it does not explicitly name any alternative tool or state when not to use it. The 404 condition about a topic belonging to a different section adds usage nuance, but no direct comparison to siblings like get_preference_section or list_preference_topics. This is clear context without 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?

The annotations already declare readOnlyHint=true, and the description's 'Fetch' is consistent with that. The description adds little beyond the annotation, though it does clarify the operation is a single-item lookup rather than a list operation. No behavioral contradiction exists.

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

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

A single clear sentence that front-loads the action and the key distinguishing constraint ('by ID'). There is no redundant or filler 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?

For a simple one-parameter, read-only getter with no output schema, the description provides enough information for an agent to invoke it correctly: it knows the resource, the single required parameter, and that this is a read operation. It does not describe return format or not-found behavior, but those are not necessary to make the call successfully.

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