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?

Beyond the annotations (destructive, idempotent, not read-only), the description adds valuable behavioral context: existing runs are unaffected because they retain their own copies, and the Courier Recommended set is protected from archiving. This helps an agent anticipate side effects and avoid an invalid invocation.

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

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

The description is two short sentences with no wasted words. The core action is front-loaded, and the two behavior-relevant caveats follow immediately. 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 one-parameter archive tool with no output schema, this description is complete: it states what happens, why it's safe for existing runs, and the one prohibited target. An agent has enough information to decide when to use it and how 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 input schema already provides 100% coverage for the single parameter device_set_id, including its format hint (pvs_...). The description adds no additional parameter-level detail, which is acceptable since the schema fully documents the required input.

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 the action clearly: 'Archive a preview device set.' This uses a specific verb and resource, distinguishing it from related siblings like create_preview_device_set, replace_preview_device_set, get_preview_device_set, and list_preview_device_sets. The first sentence alone makes the tool's purpose unambiguous.

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

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

The description gives clear context: runs that used the set keep their own copy, so archiving is safe for historical data. It also gives a direct when-not condition ('The Courier Recommended set cannot be archived'). It doesn't explicitly name alternative tools, but the operation is self-explanatory and the constraints are practical.

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 idempotentHint and destructiveHint, and the description adds the key context that the broadcast itself is preserved, which refines what 'destructive' means here. It does not overpromise or 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 two short sentences with no filler. The primary action is front-loaded, and the clarifying scope ('broadcast itself is kept') earns its place 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 single-parameter, no-output-schema tool, the description plus annotations cover the essential behavior: what is canceled, what is preserved, and that the operation is destructive-but-idempotent. Minor missing context about response values or no-op behavior is acceptable given the tool's 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%: the only parameter, broadcast_id, is already described as 'The broadcast id'. The description adds no new parameter-level detail beyond tying it to the broadcast being canceled, 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 states a specific verb ('Cancel') and a precise resource ('a broadcast's scheduled send'), and clarifies the broadcast itself is kept, distinguishing this from delete_broadcast and other cancellation tools. This is unambiguous and actionable.

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 for future scheduled sends rather than sent messages, but it does not explicitly state when to prefer this over siblings like cancel_message, cancel_automation, or delete_broadcast. No alternatives or exclusions are named.

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 declare readOnlyHint=true, so the description is not required to restate read-only behavior. It adds valuable context beyond the annotation by noting that client-side platforms need a JWT and that each guide names the tool that issues one. This is a helpful cross-reference and prerequisite warning without contradicting the annotations.

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

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

Three sentences, zero fluff. The first sentence immediately states the purpose and contents; the second gives the common trigger phrases; the third adds the important JWT caveat. Every sentence earns its place and the key information 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 single-parameter, read-only tool with no output schema, the description is complete. It explains what the tool returns (install command, sample, doc links), when to use it, and the JWT nuance. An agent has everything it needs to select and invoke this tool correctly.

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

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

Schema description coverage is 100%: the single 'platform' parameter has an enum of seven valid values and a clear description ('Which SDK to return the installation guide for'). The description adds only a hint that client-side platforms need JWT authentication, but it does not enumerate which platforms are client-side, so it does not materially enrich the 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?

The description clearly states a specific verb ('Get'), resource ('Courier SDK installation guide'), and scope ('for one platform'), and lists the guide's contents (install command, quick-start sample, doc links). It is plainly distinct from all sibling tools, which are API operations on Courier resources, so an agent can differentiate it without opening 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?

