Courier

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

Annotations already declare readOnlyHint=false and idempotentHint=false, aligning with the mutation implied by 'Add'. The description adds context that the job must already exist, but does not disclose details like duplicate handling or effects on a running job. Since annotations cover the basic safety profile, a neutral score is appropriate.

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, direct sentence with no unnecessary words. It is well-structured and immediately conveys 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?

Given the tool's low complexity (2 simple parameters, no nested objects) and the annotations indicating mutation, the one-sentence description is largely sufficient. It could mention return value or side effects, but for a simple add operation this is adequate.

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

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

Schema description coverage is 100%, with both job_id and users adequately described. The description does not add any extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Add' and identifies the resource as 'existing bulk job', clearly distinguishing it from tools like create_bulk_job or run_bulk_job. It immediately clarifies the scope (existing job) and action.

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 tool is used to populate an existing bulk job before running, but it doesn't explicitly state when to use it versus alternatives like create_bulk_job or run_bulk_job. There is no mention of 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 mark the tool as non-readonly and non-idempotent, but the description adds value by explicitly stating it appends rather than replaces existing entries. It does not contradict annotations and provides meaningful behavioral context about preserving existing subscribers.

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

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

The description is a single, compact sentence that conveys the core behavior without unnecessary words. Every element is informative.

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 append operation, the description, schema, and annotations cover the essential usage. It does not address edge cases like duplicate recipients or nonexistent lists, but given the tool's low complexity and no output schema, the provided information is adequate.

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

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

Both list_id and recipients are described in the schema with clear labels, and the description does not add extra parameter semantics. Since schema coverage is 100%, the description's lack of parameter detail is acceptable, defaulting to 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 uses the verb 'Append' and specifies the resource 'subscribers to a list,' making the action precise. The phrase 'without removing existing subscribers' clarifies the scope and differentiates from replace-style operations, aligning with the tool's 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 the use case of adding new subscribers while preserving current list membership, but it does not explicitly state when to prefer this over alternatives like bulk_subscribe_to_list or subscribe_user_to_list. There is no mention of exclusions or prerequisites, so the usage guidance remains implicit.

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

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

The annotation idempotentHint=true is provided, but the description adds no additional behavioral context. It doesn't say what happens if the user is already in the tenant, whether the profile parameter creates or updates overrides, or any side effects. With annotations covering the idempotency, the description still adds zero value beyond the name.

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, 'Add a user to a tenant,' is extremely concise and front-loaded. It contains no filler or redundant information.

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

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

For a simple write operation with annotations and complete schema documentation, the description is minimally adequate. However, it lacks context about the optional profile overrides and does not mention the existence of bulk alternatives, which would enhance completeness.

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

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

Schema description coverage is 100%, so all parameters (user_id, tenant_id, profile) are already documented in the schema. The description does not add any extra meaning or clarify the profile object semantics, so it meets the baseline but does not go beyond.

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 exactly what the tool does with a specific verb and resource: 'Add a user to a tenant.' It's clear and unambiguous, and the naming pattern distinguishes it from siblings like 'remove_user_from_tenant' and bulk alternatives such as 'bulk_add_user_tenants'.

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. There is no mention of when to prefer 'add_user_to_tenant' over bulk operations like 'bulk_add_user_tenants' or 'add_bulk_users', nor any exclusions or prerequisites.

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

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

The description adds meaningful behavioral context beyond the annotations, explaining that archived journeys cannot be invoked and existing runs continue to completion. This complements the idempotent and destructive hints without contradicting them.

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

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

The description is two sentences, front-loaded with the main action and followed by a concise consequence. 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 tool with annotations and no output schema, the description adequately explains the side effects and usage context. It could mention reversibility or return values, but these are not essential 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?

The input schema fully describes the only parameter (journey_id) with a description, and the tool description doesn't add further parameter details. Since schema coverage is 100%, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Archive a journey') and the resource, distinguishing it from siblings like archive_journey_template and cancel_journey by specifying that archived journeys cannot be invoked while existing runs continue.

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 this tool: to stop new invocations while allowing ongoing runs to finish. It doesn't explicitly name alternatives or state when not to use it, but the behavioral context provides clear guidance.

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

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

Annotations already indicate idempotentHint and destructiveHint. The description adds a meaningful behavioral consequence—'Archived templates cannot be sent'—which goes beyond the annotations by explaining the post-archive state. No contradiction with annotations found.

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

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

The description is a single concise sentence, front-loaded with the primary action and resource, with an important consequence. Every word earns its place—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 simple archive operation with two well-described parameters, no output schema, and annotations covering idempotency and destructiveness, the description is complete. It conveys the essential outcome and scope sufficiently without needing more detail.

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 journey_id having clear descriptions. The tool description adds no additional parameter-specific meaning, 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 the action (Archive) and the resource (journey-scoped notification template), using a specific verb and distinguishing it from siblings like archive_notification or archive_journey by the 'journey-scoped' qualifier. It also conveys the key consequence (cannot be sent), making the purpose unambiguous.

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

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

The description provides clear context by specifying 'journey-scoped notification template', which implies this is for templates owned by a journey, differentiating it from global templates. However, it does not explicitly mention alternative tools or when not to use it, falling 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context, such as what archiving entails (e.g., soft delete, irreversibility, permissions). It does not contradict the annotations, but it also does not enrich 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?

One sentence, front-loaded with the action and object. No wasted words or redundant information. It is appropriately concise for a one-parameter tool.

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

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

Given the tool's simplicity and the availability of annotations, the description is mostly complete. It clearly indicates the action and parameter. However, it doesn't mention the outcome or return value, which could be useful but is mitigated by the absence of an output schema and the straightforward nature of the action.

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 parameter notification_id is described as 'The notification template ID to archive'. The description's 'by ID' reinforces this but adds no new meaning beyond the schema parameter 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 'Archive a notification template by ID' clearly identifies the action (archive), the resource type (notification template), and the method (by ID). It distinguishes itself from sibling tools like archive_journey and archive_journey_template by specifying 'notification template'.

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

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

The description implies use when archiving a notification template by ID, but provides no explicit context, exclusions, or alternatives. It does not mention when to prefer this over delete_notification or other archive tools, leaving usage largely 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 destructiveHint and idempotentHint, so the description adds value by disclosing the 409 failure mode for non-empty sections and the required sequence. It does not explain the post-archive state, but the key operational constraint is covered.

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

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

Two sentences, zero filler. The action is stated first, followed by the critical precondition and failure consequence. Highly efficient.

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

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

For a single-parameter destructive operation with helpful annotations, the description covers the unique behavior (409 on non-empty) and the necessary prerequisite. It could be more complete by explaining archival consequences, but it's sufficient for an agent to invoke 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 already describes the single parameter 'section_id' (100% coverage), so the description need not repeat it. The description provides no additional parameter-level meaning, but it's not required; baseline 3 is appropriate.

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

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

The description clearly states the action ('Archive a preference section') with a specific verb and resource. It distinguishes from sibling tools like archive_preference_topic by targeting sections, and the precondition about topics further clarifies 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 provides explicit when-to-use context: a section must be empty before archiving, with a direct instruction to delete topics first. It does not name alternatives, but the precondition effectively says 'do not use this unless topics are removed', which is sufficient for this simple tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context: it does not explain whether archiving is reversible, what happens to the topic after archival, or if any side effects occur. It simply restates the action implied by the tool name.

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

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

The entire description is a single short sentence, 'Archive a topic within a section.' It is front-loaded, contains no filler, and every word contributes to the meaning. This is an appropriately concise description for a simple operation.

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

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

Given the tool's simplicity (2 parameters, no nested objects, no output schema), the description is minimally viable. However, it leaves out meaningful context: what does 'archive' do? Is it reversible? What is the returned result? Although annotations cover safety (destructive, idempotent), the absence of any explanation of the archival process or its effects makes the description slightly incomplete.

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 both parameters with clear descriptions ('Id of the subscription preference topic to archive' and 'Id of the preference section'), giving 100% coverage. The description's phrase 'within a section' reinforces the relationship between the two parameters, but it adds no new information beyond what the schema already provides. 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 'Archive a topic within a section' uses a specific verb and resource, clearly distinguishing it from sibling tools like archive_preference_section (which archives a whole section) and delete_user_preference_topic (which deletes a topic). It precisely conveys the scope: a topic nested inside a section.

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. It does not mention any prerequisites, context, or exclusions. Given the presence of similar archive tools (e.g., archive_preference_section) and deletion tools, the agent receives no hints about the appropriate selection criteria.

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 safety profile is known. The description adds valuable scope by stating the operation affects 'all its associated messages', which is critical for a destructive action. It does not mention reversibility or other side effects, 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?