It provides explicit usage context: 'This is the answer to "how do I integrate Courier" or "how do I get started"'. It does not name alternatives or exclusions, but no sibling tool is a plausible alternative (none return installation guides), so the context is sufficient. The JWT note also guides when authentication prerequisites matter.

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 already mark this as read-write and non-destructive. The description adds useful behavioral context beyond annotations: the created broadcast 'starts as a draft with no content'. It also outlines the expected sequence, which helps the agent understand the object's state after creation. Idempotency is not elaborated, but idempotentHint=false already covers that.

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 zero filler. The core purpose is front-loaded ('Create a broadcast'), and the workflow is stated compactly in the second sentence. 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 create tool with two scalar parameters and no output schema, the description is complete enough. It states the draft state and the next steps. It does not cover edge cases like name collisions or channel mutability, but given the annotations and schema, these are minor omissions.

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 both parameters (name, channel) are already fully described in the schema. The description adds only that the broadcast is a draft with no content, which implies the channel is set at creation but does not add semantics for the parameters themselves. Baseline 3 is appropriate for high schema coverage.

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

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

The description uses a specific verb-resource pair ('Create a broadcast') and clarifies the scope: a one-off message to a list or audience on a single channel. It also notes the draft state, distinguishing it from content-loading (put_broadcast_content) and sending (send_broadcast/schedule_broadcast) 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?

It explicitly describes the intended workflow: create the broadcast first, then add content with put_broadcast_content, then send or schedule. This tells the agent when to use this tool and names the follow-up alternatives. No exclusions are given, but the lifecycle guidance 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?

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?

Annotations only declare readOnlyHint false, but the description adds critical behavior: templates are always created as drafts, content.elements must be wrapped in a channel block or the API rejects it, the response carries a verification object whose semantics are explained, and an unauthorized errorKind still means the template was created. This goes far beyond the annotations and contains no contradictions.

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

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

The description is longer than average, but every clause adds essential operational detail: draft status, channel block requirement, verification semantics, unauthorized caveat, and a complete example. It is front-loaded with the purpose before caveats. Slight redundancy with the schema's own examples keeps it from a 5.

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

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

For a mutation tool with nested parameters and no output schema, the description covers the non-obvious behaviors an agent must know: creation always draft, verification result meaning, and errorKind semantics. Combined with 100% schema coverage and annotations, nothing critical is left to guesswork.

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 already 100%, but the description adds a complete example, explains the required nesting of elements inside a channel block, and warns to copy journey_id exactly rather than retype it. It also reinforces that state must be DRAFT. This adds meaning beyond the schema's field 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 states a specific verb and resource: 'Create a notification template scoped to a journey.' It immediately distinguishes this from siblings like create_notification (not journey-scoped) and create_journey (creates the journey, not the template). The draft-only constraint further clarifies what the tool does and does not do.

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 when to use the tool: to create a journey-scoped notification template that is always a draft, and explicitly says making it live is a separate step this tool cannot perform, implicitly pointing to publish_journey_template. It also gives fallback guidance for verification false (re-read journey, do not create a second template). It does not name sibling tools explicitly, so not a 5.

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

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses that a newly created template defaults to draft, cannot be published through this tool, and may have content updated separately. This gives an agent important workflow context without contradicting any annotation.

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

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

The description is front-loaded with the core purpose, then delivers constraints, workflow caveats, and a full example in a compact block. Every sentence conveys necessary decision-relevant information; the example is long but earned because it shows the required nested structure.

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

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

For a nested-object creation tool with no output schema, this is complete: the schema documents each field exhaustively, and the description adds the draft/publish lifecycle, routing intent, and the option to set content later. An agent has enough to construct a valid request and know what this tool does not do.

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 parameters; the description adds value by explaining why routing is linked ('to control which channels are used') and showing a complete example of the required notification object. It reinforces that name is required and that content can be deferred, which is not evident from the JSON schema alone.

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?

Opens with 'Create a V2 notification template,' a specific verb and resource that immediately distinguishes creation from sibling get/archive/publish/replace notification tools. It also clarifies draft state and names required fields, so an agent can recognize what resource is being produced.

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 this tool creates only drafts and explicitly states 'making it live is a separate step this tool cannot perform,' which tells the agent not to expect publication here. It also notes content may be supplied later, implying a follow-up content-editing tool, though it doesn't name sibling tools like publish_notification explicitly.

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?