The description is a single, front-loaded sentence with no redundant words. It states the verb first and includes only the essential information: action, resource, and parameter.

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 and no output schema, the description is largely complete. It covers the action, the resource, and the scope. Minor gaps include ambiguity around whether archiving is reversible or what the response looks like, but these are not critical given the simple scope.

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

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

Schema description coverage is 100%; the parameter request_id is described as 'The request ID (requestId returned from /send)'. The tool description only says 'by request ID', which adds no new semantics beyond the schema. Baseline 3 is appropriate when the schema fully documents the parameter.

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

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

The description clearly specifies the action ('Archive'), the resource ('a send request'), and the scope ('all its associated messages'), keyed by 'request ID'. This distinguishes it from sibling tools like archive_journey or archive_notification, which target different resources.

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

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

The description implies usage when one needs to archive a send request, but provides no explicit guidance on when to use this vs alternatives like cancel_message or delete_* tools. It does not name any alternative or exclusion, so the guidance is only implicit from the clear resource type.

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 idempotentHint and destructiveHint, so the baseline is lower. The description adds behavioral context beyond annotations by stating the prerequisite about notification templates, which is not inferable from the annotations or schema. This extra constraint is valuable.

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

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

The description is two sentences long. The first states the purpose, the second gives a critical precondition. There is no redundant information and the key information is front-loaded, 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 one-parameter operation, the description covers the tool's purpose, the prerequisite, and the annotations handle destructive/idempotent behavior. It does not explain what 'archive' means in terms of reversibility, but given the low complexity and annotations, it is reasonably 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 has 100% description coverage for the single parameter, with a clear description of what routing_strategy_id is. The tool description adds no additional parameter meaning, but since the schema already fully documents it, the baseline of 3 is appropriate.

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

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

The description opens with 'Archive a routing strategy', using a specific verb and the exact resource type. This clearly distinguishes it from sibling tools like archive_journey or archive_notification, 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 a clear conditional requirement: the strategy must not have associated notification templates, and instructs to unlink them before archiving. This gives practical usage context and an exclusion, but it does not explicitly mention alternatives or when to use archiving versus other operations (e.g., delete), so it's slightly less explicit than the highest bar.

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 idempotentHint=true and readOnlyHint=false, which the description respects. The description adds the behavioral nuance that a custom profile can be supplied per tenant, but it does not disclose behavior around existing associations or partial failures. This is acceptable given the annotation coverage.

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. It immediately states the action, the resource, the multiplicity, and a key capability. 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?

The tool performs a bulk mutation with nested object parameters and no output schema. The description covers the core function and profile capability, but omits details like error behavior on partial failures or handling of existing memberships. The idempotentHint annotation helps, but the description could still be richer about the bulk semantics.

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

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

Schema coverage is 100%, with both 'user_id' and 'tenants' already documented in the schema. The description's mention of 'custom profile' adds marginal meaning ('custom profile' = tenant-scoped overrides) but does not substantially elevate understanding beyond the schema.

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

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

The description uses a specific verb ('Add') and resource ('user to multiple tenants'), clearly distinguishing this bulk operation from the sibling tool 'add_user_to_tenant'. It also mentions the custom profile feature, which is essential to 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 phrase 'at once' implies this is for bulk operations, distinguishing it from single-tenant tools like 'add_user_to_tenant'. However, it does not explicitly name alternatives or state when not to use this tool (e.g., if you need to add to a single tenant).

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 (readOnlyHint false, idempotentHint false) indicate a mutating, non-idempotent operation. The description adds crucial behavior with 'Overwrites matching existing tokens,' which goes beyond the schema and annotations. It does not contradict annotations and provides useful context, though it omits details on effects on non-matching tokens or response format.

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

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

Two sentences, front-loaded with the primary action and resource, zero filler words. 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 absence of an output schema and the moderate complexity (array of token objects with nested device metadata), the description covers the core behavior but lacks details on what 'matching' means (token string vs provider_key) and prerequisites (e.g., existing user). Overall, it is adequate for an agent to understand the tool's basic function.

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

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

The input schema has 100% description coverage for both user_id and tokens, including nested device and expiry fields. The description adds no additional meaning beyond the schema, so a 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 the action ('Add'), the resource ('multiple push/device tokens for a user'), and the scope ('in one request'). It also differentiates from sibling tools like bulk_add_user_tenants (different resource) and create_or_replace_user_push_token (single vs multiple tokens).

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 'in one request' implies a bulk-use case, and 'overwrites matching existing tokens' sets expectations for upsert behavior. However, it does not explicitly name alternatives or state when not to use this tool, nor mention prerequisites like user existence.

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 key behavioral traits beyond annotations: it explains the destructive effect (resetting omitted overrides to defaults), the special case of an empty array (clearing all overrides), and validation atomicity. These details are not present in the annotations (idempotentHint and destructiveHint) and provide crucial execution-time expectations.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds meaningful information (scope, reset behavior, empty array, atomicity). No filler or redundancy.

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

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

Given the tool's complexity (destructive, atomic, full-replacement semantics), the description is complete. It covers the mutation outcome, edge cases, and atomicity. There is no output schema, so return values are not expected to be explained. The sibling tools exist but do not need explicit cross-references for the description to be contextually complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the array's semantics (complete set, empty array clears) but these are already described in the schema's topics parameter description. It adds no new parameter-level detail beyond what the schema already provides, so it stays 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 uses the specific verb 'Replace' and clearly states the resource ('a user's complete set of preference overrides in one request'). It distinguishes from sibling tools like bulk_update_user_preferences by emphasizing 'complete set' and 'every existing override not included is reset', making its scoped 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 clearly implies when to use this tool: when you need to replace an entire set of overrides atomically, with explicit behavior for missing items and empty arrays. However, it does not explicitly name alternatives or exclusions, so it falls short of the 'explicit alternatives' level but provides clear contextual usage.

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

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

Annotations already indicate mutation (readOnlyHint: false) and idempotency (idempotentHint: true). The description adds the 'replace all' semantics, clarifying the scope of change (entire list membership) beyond what annotations provide. It doesn't explicitly state that current subscribers are removed, but 'Replace' conveys this.

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

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

The description is a single clear sentence, front-loaded with the verb 'Replace', with no unnecessary words 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 simple two-parameter tool with full schema coverage and annotations, the description is complete. It clearly conveys the operation's effect and is sufficient for an agent to invoke it correctly. No output schema is present, so return values need not be described.

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

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

Schema coverage is 100% with both parameters (list_id and recipients) described. The description adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Replace all subscribers on a list with the given recipients.' It uses a specific verb ('Replace') and resource ('all subscribers on a list'), and the word 'Replace' distinguishes it from sibling add_subscribers_to_list which adds without replacing.

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 via 'Replace' (overwrite entire list membership) but does not explicitly mention alternatives or when not to use this tool. It could have said 'Use this to set the full list; to incrementally add subscribers, use add_subscribers_to_list.'

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), the description discloses important behavioral details: only body topics are modified, existing overrides remain untouched, and partial-success handling with items/errors return. This exceeds what annotations provide.

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

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

Three concise sentences, front-loaded with the primary action and scope. Every sentence adds value without fluff or repetition.

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

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

For a mutation tool with no output schema, the description compensates by mentioning the return structure (items/errors). It adequately covers the core behavior, though it could add a note about 'unapplicable' topics or tenant scoping, but these are not critical gaps given the schema.

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

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

The schema already documents all parameters with descriptions (100% coverage), so the baseline is 3. The description adds semantic value by explaining the array behavior for 'topics' (additive, only those topics affected), which is not fully captured in the schema.

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

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