Beyond the annotations (readOnly false, destructive false, idempotent false), the description adds that the topic id is generated and returned, and that it fails with a 404 if the section does not exist. This gives useful behavioral context about side effects and error conditions.

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 concise sentences, front-loaded with the core action, followed by a key result and an error condition. No unnecessary words or redundancy; 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?

Given the tool's complexity (8 parameters, nested objects) and no output schema, the description is minimal but sufficient because the schema already documents all parameters thoroughly. It covers the essential behavioral points (creation, return value, error condition) and relies on annotations for safety and idempotency. It could mention idempotency but that's covered by annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not elaborate on any parameters; it only references section existence implicitly. It adds no extra meaning beyond what the schema already provides, so a 3 is appropriate.

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

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

The description clearly states the tool creates a subscription preference topic within a section, using a specific verb and resource. It implicitly distinguishes from create_preference_section by specifying 'inside a section', and the generated id and 404 behavior add precision.

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

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

The description does not explicitly mention when to use this tool versus alternatives like create_preference_section or update tools. It implies usage context by noting the dependency on an existing section, but provides no exclusions or routing guidance to 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 signal that this is a mutating, non-idempotent, non-destructive operation. The description adds 'named, reusable' but does not disclose additional behavioral details such as duplicate-name handling or what happens on invalid device_ids. It is consistent with annotations and minimally adequate.

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 with no filler. Key qualifiers ('named, reusable') are front-loaded, and 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?

The tool has low complexity, a fully documented schema, and annotations covering the safety profile. The description is sufficient for basic invocation, though it does not mention return values or duplicate-name behavior; these are minor gaps for a create operation.

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

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

Schema description coverage is 100%, with both parameters already documented: name is a human-readable string, and device_ids must come from list_preview_devices with invalid ids rejected. The description adds little 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 a specific verb ('Create') and resource ('preview device set'), and adds clarifying qualifiers 'named, reusable'. This distinguishes it from siblings like create_preview_run, replace_preview_device_set, and archive_preview_device_set.

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—when creating a named, reusable set of preview devices—but gives no explicit guidance about alternatives such as replace_preview_device_set for updates or archive_preview_device_set for removal. Usage context is present but not elaborated.

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 this is a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false). The description adds valuable context: it bills to the workspace's previews add-on and starts in PENDING state, requiring polling. These are behavioral side effects that go beyond the annotations and inform the agent of consequences and follow-up actions. There is no contradiction with annotations.

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

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

The description is three sentences with zero redundancy. The primary action is front-loaded, followed by the key usage rule, a billing caveat, and the async nature. Every sentence contributes essential information, 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?

The tool has six parameters, a nested object, no output schema, and no enum constraints. The description covers the core purpose, the mandatory device argument selection, the cost implication, and the asynchronous workflow (poll get_preview_run). This is sufficient for an agent to invoke it correctly and know what to expect next, despite the lack of an 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 coverage is 100% (all six parameters have descriptions). The description adds the cross-parameter constraint 'exactly one of device_set_id or device_ids', which is not captured in individual schema descriptions. This is a meaningful semantic addition beyond the schema, meriting a score above the baseline of 3.

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

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

The description states a specific action ('Render a template's email on real email clients and capture screenshots') with a clear resource (a template's email preview run). It distinguishes itself from siblings like list_preview_runs and get_preview_run by focusing on creation, and it adds the key constraint ('Pass exactly one of device_set_id or device_ids') that clarifies its scope.

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 the mutual-exclusion rule for device_set_id vs device_ids, warns about billing, and directs the agent to poll get_preview_run. This is clear operational guidance. It does not explicitly name alternatives or when-not-to-use scenarios, but the workflow is well implied and the constraints are direct.

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 description is consistent with annotations (destructiveHint=true, idempotentHint=true) but adds no behavioral context beyond the word 'delete'. It doesn't mention whether deletion is permanent, whether scheduled broadcasts are canceled, or any side effects. With annotations present, the description should add extra context but fails to do so.

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 short sentence with no filler words, front-loading the core operation. It is concise and well-structured, though it is also under-specified—a completeness concern rather than a conciseness one.

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 destructive tool with no output schema and only one parameter, the description is too minimal. It doesn't explain the consequences of deletion, whether it affects scheduled broadcasts, or how it relates to sibling tools like cancel_broadcast_schedule. The annotations cover the destructive nature, but the description fails to provide a complete operational picture.

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 broadcast_id with the description 'The broadcast id', so the parameter is already documented. The tool description adds no further semantic meaning about the parameter, matching the baseline of 3 for high schema coverage.

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

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