The description clearly states the action ('Additively create or update'), the resource ('user's preferences for one or more topics'), and the scope ('in a single request'). It also distinguishes from bulk replacement by emphasizing that only specified topics are touched, leaving existing overrides intact.

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 usage context by highlighting the additive nature and partial-update behavior. It implies when to use this tool (for partial updates) versus alternatives like bulk_replace_user_preferences, though it doesn't explicitly name the alternative or state exclusions.

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

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

The description discloses a notable behavioral side effect: 'This invokes a second ad-hoc automation with a single cancel step,' which goes beyond the idempotentHint annotation. It also clarifies the exact spelling requirement, adding useful context beyond the schema.

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

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

The description is three sentences, each serving a purpose: action, side effect, and token requirement with spelling note. It is front-loaded and wastes no words.

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

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

For a single-parameter tool with no output schema, the description covers the core behavior, the side effect, and the condition for success. It doesn't address failure cases or return values, but given the tool's simplicity, it is sufficiently complete.

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

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

Schema coverage is 100%, so the parameter is fully documented. The description reinforces the token requirement but largely repeats the schema's meaning, adding only a minor clarification about matching the original token.

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 'Cancel a running automation by its cancelation_token,' clearly specifying the action (cancel), resource (automation), and method (by token). It also distinguishes 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?

It provides clear context for use: the token must match the cancelation_token from the original automation start. It doesn't explicitly state when not to use it or mention alternatives, but the token requirement and automation-specific scope imply appropriate usage.

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

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

Annotations already indicate idempotent and destructive hints, but the description adds meaningful context: canceled or finished runs are left unchanged, and the token cancels multiple runs. This goes beyond the structured 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 concise sentences, front-loaded with 'Cancel journey runs', and every phrase adds necessary information. No waste 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 two-parameter destructive tool with no output schema, the description fully explains behavior, idempotency effect, and parameter usage. It is complete and self-sufficient.

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

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

Schema already covers 100% of parameters, with descriptions and mutual exclusivity. The description adds the 'exactly one' rule and clarifies the semantic difference between token and run_id, providing extra value.

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

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

The description clearly states the tool cancels journey runs, a specific verb and resource. It distinguishes from sibling tools like cancel_automation and cancel_message by focusing on journeys.

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 instructs to supply exactly one of the two parameters and explains the effect of each. It also notes idempotency, though it doesn't contrast with alternatives; context is clear enough.

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

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

Annotations already declare idempotentHint and destructiveHint. The description adds that cancellation applies to messages 'currently being delivered' and returns 'message details with updated status', which is useful behavioral context beyond the annotations. 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 a single concise sentence that front-loads the action and includes the return behavior. Every word earns its place, with 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 simple one-parameter tool with no output schema, the description explains what action is taken and what is returned. It could mention edge cases such as what happens if the message is no longer being delivered, but the core usage is clearly covered.

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

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

The schema covers 100% of the single parameter with its own description ('The message ID to cancel'). The tool description adds no additional parameter-specific semantics, so the baseline score of 3 applies due to 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 states 'Cancel a message that is currently being delivered' with a specific verb and resource. It distinguishes itself from sibling tools like cancel_notification_submission by targeting messages in delivery, and notes the return of updated message details.

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' provides clear context for when this tool should be used, implying it is not for messages that have already been sent. However, it doesn't explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

The description aligns with the annotations (destructiveHint: true, idempotentHint: true) by using 'Cancel', but it does not add any behavioral context beyond the annotations. It does not describe consequences, reversibility, or any edge cases, though the annotations already cover the 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?

The description is a single, concise sentence that is front-loaded with the action. Every word adds value, and there is no fluff or redundancy.

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

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

The tool is simple with two clearly described parameters and annotations, but the description lacks context about what a 'notification template submission' is, when it can be cancelled, or what the outcome will be. This is acceptable for a simple tool but leaves some gaps in understanding for an agent.

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

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

Schema description coverage is 100% for both parameters (submission_id and notification_id), and the schema provides clear descriptions. The tool description adds no additional parameter semantics, 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 the action ('Cancel') and the resource ('a notification template submission'), using a specific verb that distinguishes it from sibling tools like cancel_message or cancel_journey. It is unambiguous about what the tool does.

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

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

No guidance is provided on when to use this tool versus alternatives such as cancel_message or cancel_journey. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage solely from the name and description.

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?

With annotations providing readOnlyHint=true, the description adds valuable behavioral context by disclosing that the tool also generates a sample JWT for client-side SDKs. This is beyond the basic annotation and informs the agent of an additional output. It does not contradict the read-only hint, and provides enough transparency for a tool of this simplicity.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes the key secondary behavior (JWT generation) in a compact addendum. Every sentence contributes value, and there is no redundant information.

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

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

For a simple tool with 2 parameters, no output schema, and a read-only annotation, the description covers the essential purpose and the notable special behavior. It doesn't explain the details of the sample JWT (e.g., who it is for, expiration), which could be a minor gap, but overall the description is sufficiently complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%: both 'platform' and 'user_id' have detailed descriptions in the schema. The tool description adds no new semantic information about the parameters; it only reiterates the distinction for client-side SDKs, which the schema already states. Thus the baseline of 3 is appropriate, as the description does not need to compensate.

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

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

The description clearly states the tool's function: 'Get the Courier SDK installation guide for a specific platform.' It specifies the resource (Courier SDK installation guide), the action (get), and the scope (specific platform). It also distinguishes itself from siblings by noting that for client-side SDKs it additionally generates a sample JWT, which sets it apart from tools like generate_jwt_for_user.

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 on when to use the tool: for any SDK installation guide, and specifically for client-side SDKs with JWT generation. However, it does not explicitly mention alternatives (e.g., 'if you only need a JWT, use generate_jwt_for_user instead'), so it falls short of a 5. The context is clear with no exclusions, meriting a 4.

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

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

The description adds behavioral details: claims the API requires settings and returns a 400 if omitted, then says omitting settings uses defaults. This contradicts the schema, which marks settings optional and describes a default. The default color behavior is useful, but the contradictory claim undermines transparency. Annotations only indicate readOnlyHint=false and idempotentHint=false, which don't cover this.

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, but the second sentence about settings being required is misleading and unnecessary, detracting from the otherwise concise purpose and example. It could be tightened to two clear 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?

With four parameters, nested objects, and no output schema, the description only covers a subset of parameter meaning via example and gives contradictory guidance about requiredness. It does not describe return values or idempotency, though annotations cover the latter. Overall, it's incomplete for the tool's complexity.

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

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

Schema covers all parameters with descriptions (100%), so the baseline is 3. The description provides an example for name and settings.colors, but incorrectly states settings is required, which misleads about its optionality. It does not discuss id, snippets, or email/inapp settings, but the schema handles these.

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 brand,' a specific verb+resource that clearly distinguishes it from sibling tools like update_brand, get_brand, list_brands, and delete_brand. The purpose is unambiguous despite later confusing statements.

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

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

The description implies usage for creating new brands but does not explicitly state when to prefer it over update_brand for existing brands. It provides context about settings omission/defaults, though the 'requires settings' statement creates confusion about when settings should be 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 indicate the operation is not read-only and not idempotent. The description adds context that creating a bulk job alone does not send messages—subsequent steps are required. However, it omits details like authentication, return value, or error handling.

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

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

Two concise sentences with no unnecessary words. The purpose is stated first, followed by the workflow, making the description well-structured and front-loaded.

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

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

For a single-parameter creation tool with no output schema, the description provides essential context via the workflow and clearly states the tool's function. It could mention the returned job ID, but that is implied by the workflow and not 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?

The schema provides a description for the only parameter ('message'), and the tool description doesn't add additional detail about the message structure. Since schema description coverage is 100%, 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 ('bulk job') and clarifies the tool's role in sending messages to multiple recipients. The workflow line further distinguishes it from sibling 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 explicit workflow 'create_bulk_job → add_bulk_users → run_bulk_job' provides clear context for when to use this tool as the first step in a multi-step process. It doesn't mention exclusions or alternatives, but the workflow itself acts as a strong guideline.

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

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

The description adds significant behavioral context beyond the annotations: it explains the default DRAFT state, the restriction on send nodes, that node ids are server-generated and must not be included, and includes an example payload. Since annotations only provide readOnlyHint=false and idempotentHint=false, the description carries the burden and does so thoroughly.

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

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

The description is compact yet information-dense. Every sentence serves a purpose: stating the action, the default state, the restriction and follow-up tools, the id rule, and a stripped-down example. No filler or repetition, and critical details are front-loaded.

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

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

Given the moderate tool complexity, no output schema, and minimal annotations, the description covers the essential workflow and constraints. It might be improved by hinting at the response (e.g., returning the created journey with id), but the provided next-step guidance and example make the tool actionable. A small gap remains, so 4 rather than 5.

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

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

The schema covers 100% of parameters, so baseline is 3. The description adds value by providing a concrete example of the nodes array structure, clarifying that send nodes are disallowed at creation, and reinforcing the server-generated id behavior. This goes beyond simple schema repetition, earning a 4.

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

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

The description opens with 'Create a new journey,' clearly identifying the verb and resource. It distinguishes from sibling tools by explicitly referencing replace_journey and publish_journey, and by stating what this tool does (create shell with trigger node) versus what they do (add sends, make live).

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

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

The description provides explicit guidance: 'Send nodes are not allowed on create — create the shell with a trigger node, then call replace_journey to add send nodes after linking notification templates. Call publish_journey to make it live.' This directly tells the agent when to use this tool and which alternatives to use for subsequent steps.

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 readOnly=false and idempotent=false, which are minimal. The description adds meaningful behavioral context: defaults to DRAFT, accepts PUBLISHED to publish immediately, and can be referenced in send nodes. This goes beyond the annotations but does not fully disclose all behaviors (e.g., validation, error handling), so a 4 is appropriate.

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 sized, opening with purpose, then default/publish behavior, a use case, and a helpful example. The example is long but earned its place, as it demonstrates the complex nested structure without unnecessary verbosity.

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

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

Given the tool has 5 parameters, nested objects, and no output schema, the description covers core concepts but misses some important details. It does not mention return values, failure modes, or the provider_key parameter, leaving some gaps for an agent to infer. The example helps but incomplete context around expected outcomes lowers the score to 3.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds a concrete example showing the nested notification object structure, including nullable brand/subscription and content elements. This extra example clarifies parameter semantics beyond the schema, justifying a 4.

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

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

The description clearly states the tool creates a notification template scoped to a journey, using a specific verb and resource. It distinguishes from siblings like create_notification (which is not journey-scoped) and create_journey (which creates the journey itself).

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

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

The description provides context for when to use this tool, noting templates can be referenced in journey send nodes. It also explains the default DRAFT state and how to publish on create, but does not explicitly list exclusions or alternatives, hence a 4 rather than 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 declare readOnlyHint=false and idempotentHint=true, which covers the write and retry-safety profile. The description adds the upsert-like behavior ('Create or update') that aligns with idempotency, but provides no extra detail about permissions, side effects, or handling of existing lists.

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, making it highly concise and scannable.

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 upsert with only two parameters, complete schema descriptions, and annotations indicating write/idempotent behavior, the description is adequate. It could mention what happens on create vs update (e.g., name overwritten), but the existing coverage is sufficient for basic selection.

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

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

Schema coverage is 100% with clear descriptions for both parameters ('Display name for the list' and 'The list ID'). The description's 'by list ID' reinforces list_id as the key but adds no meaningful 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 'Create or update a list by list ID' clearly identifies the action (create/update) and resource (list), and the 'by list ID' qualifier distinguishes it from list read/delete siblings. However, combining 'create or update' into one verb is less precise than a single-action tool.

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

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

The description implies usage for creating or updating a list by ID, but provides no explicit when-to-use guidance or alternatives. It does not mention that get_list is for reading or delete_list for removal, so the context is only inferred.

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 and idempotentHint=false, so this is a non-idempotent write operation. The description adds behavioral context by stating that a template cannot be sent until published (unless state is PUBLISHED) and that content can be set after creation, which goes beyond the basic write indication. It does not contradict the annotations, and the disclosure is helpful for anticipating workflow implications.

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

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

The description is compact yet dense: three sentences plus a minimal JSON example. It front-loads the primary action, then addresses requirements, alternatives, and workflow constraints in a logical order. No filler or repetition is present.

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

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

Given the complexity of creating a notification template and the absence of an output schema, the description covers all essential input aspects: required fields, content alternatives, publishing prerequisite, and routing configuration. It does not describe return values, but with no output schema and ample guidance on the input side, this is a minor gap.

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

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

Even though schema coverage is 100%, the description adds substantial meaning beyond the raw schema: it explains that 'content' can be provided inline or later, 'routing.strategy_id' controls channels, and 'state' can be set to PUBLISHED for immediate sending. The included example ties all parameters together, making the input structure concrete and easier to construct correctly.

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 V2 notification template,' which is a specific verb+resource statement that clearly distinguishes this from sibling operations like put_notification_content (content modification) and publish_notification (state change). It also clarifies that 'name is required,' reinforcing the exact 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 explicitly maps out the usage workflow: content can be provided inline or set later via put_notification_content, and the template must be published before sending unless state:'PUBLISHED' is passed on creation. It also names publishing as a prerequisite and routing strategy as a configuration step, providing clear alternatives and when-to-use guidance.

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

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

Annotations already indicate non-read-only and idempotent behavior. The description adds meaningful context about the merge semantics—specifically that existing fields not included are preserved—which goes beyond the structured annotations. There is 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?

The description is a single, concise sentence that front-loads the purpose and includes key behavioral information. No unnecessary words or repetitive 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 simple upsert tool, the description adequately covers core behavior and preservation semantics. It lacks return value information (no output schema exists), but the essential functionality is clearly conveyed. Slightly more detail about the response or use cases would improve it, but it is complete enough for an AI agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both user_id and profile. The description itself does not add additional parameter-level detail beyond what the schema already provides, so it relies on the schema for parameter semantics.

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

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

The description clearly states the tool's function: create a new user profile or merge into an existing one. It uses specific verbs ('create', 'merge') and names the resource ('user profile'), and distinguishes from siblings like replace_profile by emphasizing merge and preservation.

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 context: use this tool when you want to upsert profile data and preserve any existing fields not supplied. It does not explicitly name alternatives or exclusions, but the merge behavior with preservation provides clear context for when it 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?

Annotations already declare readOnlyHint=false and idempotentHint=true. The description only says 'create or replace' and does not add behavioral details like overwriting existing tokens, uniqueness constraints, or authentication requirements. No contradiction, but no value beyond annotations.

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

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

The description is a single front-loaded sentence that states the verb and object without unnecessary words. It is 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?

Despite 4 parameters and a nested device object, the description omits important context such as whether existing tokens are replaced per provider, how the device metadata is used, and what a successful operation returns. The absence of an output schema makes the minimal description less complete.

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

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

Schema description coverage is 100%, with descriptions for token, device, user_id, and provider_key. The tool description adds no parameter-specific meaning, so the baseline of 3 applies; the schema already documents the parameters.

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

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

The description uses a specific verb pair 'Create or replace' targeting the resource 'push/device token' for a user. It clearly distinguishes from sibling tools like delete_user_token and list_user_push_tokens by naming both create and replace behavior.

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

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

No guidance is provided on when to use this tool versus alternatives such as patch_user_token or bulk_add_user_tokens. The description lacks context about preferred scenarios or exclusions, so the agent receives no usage direction.

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

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

The description merely restates the operation ('create or replace') which is already conveyed by the tool name and idempotentHint annotation. It does not disclose what happens to existing tenant data during a replace (e.g., whether omitted fields are cleared, merged, or preserved), leaving important behavioral ambiguity.

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 fluff. Every word contributes to understanding the core action, making it highly efficient.

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

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

Given the tool has 7 parameters, nested objects, upsert semantics, and no output schema, the description is too sparse. It does not mention return values, how 'replace' handles field omissions, or the meaning of nested objects beyond the schema's brief descriptions, leaving the agent with insufficient context for correct invocation.

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

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

All 7 parameters have schema descriptions, providing high coverage. The tool description adds no parameter-level details, but since the schema already documents each parameter, the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb ('Create or replace') and resource ('tenant'), making the tool's purpose unambiguous. It distinguishes from read-only tools like get_tenant or list_tenants by indicating an upsert operation.

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

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

The description provides minimal context by defining what a tenant is, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. The usage is implied by the tool name and description, but no explicit guidance is given.

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

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

Annotations indicate the tool is not read-only and not idempotent, but the description adds valuable context: 'The section id is generated and returned.' This discloses that the API generates the identifier and that the response includes it. It also implies the creation is a mutating, one-time action consistent with the annotations. No contradiction exists.

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

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

The description is two short sentences that immediately state the main action, then provide the generated ID behavior and the next step. There is zero waste, and the structure is front-loaded with the core purpose.

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

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

For a simple create operation with no output schema, the description sufficiently covers the key return value ('section id') and the recommended follow-up action. It does not explain the full response structure, but the absence of an output schema makes the ID disclosure the most critical detail. The description is complete enough for an agent to invoke the tool correctly.

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

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

The input schema has 100% description coverage for all parameters. The description does not repeat parameter details, which is appropriate since the schema already provides semantics for name, routing_options, and has_custom_routing. However, it adds no additional meaning beyond the schema, so it earns the baseline score for high coverage.

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

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

The description clearly states the tool's action: 'Create a preference section in your workspace.' It also distinguishes itself from the sibling tool by mentioning 'Add topics afterwards with create_preference_topic.' The detail that 'the section id is generated and returned' further clarifies the tool's purpose and behavior.

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

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

The description provides clear usage context by indicating this tool is the first step in creating a preference section, followed by adding topics with create_preference_topic. It implies when to use this tool (initial creation) but does not explicitly mention when not to use alternatives like replace_preference_section. This is sufficient for basic guidance.

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

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

Annotations only indicate readOnlyHint=false and idempotentHint=false. The description adds valuable behavioral details: the topic id is generated and returned, and a 404 error occurs if the section does not exist. This goes beyond the minimal annotation info.

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

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

Two concise sentences front-load the core action, then cover return value and error behavior. No extraneous words or redundancy with schema/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?

With 7 parameters and no output schema, the description covers the essential operation, return, and error case. It does not mention optional parameter behavior, but the schema fills those gaps, making it complete enough for this simple 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%, so parameters are fully documented. The description adds no extra parameter-level meaning beyond the schema, which is consistent with the baseline of 3.

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

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

The description clearly states a specific verb ('Create'), resource ('subscription preference topic'), and scope ('inside a section'). It also distinguishes from sibling tools like create_preference_section by clarifying the parent-child relationship.

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

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

The description explicitly notes that the section must already exist (404 if not), implying the correct prerequisite. It provides clear context for when to use this tool, though it does not explicitly name alternatives 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?

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description discloses a significant behavioral consequence: configurations can be referenced by routing strategies or notification templates, so mistakes can affect live sends. This adds valuable risk context that annotations alone do not provide.

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

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

The description is three sentences long, front-loaded with the primary purpose, and every sentence earns its place. The warnings are concise and directly relevant to safe usage, with no redundant or extraneous content.

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

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

For a create tool with an object parameter and no output schema, the description provides sufficient context: what it does, a required validation step, and a risk warning. It does not mention return values, but this is not critical for successful invocation given the schema fully documents parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a constraint that the provider field must be a known Courier provider key, but the schema already says 'Provider key from the catalog,' making this only a minor reinforcement. No additional meaning is added for alias, title, or settings 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 opens with 'Create a new provider (integration) configuration'—a specific verb and resource that clearly distinguishes this from sibling tools like update_provider and list_providers. The mention of 'new' and 'create' makes the tool's purpose unambiguous.

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

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

The description provides clear contextual guidance: it tells the agent to confirm provider key and settings against list_provider_catalog before saving, and warns that mistakes can affect live sends. It does not explicitly contrast with update_provider, but the 'new' phrasing and the creation context imply the appropriate use case.

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 and idempotentHint=false, which align with the mutating 'Create' action. The description doesn't add contextual details such as uniqueness requirements, validation, or return behavior, but the annotations lower the bar and no contradiction exists.

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

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

The description is a single, concise sentence that front-loads the action and resource. No unnecessary words or repetition.

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

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

The tool has a nested routing object and six parameters, but the schema covers these well. However, with no output schema, the description does not clarify what the tool returns or whether it requires existing channels/providers. This makes it 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%, with each property including a description. The tool description adds a high-level purpose but no additional parameter-specific details. Thus, it meets the baseline without exceeding it.

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

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

The description uses a specific verb 'Create' and identifies the resource as 'routing strategy' with clear scope: defining how notifications are delivered across channels and providers. It is distinct from sibling tools like replace_routing_strategy or archive_routing_strategy, as it focuses solely on creation.

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 explicit guidance is provided on when to use this tool versus alternatives such as replace_routing_strategy or when prerequisites (e.g., existing channels/providers) must be met. The description only states what the tool does, not the context for its use.

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

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

The description adds no behavioral context beyond the annotations. The destructiveHint and idempotentHint annotations already communicate the safety profile; the description merely restates the operation without disclosing consequences like permanence or cascading deletions.

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 of six words, directly stating the action and target. 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 one-parameter delete tool, the description, combined with the annotations, adequately conveys the operation and its destructive nature. However, it does not mention any return value or side effects, though the simplicity and annotations partially compensate.

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 covers audience_id with a clear description and 100% coverage, so the tool description adds no additional parameter meaning. The phrase 'by its ID' mirrors the schema's parameter 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 uses a specific verb 'Delete' with a clear resource 'audience' and identifies the targeting mechanism 'by its ID'. This distinguishes it from sibling delete tools like delete_brand and delete_list.

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

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

The description provides no guidance on when to use this tool versus alternatives such as update_audience or get_audience. There are no exclusions or context clues about prerequisites or circumstances.

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 and idempotentHint, but the description adds no additional behavioral context such as permanence, cascading effects, or error behavior. The phrase 'by its ID' merely restates the parameter rather than revealing any new behavioral trait.

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 redundant words. It is appropriately terse for a simple one-parameter delete operation, though it omits some contextual details that could be expected.

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 tool with a single parameter and annotations indicating destructiveness and idempotency, the description is minimally viable. However, it does not explain expected side effects or return behavior, so it falls short of fully complete contextual guidance.

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

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

Schema coverage is 100% with a descriptive parameter definition ('The brand ID to delete'). The description's 'by its ID' adds no meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Delete') on a specific resource ('a brand') with the required scope ('by its ID'). It is unambiguous and easily distinguished from sibling delete tools for other entities like delete_tenant or delete_list.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no distinction from other deletion or archiving operations. It only implies usage for deleting a brand, which is already evident 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?

The annotations already disclose that the operation is destructive and idempotent. The description adds no extra context (e.g., whether deletion is permanent, effect on subscribers, or reversibility), and merely restates the parameter use from 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 a single, focused sentence with no redundant words or filler. It is front-loaded with the verb and resource, making it 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 destructive operation, the description is extremely sparse. It does not explain consequences such as permanent deletion, impact on associated data, or any preconditions. The presence of a restore_list sibling hints at data recovery potential, but this is not addressed.

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

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

The input schema already fully describes the single required parameter 'list_id' with 100% coverage. The description's phrase 'by its ID' adds no semantic insight beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (delete) and the resource (a list) identified by ID. It distinguishes this tool from siblings like create_list, get_list, and list_lists, making the 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?

No guidance is provided about when to use this tool versus alternatives such as delete_audience or when to prefer restore_list. The usage is merely implied by the action itself, with no context 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 already declare destructiveHint and idempotentHint. The description adds 'permanently', reinforcing irreversibility but not exceeding what the annotations imply. It does not disclose effects on related data or any auth requirements, but for a simple delete with annotation coverage, 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?

The description is a single clear sentence with no redundant words. Every word earns its place, conveying the action, resource, and permanence efficiently.

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

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

For a single-parameter delete tool with strong annotations, the description is sufficient. It lacks details on return value or error behavior, but the simplicity and clarity make it reasonably complete.

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

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