The description 'Delete a broadcast.' clearly states the verb (delete) and resource (broadcast), making the primary action obvious. However, it doesn't differentiate from related broadcast actions like cancel_broadcast_schedule or note whether this is a permanent hard delete, so it stops short of full 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?

There is no guidance on when to use this tool versus cancel_broadcast_schedule, archive tools, or other delete_* tools. No prerequisites, exclusions, or alternative conditions are mentioned, leaving the agent to infer the appropriate usage context.

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

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

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds the key behavioral guarantee that the original is left unchanged, which is valuable context beyond the annotations. It also clarifies the result is a new draft, not a sent broadcast. It doesn't mention side effects like whether the draft is immediately visible or requires further steps, but for a simple copy operation this is adequate.

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 wasted words. The core action is front-loaded, and the non-destructive guarantee is stated in the second sentence. 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 single-parameter, no-output-schema tool, the description is nearly complete. It states the action, the result (new draft), and the non-destructive nature. It could mention whether the new draft is immediately editable or requires additional setup, but that is a minor gap given the simplicity of the 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%: the only parameter, broadcast_id, is described as 'The broadcast to copy'. The description adds no additional parameter-level detail, but none is needed given the single, self-explanatory parameter. 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 states a specific verb ('Copy') and resource ('a broadcast into a new draft'), and explicitly notes the original is left unchanged. This clearly distinguishes it from related broadcast tools like create_broadcast, send_broadcast, schedule_broadcast, and rename_broadcast.

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 use case: duplicating an existing broadcast to create a draft without modifying the original. It doesn't explicitly name alternatives or exclusions, but the context of sibling tools (create_broadcast, send_broadcast, rename_broadcast) makes the intended usage clear. A small gap: it doesn't state when to prefer this over create_broadcast.

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 already declare readOnlyHint=true, so the description correctly focuses on additional behavioral context: it clarifies that membership is derived from a filter rather than a stored member list. This is meaningful beyond the annotation and helps the agent reason about the returned data.

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 compact sentences with no filler. The core action is front-loaded, the conceptual clarification follows, and the sibling alternative is given at the end without redundancy.

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

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

For a single-parameter, read-only tool with no output schema, the description covers what the tool returns, why an agent would use it, and how it differs from the closest sibling. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the single parameter audience_id is already described as 'The audience ID'. The description merely echoes 'by ID' without adding new semantic detail, so the schema carries the load and a baseline score of 3 is appropriate.

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

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

States a specific verb+resource ('Get one audience by ID') and adds the unique distinguishing detail that it returns the membership filter, not a member list. This clearly separates it from siblings like list_audiences and list_audience_members.

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

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

Explicitly explains when to use this tool: to explain why someone is or is not in an audience, because the filter is the rule. It also names the alternative, list_audience_members, for the related but different need of seeing who currently matches.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by stating what data the response includes (colors, logo, styling settings) and the purpose this serves, going beyond the bare annotation without contradicting 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?