Schema coverage is 100%, and the parameter description 'The user ID to delete' is self-explanatory. The description does not add extra parameter meaning, 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'), names a clear resource ('user profile'), and adds 'permanently' to emphasize irreversibility. This distinguishes it from sibling tools like delete_audience or delete_list and makes 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 clear context that this is the permanent deletion tool for user profiles. It does not explicitly mention alternatives or when-not-to-use, but the verb 'Delete' and resource 'user profile' are enough to convey primary usage.

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

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

Beyond the annotations (destructiveHint, idempotentHint), the description discloses a specific behavioral trait: the operation returns 409 if the provider is still referenced by routing or notifications, signaling a dependency check. Other behaviors like success response or reversibility are not detailed, but the key destructive constraint is captured.

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

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

The description is two short, front-loaded sentences with zero waste: the first states the core action, the second adds a critical conflict condition. 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 delete with annotations, the description covers the core action and the most important behavioral constraint (409 when referenced). It omits success-response details, but given the tool's simplicity and the presence of the 409 caveat, it is sufficiently complete.

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

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

The input schema already documents the only parameter (provider_id: 'The provider configuration ID to delete') with 100% coverage. The description adds no additional parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the action ('Delete') and the resource ('provider configuration'), which distinguishes it from sibling tools like create_provider, update_provider, get_provider, and list_providers. The added 409-on-referenced detail further specifies the tool's operational 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 implies when to use the tool (to remove a provider configuration) and the 409 note implies a precondition: references must be removed first. However, it does not explicitly state when not to use it or name alternatives (e.g., update_provider for modifications).

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 no behavioral context beyond the annotations. Annotations already convey destructive and idempotent hints, but the description omits details about permanence, cascading effects, or required permissions.

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 superfluous words. It is concise and structured effectively.

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 delete operation, the description plus annotations provide sufficient context for selection and invocation. However, it does not mention return values or irreversibility beyond the annotations, 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?

With 100% schema description coverage, the baseline is 3. The description adds no new parameter 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 'Delete a tenant by its ID' uses a specific verb and resource, clearly distinguishing it from sibling delete_* tools. It unambiguously states what the tool does.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It only implies usage by its name and phrasing.

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. Description adds the scope (default notification preference for a topic from a tenant) but does not disclose side effects, irreversibility, or authorization requirements. 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?

Single sentence, front-loaded with verb and object, no superfluous content.

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

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

For a simple delete operation with complete schema and annotations, the description adequately explains the purpose. It could mention side effects but overall sufficient for selection and 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% with descriptions for both tenant_id and topic_id. The tool description adds no additional 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?

Description uses specific verb 'Remove' and resource 'default notification preference for a topic from a tenant', clearly distinguishing from sibling tools like update_tenant_preference and delete_user_preference_topic.

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

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

Usage is implied by the verb and resource, but no explicit guidance on when to use this over alternatives or prerequisites. It doesn't exclude user-level preferences or mention that this is tenant-level only.

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

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

Beyond the destructiveHint=true annotation, the description adds concrete behavioral details: it returns 204 on success and 404 if the template does not exist for the tenant. This clarifies expected outcomes and scoping, which is not present in the annotations.

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

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

The description is a single, focused sentence followed by status codes. Every word adds value, and the most important action is stated first. No filler or redundancy.

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

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

For a simple delete operation, the description covers the primary success and error cases adequately. It does not mention irreversibility or side effects on related resources, but given the simplicity and the presence of destructiveHint, the information is reasonably complete. No output schema exists, so status codes are the key returned data.

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

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

The input schema provides complete descriptions for both parameters (tenant_id and template_id), achieving 100% coverage. The tool description adds no additional parameter information, so the baseline score of 3 is appropriate since 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 action: 'Delete a tenant notification template' – a clear verb+resource combination. It distinguishes itself from sibling tools like delete_tenant, archive_journey_template, and replace_tenant_template by targeting the exact resource.

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

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

No guidance is given on when to use this tool versus alternatives (e.g., archive vs delete, or replace). There are no prerequisites, exclusions, or explicit contexts. The only implicit signal is the delete verb, but the description does not help the agent decide between similar 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?

The description confirms the destructive action, aligning with the destructiveHint=true annotation. It adds no additional behavioral context beyond the literal action, but the annotations already signal the key traits.

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

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

One concise sentence that front-loads the verb and resource, with no wasted words.

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

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

For a simple single-parameter delete operation, the description and annotations provide sufficient context. The lack of an output schema is acceptable, as delete operations typically return nothing.

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 the single parameter user_id, and the description adds no extra semantic value beyond restating it as 'for a user.' With schema coverage at 100%, this is adequate.

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 clearly identifies the resource 'all list subscriptions for a user,' distinguishing it from sibling tools like get_user_list_subscriptions 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 description doesn't explicitly state when to use this tool versus alternatives like unsubscribe_user_from_list, though the scope is clear from 'all list subscriptions.' It lacks explicit exclusion or alternative guidance.

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

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

Annotations provide idempotentHint=true and destructiveHint=true. The description adds valuable context by explaining exactly what happens: the user's preference is removed and the topic falls back to its default status. This goes beyond the annotation flags and clarifies the postcondition.

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, tightly worded sentence that starts with the action verb and includes the essential resource and outcome. No filler or redundant information is present.

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

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

For a simple two-parameter mutation with annotations for idempotency and destructiveness, the description covers the core semantics. It does not describe return values or error conditions, but the lack of an output schema and low complexity make this acceptable.

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

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

Schema description coverage is 100% for both parameters (user_id and topic_id), providing clear definitions. The description adds no additional parameter meaning, but since the schema fully explains them, 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 the specific verb 'Delete' and names the exact resource: 'a user's preference for a specific subscription topic.' It also clarifies the semantic effect ('reverting it to the topic's default status'), which distinguishes it from update_user_preference_topic 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 when to use it by stating the effect (revert to default), but it does not explicitly compare with alternatives like update_user_preference_topic or provide exclusion criteria. The usage context is clear but not fully defined.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description simply states 'Delete' without adding extra behavioral context such as reversibility, error handling, or side effects. It does not contradict annotations but also does not add value 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?

A single 7-word sentence that is perfectly concise and front-loaded. No redundant information 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 simple delete operation with only two required parameters and no output schema, the description plus schema fully covers the necessary information. The low complexity and clear parameter details make this complete.

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

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

Schema coverage is 100% with both parameters described ('The user ID' and 'The token identifier to delete'). The tool description does not add additional meaning beyond the schema, which is sufficient for this simple case. Baseline of 3 applies.

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

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

The description uses a specific verb ('Delete'), resource ('push token'), and scope ('for a user'), clearly distinguishing it from sibling tools like patch_user_token or create_or_replace_user_push_token. It unambiguously names the operation and target.

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. There is no mention of prerequisites, alternatives, or scenarios where this should be used, leaving the agent to infer from the name and siblings 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?

With annotations only declaring readOnlyHint=false and idempotentHint=false, the description carries the burden of explaining side effects. It mentions 'Generate' implying a write action, but does not clarify whether the token is persisted server-side, any required permissions, or rate limits. The safety profile is partly conveyed by annotations, but behavioral details are sparse.

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 redundant phrasing. It front-loads the primary function and then adds a brief use-case note, making it both concise and informative.

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 generation tool with no output schema, the description covers the core purpose and intended context. However, it does not explicitly state the return value (the JWT string), which would be helpful since there is no output schema to clarify this.

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

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

Schema coverage is 100%, with each parameter having a description. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Generate a JWT authentication token') and the resource ('for a user'), making the tool's purpose immediately obvious. It also specifies the use case ('client-side SDK auth (Inbox, Preferences, etc.)'), which helps distinguish it from sibling tools like push token or user token management.

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

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

The description provides clear context for when to use the tool ('client-side SDK auth') and implicitly suggests it is for authentication tokens rather than other token types. It lacks explicit exclusion of alternatives, but given the absence of direct siblings, this is acceptable.

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

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

The readOnlyHint annotation already marks the operation as read-only, and the description adds context about the return value ('including its filter definition'), which goes beyond the annotation. No other behavioral traits are disclosed, but for a simple read operation this is sufficient.

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 action and includes the important detail about filter definition. No unnecessary words or repetition.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete enough: it states what it does, how it identifies the audience, and what the response includes. The read-only annotation covers safety aspects.

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 fully describes audience_id as 'The audience ID', and the description reinforces this with 'by its ID' without adding new meaning. With 100% schema description coverage, the description adds minimal value beyond the schema.

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

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

The description clearly states the tool gets an audience by ID, using the specific verb 'Get' with a specific resource and identifier. It also notes the return includes the filter definition, which distinguishes it from list_audiences and other sibling tools.

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

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

The description implies usage when you have an audience ID and need the full audience object. It does not explicitly mention alternatives like list_audiences, but the context is clear and unambiguous for a simple getter.

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

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

The readOnlyHint annotation marks the operation as read-only, and the description's 'Get' is consistent. The description adds no extra details about return format, permissions, or error behavior, but for a simple getter with annotation coverage this is minimal but acceptable.

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?