Two concise sentences pack the resource, scope, returned content, and a use case with no filler. The primary action 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 single-parameter read tool with readOnlyHint and no output schema, the description is sufficient: it names the resource, the lookup key, the key returned fields, and the motivating use case. It could add explicit error/not-found behavior, but that is not necessary for basic 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 the sole brand_id parameter is documented in the schema. The description does not add new parameter meaning, so it meets the baseline but no more.

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 (get) on a specific resource (brand by ID) and enumerates the meaningful payload (colors, logo, styling settings), which distinguishes it from list_brands and brand mutation tools. The second sentence gives a concrete use case for interpreting templates.

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 when to call this tool: when you need a brand's visual styling to describe what a referencing template will look like. It does not explicitly name alternatives or exclusions, but the single-brand-by-ID semantics and sibling set make the intended use obvious.

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

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

Annotations already provide readOnlyHint=true, and the description's verb 'Get' is consistent. The description adds value by specifying that the response includes channel and send/schedule state, which is not implied by the schema or annotations. It does not contradict annotations and provides useful context about the return payload.

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: 'Get a broadcast by id' immediately conveys the core action, followed by the relevant return details. There is no redundant wording or filler, 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 simple read operation with one parameter, the description adequately explains what is returned (channel and send/schedule state). No output schema exists, so this explicit mention is helpful. It does not cover edge cases or error behavior, but for a basic get-by-id tool, this is sufficient. A slightly more detailed explanation of 'send or schedule state' could elevate it, but it is not essential.

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 broadcast_id as 'The broadcast id' (100% coverage). The description does not add additional meaning to this parameter, but with full schema coverage, the baseline of 3 is appropriate. No further clarification is necessary for a single, self-explanatory 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'), a specific resource ('a broadcast'), and identifies it by 'id'. It also clarifies what is included in the response ('channel and send or schedule state'), distinguishing it from siblings like get_broadcast_content. This clearly separates it from other retrieval tools.

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

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

The description implies its use for fetching a broadcast's details and state, but it does not explicitly mention when to use it over alternatives such as get_broadcast_content or list_broadcasts. With many sibling get_* tools, some explicit guidance on selection would improve clarity, though the purpose itself 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 adds only the 'Elemental content' qualifier as extra context. It does not describe output shape, nullability, or other behavioral details, but for a straightforward read-only getter this is an acceptable baseline.

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

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

The definition is a single, front-loaded sentence with no filler. It states the action and resource concisely, 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?

This is a one-parameter, read-only getter with no output schema, so the description is largely sufficient. The only minor gap is that 'Elemental content' is left undefined, which may leave an agent uncertain about the exact returned artifact.

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

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

The input schema covers 100% of the parameters with a clear description for broadcast_id, and the tool description adds no further parameter meaning. Baseline of 3 is appropriate because the schema carries the semantic weight.

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 as a broadcast's 'Elemental content', which distinguishes it from related tools like get_broadcast or put_broadcast_content. It does not explicitly explain what 'Elemental content' means, so it falls just short of full clarity.

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

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

The description gives no indication of when to choose this tool over siblings such as get_broadcast, get_message_content, or put_broadcast_content. There are no exclusions, prerequisites, or contextual triggers, leaving selection heuristics 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 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 description adds behavior beyond the readOnlyHint annotation by explaining versioning semantics: defaults to published, supports draft and historical versions. It makes the read behavior concrete and gives the agent an expectation about what will happen when no version is supplied.

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 carry the core operation and versioning behavior with no wasted words. The primary purpose appears first and the default behavior is stated clearly at the end.

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

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

This is a simple two-parameter read operation, with readOnlyHint set and full schema coverage. The description gives the launching semantics and required parameters; while it doesn't describe the returned object shape, no output schema exists and the normal expectations for a fetch-by-ID tool are met.

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 both parameters fully with 100% description coverage. The description rephrases the version parameter as 'working draft' versus 'historical version', which adds minor color but no new semantic information beyond the schema.

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

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

The description states a specific verb and resource: 'Get a journey by ID' and explains the version variants (draft, vN, published). This clearly separates it from siblings like get_journey_template and list_journeys, which enumerate or access templates, not a single journey by 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 gives clear invocation guidance for the version parameter: pass draft, pass vN, or rely on the published default. However, it does not explicitly compare get_journey to alternative retrieval tools or state when it should be used versus those alternatives, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds useful behavioral context by naming the return fields (journey, status, timestamps), but it does not disclose error/not-found behavior or output format. Since annotations cover the safety profile, this is adequate but not exceptional.

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 11-word sentence that front-loads the verb and resource, states the identifier method, and lists the key return fields. 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?