Single sentence, direct, and front-loaded with the verb and resource. There is no filler, and every word contributes to the meaning.

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, the description is sufficiently complete to understand the tool's purpose. There is no output schema, but the lack of return-format detail is unlikely to block correct invocation. It could mention the relationship to list_audit_events, but this is not 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 description coverage is 100%, with audit_event_id fully described. The description's 'by its ID' adds no semantic detail beyond the schema. Parameter semantics are fully handled by the schema.

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

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

The description clearly states the action ('Get'), the resource ('specific audit event'), and the selection criterion ('by its ID'). This distinguishes it from list_audit_events and other get_* 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 need for an audit_event_id implies the tool is for fetching a single audit event when the ID is already known. It does not explicitly mention alternatives like list_audit_events for discovering IDs, but the scope is clear and no exclusions are stated.

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

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

The description aligns with the readOnlyHint annotation ('Get' is a read operation) and contains no contradiction. However, it adds no behavioral context beyond the annotation—no mention of what is returned, not-found behavior, or any edge cases. With annotations already covering the safety profile, the description provides minimal extra transparency.

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

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

A single, direct sentence communicates the entire purpose. There is no redundancy or filler, making it an appropriate model of conciseness for a simple retrieval tool.

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

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

For a low-complexity tool with one parameter, a readOnlyHint, and no output schema, the description is functionally sufficient to select and invoke correctly. It lacks details like return value shape or error handling, but those are not strictly necessary for a simple ID-based getter.

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 brand_id parameter already carries a basic description in the schema. The description's 'by its ID' reinforces that the parameter identifies the brand but adds no new semantic detail such as format, constraints, or potential values. Baseline 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 'Get a brand by its ID' uses a specific verb ('Get') and resource ('brand') with a clear identifier qualifier. It distinguishes itself from siblings like list_brands, create_brand, update_brand, and delete_brand by specifying retrieval of a single entity 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?

No explicit guidance is given about when to use this tool versus alternatives. The phrase 'by its ID' implies this is for single-brand retrieval, but there is no mention of when not to use it or that list_brands should be used for searching. Usage is only implied, not articulated.

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 readOnlyHint=true already communicates that this is a read-only operation, and the description aligns with that by saying 'Get'. However, the description adds no further behavioral context such as whether it returns only the status or additional job details.

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

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

The description is a single, front-loaded sentence with no extraneous words. It delivers the essential information efficiently.

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

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

Given the simple nature of the tool (one required parameter, read-only annotation, no output schema), the description is nearly complete. It could mention the possible status values or response shape, but the plain description is adequate for understanding the tool's purpose and 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% for the single parameter job_id, which is already documented as 'The bulk job ID'. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Get' with the resource 'status of a bulk job', clearly distinguishing this from sibling tools like create_bulk_job, run_bulk_job, and list_bulk_users. It precisely states what the tool does.

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

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

The description implies that this tool is used to check the status of a bulk job, but it does not explicitly state when to use it instead of alternatives, such as after creating or running a bulk job. There are no exclusions or use-case context 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 readOnlyHint=true, so the read-only nature is known. The description adds useful behavioral details by explaining version selection and the default to published, which goes beyond the annotation. No contradiction.

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

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

Two concise sentences front-load the main action and provide necessary version detail without waste. 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 get-by-id tool with one optional parameter, the description is complete enough. It omits return format details, but no output schema exists and the operation is straightforward; the provided information suffices.

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 already documents both parameters with 100% coverage. The description adds value by clarifying version='draft'/'vN' semantics and the default behavior, enriching the 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?

Clearly states the function: 'Get a journey by ID' with specific verb+resource. Distinguishes from sibling tools like list_journeys by emphasizing retrieval of a single journey and mentioning version variants.

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 version usage guidance ('Pass version=draft...') but does not explicitly contrast with alternatives or state when not to use this tool. The context implies it is for fetching specific journeys, yet exclusions/alternatives are absent.

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?

With readOnlyHint=true already annotating the safe read operation, the description adds valuable behavioral context about version handling: the draft version is required before publication, and the default is published. This goes beyond the annotation without contradiction.

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

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

The description is two concise sentences, front-loads the core purpose, and every word adds value. There is no fluff 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 simple read-only getter with 3 parameters and no output schema, the description covers the key complexity (version behavior). It does not describe return format, but the tool is straightforward and the annotations already indicate it is read-only. Slight gap on alternative usage, but overall adequate.

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

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

Schema coverage is 100%, providing the baseline of 3. The description enhances the 'version' parameter by explaining when to use draft vs published, which is not fully captured in the schema. It adds semantic nuance about publication status, elevating it above 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 clearly states the tool retrieves a journey-scoped notification template by notification ID, which is a specific verb+resource combination. It also distinguishes from siblings like get_journey_template_content or get_notification by emphasizing 'journey-scoped' and 'template'.

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

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

It provides clear context on when to use version=draft (required before publication) and indicates the default is published. However, it does not explicitly compare to alternatives like get_journey_template_content or get_notification, so it lacks explicit exclusion 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 adds version behavior (defaults to published, draft/historical selection) beyond the readOnlyHint annotation, which is helpful. It does not contradict the annotation and gives useful context about what the tool returns for different version inputs.

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, front-loaded with the core purpose, followed by precise version guidance. No wasted words; every phrase contributes to understanding the tool's behavior.

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 fetch operation with read-only annotation and well-documented schema, the description covers purpose, version semantics, and default behavior. It could mention what 'elemental content' includes or response format, but the absence is not critical given the clear tool name and 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 already documents all parameters (100% coverage), so baseline is 3. The description adds meaningful nuance to the 'version' parameter by explaining the exact semantics of 'draft', 'vN', and the published default, which the schema description states more cryptically.

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

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

The description uses the specific verb 'Fetch' and identifies the resource as 'elemental content of a journey-scoped notification template', which clearly distinguishes it from sibling tools like get_notification_content or get_journey_template. The scope is 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?

Provides clear usage context for version selection (draft, historical vN, or default published), which is direct and actionable. It does not explicitly name alternative tools or exclusion criteria, but the 'journey-scoped' qualifier implies when this tool is appropriate versus non-journey content fetchers.

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

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

The readOnlyHint annotation already declares this as a read-only operation, and the description's 'Get' verb aligns. No additional behavioral context (e.g., error handling, return format) is provided, but given the annotation, the safety profile 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?

The description is a single concise sentence that communicates the essential purpose without any wasted words.

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

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

For a simple get-by-ID tool with full schema coverage and a safety annotation, the description is sufficient. It lacks a note about sibling operations or return details, but the core usage is clear and unambiguous.

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 list_id is fully described in the schema with 100% coverage. The description adds no extra meaning beyond what the schema already provides, which is acceptable given high schema coverage.

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

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

The description clearly states the operation (get) and resource (list) with the required ID parameter. It is distinct from sibling tools like list_lists (which lists all lists) and get_list_subscribers (which retrieves subscribers).

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

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

The description implies usage when a specific list ID is known, but provides no explicit guidance on when to use this versus alternatives such as list_lists or restore_list. It lacks exclusions or alternative tool hints.

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 readOnlyHint=true already communicates that this is a safe read operation, and the description is consistent with this. However, the description adds no extra behavioral context (e.g., pagination behavior via cursor, possible empty results, or ordering). It merely restates the tool's name, so it provides minimal added transparency beyond the annotation.

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

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

The description is a single concise sentence ('Get all subscribers of a list.') with no filler, redundancy, or irrelevant details. It is appropriately sized for the simplicity of the tool.

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

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

The tool is simple: two parameters, one required, no output schema, and a read-only annotation. The description adequately states the core function, and the schema covers parameters. The only minor gap is that it doesn't explicitly mention pagination, but that is inferred from the cursor parameter. Given the low complexity, the description is sufficiently complete.

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

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

Schema coverage is 100%, with both parameters (list_id and cursor) described. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Get all subscribers of a list.' It clearly indicates the operation and the target resource, distinguishing it from sibling tools 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?

The description implies usage (use when you need all subscribers of a given list) but does not explicitly mention alternatives or exclusions. No guidance is given about when to use this versus list_audience_members or get_user_list_subscriptions, so it relies on the name for context.

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

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

Annotations declare readOnlyHint=true, and the description aligns by using 'Get'. It adds useful context about return scope ('full details and status'), which goes beyond the annotation. 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?

A single, front-loaded sentence that conveys purpose and key qualifier without waste.

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

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

For a simple single-ID retrieval tool with no output schema, the description adequately conveys what is returned ('full details and status'). It is complete for the tool's complexity.

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

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

The schema covers 100% of parameter semantics with 'The message ID to retrieve'. The description's 'by its ID' adds no new 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 clearly states the verb (Get), resource (message), and scope (full details and status, by ID). This distinguishes it from sibling tools like get_message_content (content only) and get_message_history (history).

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 implies the primary use case: retrieving a single message by ID. It doesn't explicitly name alternatives or exclusions, but the context is clear enough that an agent would know when to choose this over list_messages or get_message_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?

The readOnlyHint annotation already indicates a safe read operation. The description adds that content is 'rendered' and limited to 'previously sent' messages, which is useful scoping, but does not disclose error behavior, authentication needs, or rate limits. 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 a single sentence that is direct and informative, with no filler or redundant information. It efficiently conveys the purpose and scope.

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 getter with one required parameter and no output schema, the description sufficiently indicates the return contents (HTML, text, subject). It lacks details on return structure or edge cases, but these are not critical for a tool of this complexity.

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

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

The schema has 100% coverage with a basic description for message_id. The tool description adds the context that the ID refers to a previously sent message, which provides some semantic value beyond the schema, but does not explain the format or how to obtain the ID.

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

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

The description clearly states the specific verb 'Get' and the resource being retrieved: 'rendered content (HTML, text, subject) of a previously sent message'. This distinguishes it from related tools like get_message (metadata) and get_message_history (history).

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

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

The phrase 'previously sent message' implies this tool is for sent messages rather than drafts, but it does not explicitly name alternatives like get_message for metadata or when not to use this tool. Usage context is implied 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 include readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it shows each step in the delivery pipeline, clarifying the nature of the returned data. However, it does not disclose details like ordering, timestamp inclusion, or pagination, which is a minor gap beyond the annotation.

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

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

The description is a single, well-structured sentence that front-loads the core action ('Get the event history for a message') and immediately clarifies the output with examples. No unnecessary words or content.

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

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

Given the tool's simplicity (2 params, no output schema) and the presence of readOnlyHint and complete schema descriptions, the description sufficiently covers the tool's purpose and expected return content. The delivery pipeline examples provide enough context for an agent to understand what this tool returns.

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 message_id and type have descriptive text. The description adds no parameter-level information, but the schema already provides the necessary meaning. Baseline 3 is appropriate given the complete schema coverage.

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

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

The description clearly states the tool retrieves the event history for a message, with specific examples of delivery pipeline steps (enqueued, sent, delivered). The verb 'Get' and resource 'event history for a message' are specific, and it is readily distinguishable from sibling tools like get_message or list_messages.

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

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

The description implies usage for inspecting the delivery pipeline of a message but does not explicitly state when to use this tool versus alternatives or provide exclusions. It gives context (showing each step) but lacks explicit guidance on choosing it over related message 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 annotation already declares readOnlyHint=true, covering safety. The description's versioning detail ('draft, published, or a version such as v001') is already present in the schema's version parameter description, so the description adds no new behavioral context such as default behavior, response format, or side effects.

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

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

Two concise sentences, front-loaded with the main action, no filler words. Every sentence contributes to understanding the tool's purpose and option.

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 with a clear purpose and full schema coverage. However, no output schema exists, and the description does not mention default behavior (e.g., what happens if version is omitted) or the return format, leaving some gaps. 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%, so the schema already documents both parameters. The description restates the version parameter's possible values without adding new meaning. Baseline 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 clearly states the action and resource: 'Retrieve a notification template by ID.' It also distinguishes from sibling tools like get_notification_content and get_notification_draft_content by mentioning optional draft/published/version retrieval, making the scope specific.

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

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

The description provides clear context for when to use the tool (retrieving a specific notification template by ID, optionally with a version). It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous and the optional versioning adds clarity.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds the distinction between published and draft content but does not disclose what a 'content block' consists of, return format, or any potential edge cases. Given the annotation covers safety, 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 a single, focused sentence with no filler or redundancy. It immediately conveys the tool's action and object, earning full marks for conciseness.

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

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

For a simple read-only getter with one parameter, the description is nearly complete. It clarifies the 'published' aspect, which is a key contextual distinction. The absence of an output schema is somewhat mitigated by the tool's simplicity, though more detail on 'content blocks' would improve completeness.

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

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

The input schema already provides 100% coverage for the single parameter ('notification_id' described as 'The notification template ID'). The description adds no further detail about the parameter, so it meets the baseline without enhancing understanding.

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

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

The description clearly states the tool retrieves 'published content blocks' of a notification template, using a specific verb and resource. The term 'published' distinguishes it from the sibling get_notification_draft_content, making its 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 provides clear context by specifying 'published content blocks', implying this is for published templates and that a draft variant exists. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full explicit 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 readOnlyHint annotation already informs the agent this is a safe read operation. The description adds minimal context beyond the tool name ('draft (unpublished)'), but does not describe any additional behavioral aspects such as return format, pagination, or auth requirements. With annotations covering the safety profile, 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 a single, clearly worded sentence that immediately conveys the tool's purpose without unnecessary words or repetition. It is perfectly 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?

This is a simple one-parameter read tool with a clear name, useful annotation (readOnlyHint), and complete schema. The description clarifies the 'draft' aspect, and while there is no output schema, the meaning of 'content blocks' is self-explanatory. The tool is adequately specified for its complexity.

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

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

The schema provides a full description for the single parameter ('The notification template ID'), achieving 100% schema description coverage. The description adds no extra parameter semantics beyond what the schema already states, 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 uses a specific verb 'Get' and identifies the resource as 'draft (unpublished) content blocks of a notification template', clearly distinguishing it from the sibling tool get_notification_content which likely retrieves published content. The intent is unambiguous.

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

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

The description provides clear context that this tool is for draft/unpublished content, implying it should be used when draft content is needed instead of published content. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a full 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 declare readOnlyHint: true, so the safety profile is known. The description adds that the response includes topics, which is beyond the schema, but it does not disclose other behaviors such as error conditions, pagination, or whether topics are returned inline. With annotations lowering the burden, 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 one concise sentence, front-loaded with the verb and resource, and contains no fluff. It fully conveys the tool's purpose in minimal words.

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

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

For a simple read-only getter with a single parameter, the description is complete. It covers the action, resource, identifier, and expected content (including topics). No output schema is given, but the description suffices 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?

The schema already provides 100% coverage for the single parameter, including its description ('Id of the preference section'). The tool description does not add further meaning, so the baseline of 3 applies.

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

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

The description clearly specifies the verb 'Retrieve', the resource 'preference section', and the identifier-based access ('by id'), while adding that topics are included. This differentiates it from siblings like list_preference_sections (which lists all) and get_preference_topic (which retrieves a single topic).

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

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

The description implies usage when you have a specific section_id and need the section with its topics. There is no explicit exclusion of alternatives, but the 'by id' phrasing gives clear context. While it does not name sibling tools, it is sufficient for a simple getter in the presence of many 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?

The readOnlyHint annotation already signals a safe read operation. The description adds valuable context by specifying the 404 behavior and the requirement that the topic must belong to the given section, which is a meaningful validation detail. It does not cover auth or rate limits, but for a simple read tool this is sufficient.

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 that fronts the core purpose and then adds a concise clarification about the 404 condition. No wasted words, and it is immediately scannable.

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

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

For a simple retrieval tool, the description covers the key behavioral nuance (section-topic relationship and error case) and the parameters are fully documented in the schema. Since there is no output schema, the description does not need to detail return values, and the 404 condition gives sufficient context for an agent to anticipate failure modes.

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 topic_id and section_id having clear descriptions in the schema itself. The tool description adds no further parameter semantics, so the baseline score of 3 is appropriate given the schema already handles parameter explanation.

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 ('Retrieve a topic within a section') and the resource (topic within a preference section). It distinguishes from sibling tools like get_user_preference_topic (which retrieves by user) and list_preference_topics (which lists topics) by emphasizing the section context. The 404 condition also clarifies the expected 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 implies usage by indicating this tool retrieves a specific topic using both section_id and topic_id. However, it does not explicitly state when to use this over alternatives such as list_preference_topics or get_user_preference_topic. No exclusions or alternative conditions are provided.

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