For a single-parameter get tool with readOnly annotation and no output schema, the description is largely complete: it states what the tool does and what fields the result contains. It could optionally mention not-found behavior or explicitly route to list_journey_runs for enumeration, 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% and run_id is already well described as 'The journey run id'. The description only reinforces 'by id' without adding format, examples, or lookup semantics. Baseline 3 is appropriate given the schema carries the semantic weight.

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 explicitly that it retrieves a single journey run by id and enumerates the returned aspects (journey, status, timestamps). This clearly distinguishes it from siblings like get_journey, list_journey_runs, and list_journey_run_steps without requiring schema inspection.

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 usage: when you have a run_id and need a single run's details. However, it does not explicitly mention alternatives or when-not-to-use, such as 'for listing runs use list_journey_runs'. The sibling names provide context, but the description itself leaves exclusions 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 annotation already carries readOnlyHint=true, and the description adds meaningful mode-dependent behavior: draft retrieval is mandatory pre-publication, while published is the default. This goes beyond the annotation, though it stops short of describing response contents or pagination.

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

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

Two sentences with zero filler: the core purpose is front-loaded, and the draft/published caveat follows immediately. 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 read-only tool with fully documented parameters, an agent has everything needed to invoke it correctly: required IDs, version semantics, and the safety profile from annotations. There is no output schema, so the return shape is unspecified, but the name and 'template' wording make the response type reasonably predictable.

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 provides strong guidance, including exact character-for-character copying instructions for both IDs and the enumerated version values. The description adds one layer of meaning beyond the schema: the rule that version=draft is required before publishing, clarifying when each version value 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 names a specific verb (get), a specific resource (journey-scoped notification template), and the lookup key (notification ID). The qualifier 'journey-scoped' differentiates it from sibling getters such as get_notification and get_journey_template_content, and the version semantics are stated directly.

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 concrete usage context: pass version=draft when the template has not yet been published, and rely on the published default otherwise. It does not explicitly name sibling tools or state when-not-to-use, so an agent must infer the boundary against get_notification and get_journey_template_content.

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, so the tool is known to be a safe read operation. The description adds context by explaining version resolution (draft, historical, or published default), which is valuable. However, it does not disclose other behavioral aspects such as error handling, what 'elemental content' exactly returns, or any implications of the journey-scoped context. Since annotations cover safety, this is adequate but not comprehensive.

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 well-structured: two sentences, the first stating the core purpose and the second providing version usage. It front-loads the primary action and avoids redundancy or unrelated details. Every sentence contributes meaningful information with 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?

Given that the tool has a read-only annotation, no output schema, and 3 parameters (2 required), the description covers the essential usage: what it fetches and how to specify versions. It does not explain the return format or contrast with very similar siblings, which might be helpful but is not critical for a simple fetch operation. The description is sufficient for an agent to call it correctly for most scenarios.

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 all three parameters are already documented in the schema with descriptions. The description adds minimal value by reaffirming the default version behavior ('Defaults to published'), which is already stated in the schema's version description. It does not introduce new parameter semantics beyond what the schema provides, 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 clearly states the tool fetches 'elemental content of a journey-scoped notification template', using a specific verb ('Fetch') and resource. It also distinguishes itself from siblings by specifying 'journey-scoped' and version handling, which separates it from generic get_notification_content or get_journey_template. The version parameter is explicitly described, making the tool's function 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 usage guidance for the version parameter ('Pass version=draft for the working draft, or vN for a historical version. Defaults to published.') but does not contrast this tool with related siblings like get_journey_template or get_notification_content. It implies the tool is for journey-scoped content, but does not explicitly state when to choose this over alternatives. Some context is given, but exclusions are missing.

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