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

Annotations already cover safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds meaningful behavior beyond that: duplicate adds fail with 409 (case-insensitive), and the ownership requirement for the domain argument. This is real value beyond the annotations.

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

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

Three tightly packed sentences: purpose first, then the error condition, then the ownership constraint. Every sentence earns its place with no redundancy.

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

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

For a mutation tool with no output schema, the description adequately covers effect, failure mode (409), and the key prerequisite. Return payload details are not described, but the critical behavior for correct invocation is present.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema (including the wildcard example). The description adds only the domain-ownership constraint, which is useful but marginal against a fully documented schema. Baseline 3 applies.

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

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

States a specific verb (Adds) and resource (sender email/wildcard pattern to the blacklist) plus the effect scope ('always treated as spam on every domain'), which cleanly distinguishes it from add_spam_whitelist_entry and the other spam siblings. An agent knows exactly what this tool does without opening the schema.

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

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

Gives clear usage context: removes ambiguity about which list is being modified and clarifies the domain-ownership prerequisite plus the account-wide scope. It does not explicitly name sibling alternatives (e.g. add_spam_whitelist_entry) or state when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond them: a 409 conflict when the entry already exists, case-insensitive duplicate matching, and the account-wide blast radius of the change. It stops short of 5 because nothing is said about rate limits or the success response.

Agents need to know what a tool does to the 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 tight sentences: what it does and its scope, then the error/duplicate behavior, then the domain-vs-list constraint. No filler, and the highest-value information (effect and scope) is front-loaded.

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

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

For a two-parameter mutation with full schema coverage and annotations carrying the safety profile, the description covers effect, duplicate handling, precondition, and scope. It could still say what a success returns or when the whitelist takes effect, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description resolves the non-obvious ambiguity between the required 'domain' (must be owned) and the account-wide scope of the list itself, plus restates that 'entry' accepts wildcard patterns. That is real added meaning over the schema text.

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

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

States a specific verb (adds) and resource (spam whitelist entry) plus the concrete effect: sender mail bypasses spam filtering account-wide. The verb+noun naming plus the sibling set (add/remove/list whitelist vs. blacklist) makes it trivially distinguishable from remove_spam_whitelist_entry and add_spam_blacklist_entry.

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

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

Gives clear context (account-wide whitelist affecting every domain) and a real prerequisite: the domain argument must be a domain you own even though the list is account-wide. It never explicitly names an alternative or a when-not-to-use case, so it stops short of a 5.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true) by disclosing the 422 failure mode for unknown packages, the 403 refusal for non-reseller accounts, and a configuration prerequisite. The return value ('Returns the updated user') is also stated, which matters because no output schema 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?

Three short sentences, front-loaded with the action, then error behavior, then eligibility constraints. Every sentence carries actionable information and there is no filler.

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

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

With no output schema and full annotation coverage, the description fills all remaining gaps an agent needs: what it does, failure codes, eligibility restrictions, environment caveat, and the return value. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters carry inline descriptions with examples ('premium', 'johndoe'), so the schema does the heavy lifting. The description adds no parameter-level meaning such as whether the package name must pre-exist or whether assignment replaces or supplements the current package. 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?

States a specific verb and resource: 'Assigns a different package to a user,' which is clearly distinguishable from update_reseller_user, suspend_reseller_user, and the package CRUD tools. It doesn't explicitly contrast itself with the closest sibling (update_reseller_user), so it falls just short of the 5 bar for sibling differentiation.

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

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

Provides a clear precondition ('Reseller accounts only') and an explicit exclusion ('regular accounts are refused, typically with 403'), plus an environment-level restriction on MXROUTE_USERNAME form. It stops short of naming what an agent should do instead for regular accounts, so no true alternative routing is given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: the external DNS precondition and the 409 rejection path, which is consistent with idempotentHint=false. It does not mention auth/permission requirements or what a successful call returns.

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

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

Three short sentences, each doing distinct work: what it does, the precondition with the helper tool, and the duplicate error. The purpose is front-loaded and there is no filler.

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

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

For a single-parameter mutation tool with no output schema, the description covers the operational essentials an agent needs: the external DNS prerequisite and the duplicate-domain failure mode, while annotations cover the safety profile. Missing only secondary details such as permission requirements and the success response shape.

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

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

There is a single parameter with 100% schema description coverage including a pattern, minLength, and an example.com hint, so the schema carries the semantics. The description never mentions the 'domain' argument at all, adding no meaning beyond the schema; 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?

States a specific verb and resource ('Adds a domain to the account') and immediately distinguishes itself from the read-side sibling by pointing to get_domain_verification_key for the prerequisite. An agent can tell this apart from list_domains, get_domain, and delete_domain without opening any schema.

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

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

It gives a concrete precondition (the verification TXT record must already be in DNS) and names the tool that supplies it, plus the failure condition (409 if the domain already exists), which implicitly tells the agent not to call this for existing domains. It stops short of naming alternative tools for adjacent operations such as create_domain_pointer, so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is largely covered. The description adds the alias-vs-redirect consequence of the flag, but that information is duplicated verbatim in the schema, and it says nothing about auth requirements, re-run behavior on an existing pointer, or domain-verification prerequisites.

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

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

A single sentence that front-loads the action and the target/pointer relationship, with zero filler. Nothing is padded or repeated unnecessarily.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 3-parameter, non-nested create tool with full schema coverage and no output schema, the description covers purpose, directionality, and the alias/redirect branch. Remaining gaps — error conditions and prerequisites — are modest given the low complexity and the annotations that already signal this is a non-destructive, non-idempotent, open-world write.

Complex tools with many parameters or behaviors need more documentation. 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% — every parameter already carries a description including the alias default and the pointer example. The description restates the alias semantics and the domain/pointer direction without adding syntax, format, or constraint detail beyond the schema.

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

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

The description gives a specific verb and resource ('Creates a domain pointer') and resolves the ambiguity that matters most here: which domain is the target and which one points at it. It does not name the sibling tools it must be distinguished from (delete_domain_pointer, list_domain_pointers), but the directionality statement makes the operation self-evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 only implied — an agent can infer this is the tool for establishing a pointer, and the alias=true/false clause hints at a choice to make. There is no explicit when-to-use or when-not-to-use guidance, nor any pointer to list_domain_pointers as the inspection alternative.

Agents often have multiple tools that could apply. Explicit usage 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 the write/non-destructive/openWorld/idempotent profile, but the description adds genuinely useful context beyond them: the password is transmitted to MXroute and never surfaced in the result, plus concrete defaults for quota and daily send limit when fields are omitted. It stops short of noting that the password is unrecoverable afterward or what the result contains.

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

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

Three short sentences, front-loaded with the action, then the critical password behavior, then the defaults. No filler and nothing important buried at the end.

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

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

For a mutation tool whose annotations cover the safety profile and whose schema is fully described, the description is nearly complete, and it even clarifies output behavior (password withheld). It leaves out prerequisites such as an existing domain and any authentication context, which openWorldHint implies but does not spell out.

Complex tools with many parameters or behaviors need more documentation. 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 five parameters are already documented, including the 1024 MB and 9600 defaults. The description's defaults sentence largely repeats what the schema descriptions already state, so it adds little beyond the baseline.

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

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

States a specific verb+resource ('Creates a mailbox') and clarifies the resulting identifier format with `username@domain`. It's clearly distinguishable from delete/get/list email account siblings, though it never explicitly names an alternative like update_email_account or create_forwarder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 only implied by the verb: use this when you want a new mailbox. There is no explicit when-to-use/when-not guidance, no prerequisite note (e.g., domain must already exist), and no pointer to a sibling for related 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?

Beyond the annotations (which only declare readOnly=false, idempotent=false, destructive=false, openWorld=true), the description discloses substantive behavior: `:blackhole:` silently discards mail, `:fail:` rejects it, and forwarding to Yahoo/AOL/Gmail automatically enables Expert Spam Filtering for the domain. These non-obvious side effects and special-value semantics are exactly what an agent cannot learn from annotations or 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?

A single dense sentence, front-loaded with the core action, followed by the special-value semantics and the side effect. Every clause carries information, though the semicolon-heavy packing makes it slightly harder to scan than two or three shorter sentences.

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

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

For a 3-required-param creation tool with no output schema, the description covers the action, the special destinations, and a notable side effect. It omits return/failure behavior (e.g., what happens if the alias already exists), which is a minor gap given the annotation set already flags non-idempotence.

Complex tools with many parameters or behaviors need more documentation. 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, but the description adds real meaning: it shows how `alias` and `domain` combine into `alias@domain`, and explains what the `:blackhole:` and `:fail:` destination values actually do, which the schema only lists by name.

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

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

The description names a specific verb (creates), the exact resource (`alias@domain` forwarder), and the destinations it routes mail to. It is immediately distinguishable from siblings like create_email_account or create_domain_pointer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one procedural caution (confirm with the user before using `:blackhole:`) but never states when to choose this tool over alternatives such as create_email_account or set_catch_all, nor any precondition beyond the confirm step. Usage is implied rather than explicitly scoped.

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

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

Goes well beyond the annotations by disclosing default values applied to omitted limits, the auth/account requirement with the concrete 403 failure mode, and an environment-level availability restriction. It does not say what is returned or what happens on a duplicate name, which matters given idempotentHint=false.

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

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

Two sentences, no filler, with the core action front-loaded and the constraints packed tightly behind it. Every clause carries an actionable fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 6-parameter mutation tool with full schema coverage and annotation-covered safety profile, the description supplies defaults, auth scope, and availability caveats. The remaining gap is return/duplicate behavior, which is not covered by an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by supplying the defaults that the schema entirely omits (quota 1 GB, 1 domain, 100 mailboxes, 100 forwarders, 10 domain pointers). That is real added meaning an agent cannot get from the schema.

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

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

States a specific verb and resource ("Creates a package") that maps cleanly onto the create_package name and separates it from list_packages/get_package/update_package/delete_package siblings. The reseller-only qualifier further narrows it, though the description never explains what a 'package' contains beyond the limit fields.

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

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

Explicitly scopes the caller: reseller accounts only, regular accounts refused with a 403, and unavailable while MXROUTE_USERNAME is in `reseller|user` form. That is strong when-to-use/when-it-fails guidance, but no alternative is named (e.g., pointing to update_package for later changes).

Agents often have multiple tools that could apply. Explicit usage 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower, yet the description still adds non-obvious behavior: the password is sent to MXroute and never returned, plus the 403 refusal and config-based availability constraint. It leaves permission/ownership nuances unstated, so not a full 5.

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

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

Three tightly packed sentences: purpose first, then the password behavior, then the eligibility constraints. No filler, nothing repeated from the schema.

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

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

No output schema exists, but the description explains the meaningful result characteristic (password never shown). Combined with full schema coverage and annotations, an agent has everything needed to call this 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%, so all four parameters (email, package, password, username) are already documented with patterns and lengths. The description adds no syntax or format detail beyond referencing an existing package, so the baseline 3 is appropriate.

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

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

States a specific verb ('Creates') and resource ('new user account under the reseller'), and pins the scope to reseller accounts with a required existing package. This clearly separates it from create_email_account and create_package-style siblings.

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

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

Explicit when-not guidance: regular accounts are refused (403) and the tool is unavailable while MXROUTE_USERNAME is in `reseller|user` form. Also points to list_packages for the required package, giving the agent both preconditions and a routing hint.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is given. The description still earns credit by disclosing irreversibility and, crucially, the cascade onto mailboxes and forwarders — blast radius that the annotations alone do not convey. It stays vague on exactly what happens to those child objects.

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

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

Two short clauses with the irreversible nature front-loaded and the safety instruction last. No filler, nothing repeated from the title or annotations.

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

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

For a single-parameter destructive tool with rich annotations and no output schema, this covers what an agent needs: what it destroys, that it cannot be undone, and the confirmation duty. The one soft spot is 'affected' — whether mailboxes and forwarders are deleted or merely detached is left to inference.

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

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

Only one parameter and schema description coverage is 100% (the schema documents the domain name with an example and a pattern), so the schema carries the load. The description adds no format or constraint detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Permanently removes a domain from the account') and adds scope ('mailboxes and forwarders under the domain are affected'), which distinguishes it from sibling deletes like delete_domain_pointer, delete_email_account, and delete_forwarder. An agent can pick the right tool without opening other schemas.

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

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

Gives an explicit gating condition: 'Destructive: confirm with the user before calling', which tells the agent how to behave before invoking. It stops short of naming alternatives (e.g. removing only a pointer vs. the whole domain), so it is clear context without full alternative routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so 'Destructive:' largely restates structured data. The description does add real value with the actionable workflow 'confirm with the user before calling,' but says nothing about side effects, reversibility, or what happens on a missing pointer.

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

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

Two short sentences, front-loaded with the operation and followed immediately by the safety instruction. The 'Destructive:' label duplicates the annotation, which is slight waste, but nothing is bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, fully documented destructive mutation with rich annotations, the description covers the essentials plus the confirmation requirement. It omits prerequisites and post-deletion effects (e.g., what happens to mail routed via that pointer), which would be the natural remaining gaps.

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

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

Schema description coverage is 100% and both parameters carry clear descriptions ('the target domain the pointer points at', 'the pointer domain to remove, e.g. alias.com'). The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Removes a domain pointer from a domain'), which is distinct from the sibling delete_domain (which removes an entire domain) and from list_domain_pointers / create_domain_pointer. It does not explicitly name those siblings to route the agent, so it falls short of a 5.

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

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

There is no guidance on when to use this versus delete_domain or how it relates to the pointer lifecycle (e.g., whether the pointer must exist first). The only instruction is a confirmation protocol, which is behavioral rather than selection 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 carry destructiveHint=true and idempotentHint=true, so the description's 'Destructive' label is partly redundant. It still earns credit for disclosing what is actually destroyed (the mailbox plus its stored mail) and for mandating user confirmation, neither of which the annotation block conveys.

Agents need to know what a tool does to the 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 irreversible/destructive nature is front-loaded before the confirmation instruction, so the highest-severity fact lands first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 both parameters documented in a 100%-coverage schema, annotations covering the safety profile, and no output schema to explain, the description is sufficient to call correctly. It omits minor operational detail (e.g. what happens to forwarders or aliases bound to the mailbox) but nothing blocking.

Complex tools with many parameters or behaviors need more documentation. 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 both 'domain' and 'username' are already fully documented, including the 'part before the @' clarification. The description adds no syntax, format, or constraint detail 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?

States a specific verb+resource ('Permanently deletes a mailbox') and clarifies the blast radius ('and the mail stored in it'), which cleanly separates it from the sibling delete_domain. The '(irreversible)' qualifier removes any ambiguity about permanence.

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

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

Gives an explicit precondition for invocation: 'Destructive: confirm with the user before calling.' That is a real when-to-use directive, not boilerplate. It stops short of naming alternatives or exclusions (e.g. preferring suspension), so it falls just below the top band.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine context beyond that: the concrete effect that mail to the address stops being forwarded, plus an operational requirement (user confirmation) that the annotations do not encode. Return/error behavior is not described, keeping it out of 5 territory.

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

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

Three short sentences, zero filler, with the action stated first and the destructive-confirmation warning last. Every sentence carries distinct information.

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

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

For a two-parameter destructive tool with full schema coverage, rich annotations, and no output schema, the description covers purpose, effect, and the safety precondition. The only minor gap is what happens on a non-existent forwarder (the idempotentHint implies success), which the annotation largely addresses.

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

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

Schema description coverage is 100% and both parameters (domain, alias) carry their own descriptions and patterns, so the schema fully documents inputs. The description adds nothing parameter-specific, which matches the baseline of 3 when 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?

States a specific verb and resource ('Deletes an email forwarder') and immediately adds the consequence of the action. It is trivially distinguishable from siblings like create_forwarder and list_forwarders, which an agent can select between without opening any schema.

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

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

Gives an explicit invocation condition: 'Destructive: confirm with the user before calling.' That is meaningful when-to-use guidance for a destructive operation. It does not name alternatives or state when-not-to-call, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds concrete failure semantics (422 when users are still assigned, 403 for non-reseller accounts) and an environment-configuration blocker (MXROUTE_USERNAME form). It also spells out the required human confirmation, which annotations cannot convey.

Agents need to know what a tool does to the 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 tight sentences: the action and its main failure mode come first, then eligibility constraints, then the safety instruction. No filler or repetition of the title.

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

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

For a single-parameter destructive tool with no output schema, the description covers the destructive nature, precondition failures, account-type eligibility, and environment gating. An agent has everything needed to decide whether calling is safe and legal.

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

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

Only one parameter exists and schema description coverage is 100%, with the schema documenting the name pattern and allowed characters. The description adds no format, syntax, or naming guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Deletes a package') and immediately adds the 422 precondition when users remain assigned. The 'package' resource cleanly distinguishes it from the other delete_* siblings such as delete_domain, delete_email_account, and delete_forwarder.

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

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

Gives explicit when-not conditions: reseller accounts only, regular accounts refused (403), and unavailable while MXROUTE_USERNAME is in `reseller|user` form, plus a 'confirm before calling' instruction. No alternative tool (e.g., update_package) is named for modifying rather than removing a package, so it falls just short of a 5.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description goes well beyond them: it enumerates what is destroyed (domains, mailboxes, mail), states irreversibility, discloses the 403 failure mode for regular accounts and the environment-variable precondition, and mandates confirmation. That is exactly the extra behavioral context annotations cannot carry.

Agents need to know what a tool does to the 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 dense sentences, front-loaded with the destructive consequence and scope, then eligibility, then the confirmation instruction. No filler and nothing buried.

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

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

One required parameter, no output schema, and safety flags already in annotations. The description covers the remaining unknowns an agent needs — cascade damage, irreversibility, auth eligibility, and the refusal error — so nothing material is missing.

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

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

Schema coverage is 100% and the single `username` parameter is documented in the schema with an example, so the baseline applies. The description adds no per-parameter meaning beyond the environment-form caveat, which is auth context rather than 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?

Specific verb+resource ('Permanently deletes a user account') with the exact cascade scope spelled out: domains, mailboxes, mail. It also distinguishes itself from the sibling deletes by restricting itself to reseller accounts, so an agent can differentiate it from delete_domain or delete_email_account without opening the schema.

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

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

Explicit preconditions and exclusions: reseller accounts only, regular accounts refused with 403, and unavailable when MXROUTE_USERNAME is in `reseller|user` form. It also instructs confirmation before calling. It stops short of naming a reversible alternative (e.g. suspend_reseller_user) for callers who don't want destruction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful behavioral context by enumerating the return semantics (fail, blackhole, address), but says nothing about auth requirements, error behavior for unknown domains, or account scoping.

Agents need to know what a tool does to the 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 states what is returned and the possible values, with zero redundant or filler text. Every clause earns its place.

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

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

For a one-parameter read-only getter with full schema coverage and annotations covering the safety profile, the description is nearly sufficient, and the enumeration of return values effectively compensates for the absence of an output schema. Only edge behavior (invalid/unknown domain, account scoping) is unstated.

Complex tools with many parameters or behaviors need more documentation. 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 domain parameter is documented in the schema with a pattern and example (example.com). The description adds no syntax or format detail beyond 'on a domain', so the baseline 3 applies.

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

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

States a specific verb (returns) and resource (catch-all handling for a domain), and enumerates the three possible dispositions (fail, blackhole, address), so the agent knows exactly what it retrieves. It does not explicitly name its obvious mutation counterpart set_catch_all, so sibling differentiation is left to inference rather than stated.

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

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

There is no when-to-use statement, no mention of the set_catch_all sibling as the write alternative, and no stated preconditions beyond the required domain. The purpose is clear enough that usage can be guessed, but the description offers no guidance text.

Agents often have multiple tools that could apply. Explicit usage 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description reinforces it with 'it does not change DNS.' It adds real behavioral value beyond the annotations with 'DKIM (when available)', warning that the result set can be partial and the agent should not assume a DKIM record is returned.

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

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

Two tight sentences: the first front-loads what is returned, the second disambiguates the mutation risk. No filler and nothing redundant with the title.

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

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

With no output schema, the description correctly carries the burden of describing return contents and flags conditional DKIM availability. It leaves minor gaps — output format and whether records include priority/TTL values — but is otherwise sufficient for a single-parameter read tool.

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

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

There is a single required parameter and schema description coverage is 100%, so the schema already documents the domain argument with an example. The description adds nothing about the domain parameter (e.g. whether it must be an existing account domain), so baseline 3 applies.

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

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

States a specific verb and resource (returns DNS records for a domain) and enumerates the exact record types returned: MX, SPF, DKIM and the verification record. This clearly separates it from adjacent siblings such as get_domain_verification_key and get_domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'to configure at the registrar' makes the intended scenario explicit — this is the tool for domain DNS setup. It stops short of naming alternatives or exclusions (e.g. when to prefer get_domain_verification_key alone), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds what data comes back, which is useful, but says nothing about auth requirements, error behavior for nonexistent domains, 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?

One sentence, front-loaded with the verb and resource, then the returned fields. No filler, no redundancy.

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

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

There is no output schema, so the description usefully enumerates the returned fields, and the annotations carry the safety profile. It is nearly complete for a simple single-entity read; only failure modes (unknown domain) are unstated.

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

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

Schema description coverage is 100% and the single 'domain' parameter is documented with an example (example.com) and a pattern. The description adds no format or syntax detail beyond what the schema already provides, so 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 names a specific verb and resource ('Returns details for one domain') and enumerates the concrete fields returned (mail hosting status, SSL status, domain pointers). It implicitly distinguishes itself from list_domains by scoping to 'one domain', but never names the sibling explicitly.

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

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

Usage is only implied: an agent can infer this is the read tool for a single domain's configuration, contrasted against list_domains and delete_domain. There is no explicit when-to-use statement, no prerequisites, and no named alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the server cannot change DNS, the response shows the exact record, and DNS propagation typically takes 5-15 minutes.

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

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

Two sentences with zero waste. The first sentence front-loads what is returned, and the second sentence provides prerequisite and timing context. Every clause earns its place.

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

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

Given zero parameters, no output schema, and annotations that already cover the safety profile, the description provides everything an agent needs: what the tool returns, why it matters for create_domain, what the user must do with the result, and the DNS propagation delay.

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

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

The tool takes zero parameters, so per the calibration baseline this is a 4. The description adds no parameter information, but none is needed because there are no inputs to describe.

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

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

The description states a specific verb and resource: returns the account's domain verification key and the DNS TXT record that proves ownership. It also distinguishes this tool from create_domain by explaining the prerequisite relationship, so an agent can tell it apart from siblings like get_domain or get_dns_records.

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

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

Usage context is clear: the tool must be used before create_domain will work, and the user must add a TXT record and wait for propagation. It does not explicitly state when not to use it or name alternatives, but the dependency makes the intended use obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds real value by enumerating what the read returns (quota, usage, daily send limit, emails sent today, suspended state), which matters because there is no output schema; it stops short of error behavior such as a missing mailbox.

Agents need to know what a tool does to the 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 no filler; every clause names a returned field the agent needs because no output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 read-only lookup with full schema coverage, the description covers the essentials, and enumerating the response fields compensates for the absent output schema. Only failure/missing-mailbox behavior is unaddressed.

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

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

Schema coverage is 100%, and both required parameters are documented there with patterns and examples (domain 'example.com', username as the part before the @). The description adds nothing about parameter formats or how domain/username compose, so the baseline 3 applies.

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

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

States a specific verb (returns) and resource (one mailbox) plus the exact fields returned: quota, usage, daily send limit, emails sent today, suspended state. The 'one mailbox' scoping implicitly separates it from list_email_accounts, but it never names or distinguishes itself from the sibling get_email_usage, which overlaps on the 'usage' concept.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_email_accounts (bulk) or get_email_usage. The agent must infer from the singular 'one mailbox' phrasing that this is a per-mailbox lookup.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds genuinely useful behavior beyond them — the 'largest first' ordering and the hourly refresh cadence from MXroute, which tells the agent how fresh the data is. It omits pagination/response-shape 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?

Two short sentences, zero waste, with the core result stated first and the freshness caveat second. Nothing is padded or redundant.

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

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

No output schema exists, so the description must convey the return payload; it gives the unit (bytes), the coverage (every mailbox) and the sort order, which is enough to consume the result. It does not say what identifies each mailbox entry, a minor gap for a zero-parameter tool.

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

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

The tool takes no parameters, so the baseline is 4; there is no parameter surface for the description to illuminate and it correctly does not invent one.

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

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

Specific verb+resource: 'Returns disk usage in bytes for every mailbox on the account', with scope (all mailboxes, account-wide) and ordering (largest first). It does not, however, differentiate itself from the sibling get_quota, so the agent must infer which one to call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 reporting nature of the tool, but there is no explicit when-to-use versus the sibling get_quota or any stated prerequisite/permission context. Nothing misleading, but nothing that routes the agent either.

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

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

Annotations already establish readOnly/idempotent safety, and the description adds substantial context: null means unlimited, quota_unlimited flags unlimited disk quota, the 403 refusal mode for non-reseller accounts, and an environment-variable precondition. That is real behavioral disclosure beyond the structured fields.

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

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

Two dense sentences, front-loaded with the return payload before the qualifiers, and every clause carries information (null semantics, environment precondition). No filler or restatement of the title.

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

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

With no output schema, the description takes on the job of describing the return shape and does so field-by-field, plus null/unlimited semantics and the failure mode. An agent has everything needed to call it and interpret the result.

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

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

Only one parameter (name) and schema description coverage is 100%, with the pattern documented inline, so the schema fully carries parameter semantics. The description adds no naming, format, or resolution detail beyond it, which matches the baseline of 3 when 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?

States a specific verb and resource ('Returns a package's limits') and enumerates exactly what is returned: disk quota, domains, mailboxes, forwarders, domain pointers. This clearly distinguishes it from list_packages (enumeration) and get_quota (single-account quota).

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

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

Gives explicit when-not conditions: reseller accounts only, regular accounts refused (typically 403), and unavailable while MXROUTE_USERNAME is in `reseller|user` form. It never names an alternative sibling (e.g., list_packages or get_quota) for the cases it excludes, keeping it just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real value beyond them: '0 = unlimited' decodes a sentinel quota value, grace-period status is disclosed as conditional, and 'refreshed hourly by MXroute' tells the agent the data's freshness, which prevents it from treating results as real-time.

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

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

A single sentence that front-loads the primary return ('overall disk usage') and then details the fields. No filler or repetition of the title.

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

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

With no output schema, the description carries the full burden of describing return values, and it does so thoroughly — all key fields, the unlimited sentinel, category breakdown, and grace-period condition. Nothing an agent needs in order to call this zero-argument tool correctly is missing.

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

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

Zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly focuses on output content instead.

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

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

States a specific verb and resource ('Returns the account's overall disk usage') and enumerates exactly what comes back: bytes used, quota limit, percent used, category breakdown, grace-period status. The word 'overall' implicitly separates it from the per-mailbox get_email_usage sibling, but no sibling is named, so differentiation is inferred rather than stated.

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

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

There is no explicit when-to-use statement, no prerequisites, and no reference to alternatives such as get_email_usage or list_packages. Usage is only implied by the tool's name and content.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them by disclosing failure behavior (403 for non-reseller accounts) and a configuration-dependent unavailability condition tied to MXROUTE_USERNAME, which an agent cannot infer from the schema or annotations.

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

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

Two tightly packed sentences with zero filler: returned fields first, then eligibility and environment constraints. Every clause carries actionable 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 single-parameter read tool with full annotations and no output schema, the description covers return fields, error behavior, and environment preconditions. It stops short of noting behavior for a nonexistent/invalid username, which is the only notable 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?

There is a single required parameter with 100% schema description coverage, so the schema already documents the argument format ('johndoe'). The description adds no additional parameter-level detail, which is the baseline when schema coverage is complete.

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

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

The description names a specific verb ('Returns') and resource (a reseller user's record) and enumerates the exact fields returned (email, primary domain, package, suspended state, disk quota). This clearly separates it from the sibling list_reseller_users, which returns a collection rather than a single 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?

Gives explicit conditions: reseller accounts only, with regular accounts refused (403), plus an environment precondition (unavailable while MXROUTE_USERNAME is in `reseller|user` form). It does not name a sibling alternative to use instead when the constraint fails, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral detail — the meaning and range of the high_score return field (1-50, auto-deletion threshold) — but says nothing about error behavior for unknown domains or about the remaining returned fields.

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

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

Two short sentences, front-loaded with the operation and scope, and the second sentence delivers a concrete numeric constraint rather than filler. Nothing is wasted.

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

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

There is no output schema, so the description must carry the return-value burden, yet it documents only one field (high_score). It omits the other settings an agent would receive and any failure behavior, leaving the response shape largely unknown.

Complex tools with many parameters or behaviors need more documentation. 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 a single parameter at 100% schema description coverage (including pattern and an example), the schema already carries the parameter semantics, so the baseline is 3. The description's high_score note concerns a return value, not the domain parameter, so it adds no parameter-level meaning.

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

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

States a specific verb and resource ('Returns the spam filter settings') with scope ('for a domain'), so an agent knows exactly what it fetches. It does not differentiate from the close sibling update_spam_settings or from the whitelist/blacklist listing tools, so it stops short of a 5.

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

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

The description gives no when-to-use guidance, no mention of the read/write relationship with update_spam_settings, and no prerequisites (e.g., domain must exist on the account). Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the shape of each returned entry and the two possible pointer types (alias vs redirect).

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

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

Two tight sentences: the first states the action and scope, the second explains return contents. Nothing is redundant and the core purpose is front-loaded.

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

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

With no output schema, the description usefully compensates by describing the return entries and pointer types. For a one-parameter read-only list tool this is largely complete, though it omits any note on empty results or permissions 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 coverage is 100% with a single, well-documented 'domain' parameter including a pattern and example, so the schema does the heavy lifting. The description adds no syntax or format detail for the parameter, making a baseline 3 appropriate.

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

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

States a specific verb (Lists) and resource (domain pointers), and even defines the term as 'aliases and redirects' with the fields each entry carries. That is enough to separate it from siblings like list_domains or create/delete_domain_pointer, though no sibling is named explicitly.

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

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

There is no when-to-use guidance, no prerequisite (e.g. domain must exist on the MXroute account), and no mention of the create_domain_pointer / delete_domain_pointer siblings that manage the same resource. Usage is only inferable from the verb.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered elsewhere. The description's one added behavioral fact is that only domain names are returned, not full records — useful but thin for an open-world account-scoped call.

Agents need to know what a tool does to the 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 no filler or redundancy. Every word carries information about scope and return 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 zero-parameter, read-only list tool with no output schema and full annotation coverage, this is close to sufficient: the agent knows what it returns (names) and that it is safe and idempotent. It could add a note on pagination or whether names include verified/pending status, but nothing critical for correct invocation is missing.

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

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

The tool takes zero parameters, so the schema has nothing to explain and the description correctly introduces no parameter syntax. Baseline for a 0-param tool is 4 since there is no room for parameter-level ambiguity.

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

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

Clear specific verb (Lists) plus resource (domains) and scope (all domains on the MXroute account). It distinguishes itself from get_domain by implying a bulk name-only listing, but it never explicitly names a sibling or contrasts itself with list_domain_pointers or list_email_accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 only implied: 'all domains' suggests this is the enumeration entry point, but there is no explicit when-to-use or when-to-prefer get_domain for per-domain detail. No prerequisites or 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that by enumerating the returned data (quota in MB with 0 = unlimited, current usage, daily send limit, emails sent today, suspended state) — this is the only place that return shape is documented since no output schema 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?

One sentence, front-loaded with the action and resource, followed by a compact enumeration of returned fields. Dense but every clause carries information; only minor cost is that the parenthetical for quota units reads slightly cramped.

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

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

For a single-parameter read-only list tool with no output schema, the description adequately compensates by spelling out the returned fields and the 0-means-unlimited quirk. Pagination behavior and error cases (invalid or unhosted domain) are the only gaps.

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

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

Schema coverage is 100% and the single 'domain' parameter is fully documented in the schema with a pattern and example, so the baseline is 3. The description adds no syntax, format or constraint details 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?

States a specific verb and resource ('Lists the mailboxes on a domain') and enumerates the fields returned, which separates it from sibling listers like list_domains, list_forwarders and list_packages. It does not explicitly name a sibling it is not, so it falls just short of a 5.

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

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

No indication of when to use this tool versus get_email_account (single mailbox) or get_email_usage, and no prerequisites such as needing the domain to exist on the account. Usage must be inferred entirely 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds that destinations are returned alongside each forwarder, which is useful output context but not a deep behavioral disclosure 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?

A single efficient sentence that front-loads the primary action and resource and then adds the return value. No wasted words.

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

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

For a simple read-only list tool with 100% schema coverage and full annotation coverage, the description is nearly complete. It even mentions the return shape (forwarders plus destinations) despite no output schema. Minor gap: no pagination or result-size context.

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

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

Schema description coverage is 100%, and the single 'domain' parameter is fully documented in the schema with a pattern and example. The description only reiterates that the list is scoped to a domain, adding no syntax or format detail 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 uses a specific verb ('Lists') and resource ('email forwarders on a domain'), and it clarifies the return content ('the destinations each one forwards to'). It distinguishes itself from create_forwarder and delete_forwarder by implication, but never explicitly names alternatives, so it falls short of a 5.

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

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

Usage is implied by the listing purpose—an agent can infer this is for inspecting existing forwarders—but there is no explicit when-to-use guidance, prerequisites, or mention of sibling tools like create_forwarder or delete_forwarder. Adequate but with clear gaps.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine behavioral value on top: the 403 refusal for non-reseller accounts and the MXROUTE_USERNAME configuration constraint that makes the tool unavailable.

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

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

Two tight sentences with the purpose front-loaded before the access caveats. Slightly compressed notation (`reseller|user` form) but 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?

With zero parameters, no nested objects and no output schema, the description covers what the agent needs: the shape of the result (names) and the conditions under which the call fails. Only minor gaps remain, such as whether a non-reseller call errors or returns empty.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies no filtering arguments are accepted.

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

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

States a specific verb (Lists) and resource (the reseller's packages) and narrows the return to names, which distinguishes it from get_package, create_package and the other package siblings. An agent can tell immediately what it gets back and that it is a read-only enumeration.

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

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

Gives a concrete when-not condition: reseller accounts only, regular accounts refused with 403, and unavailable while MXROUTE_USERNAME is in `reseller|user` form. It stops short of naming an alternative tool (e.g. get_package for detail on a single package), so it is clear context rather than full routing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description goes further by disclosing the failure mode (403 for regular accounts) and an ambient configuration constraint on the caller's environment. That is real behavioral context beyond structured fields.

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

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

Two sentences, no filler, with the primary purpose front-loaded before the eligibility caveats. Every clause carries information an agent needs.

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

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

There is no output schema, but the description itself states the return content (usernames), and with zero parameters and full annotation coverage nothing else is needed to invoke it correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. It does implicitly note the absence of filtering (it returns all users under the reseller), which is consistent with an empty schema.

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

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

States a specific verb (lists) and resource (usernames of all user accounts under the reseller), and the word 'all' plus the plural resource separates it from the sibling get_reseller_user. An agent can tell it apart from list_domains or list_email_accounts without opening the schema.

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

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

Gives explicit when-not conditions: reseller accounts only, regular accounts are refused (typically 403), and the call is unavailable while MXROUTE_USERNAME is in `reseller|user` form. This is precisely the kind of precondition guidance that prevents misfires.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the domain argument is an ownership/auth scope, while the blacklist entries returned are account-wide — a non-obvious scoping rule an agent would otherwise get wrong.

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

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

Two sentences, zero waste, and the payload semantics are front-loaded before the scoping caveat. Every clause earns its place.

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

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

For a one-parameter read tool with 100% schema coverage and full annotations, the description covers the one trap (domain vs account-wide scope). It does not describe the shape of returned entries, but with no output schema that is a minor gap for a simple list operation.

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

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

Schema coverage is 100%, so the schema already documents the domain pattern and gives an example. The description adds meaning beyond it by clarifying that the domain must be one you own and that it does not filter the returned entries — a real semantic distinction, not a restatement.

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

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

States a specific verb and resource ('Lists the account-wide blacklist') and immediately defines what that resource contains ('sender entries that are always treated as spam'). This is clearly distinguishable from the sibling tools list_spam_whitelist, add_spam_blacklist_entry, and remove_spam_blacklist_entry.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('domain argument must be one you own') but never explicitly says when to reach for this tool versus the whitelist or the entry-management siblings. The scope caveat is helpful for calling correctly, but the routing guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds the non-obvious behavioral point that the list is account-wide and the domain argument does not scope the results, which the agent cannot infer from 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?

Two compact sentences, front-loaded with the action and scope, and every clause carries information (the domain constraint and the account-wide caveat). No filler.

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

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

For a single-parameter, read-only list tool with no output schema, the description supplies the action, the entry semantics, and the domain caveat. It stops short of describing ordering or pagination, but nothing essential to invoking it correctly is missing.

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

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

With 100% schema description coverage the baseline is 3, and the description goes beyond the schema by clarifying the semantic role of 'domain': it is an ownership/authorization anchor, not a result filter. That is added meaning the schema text alone does not convey.

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

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

States a specific verb and resource ('Lists the account-wide whitelist') and immediately defines what an entry is ('sender entries that are never treated as spam'). This clearly separates it from the sibling list_spam_blacklist and from the add/remove whitelist-entry tools.

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

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

It gives a real precondition ('the domain argument must be one you own'), which tells the agent when the call is valid, but it names no alternatives and offers no when-not guidance. Usage is implied rather than explicitly routed.

Agents often have multiple tools that could apply. Explicit usage 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 flag destructiveHint=true and idempotentHint=true, yet the description still adds value: it tells the agent to confirm with the user before calling, and warns that the lists are account-wide so a removal is not scoped to the given domain. It does not say what happens if the entry is absent, which is why it stops at 4.

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

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

Three short sentences, front-loaded with the operation and scope, followed by the ownership caveat and the safety directive. No filler.

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

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

No output schema and no annotations on return behavior, but for a delete operation the description covers scope, prerequisites, and the destructive-action guidance an agent needs. Minor gap: it doesn't state behavior when the entry doesn't exist (idempotency 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%, so the baseline is 3, but the description adds real meaning to the 'domain' parameter: it is a domain you own used to authorize the call, while the list itself is account-wide. That clarifies an otherwise confusing ownership/scope split the schema does not express.

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

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

States a specific verb ('Removes') plus resource and scope ('an entry from the account-wide spam blacklist'), which cleanly separates it from remove_spam_whitelist_entry and the other remove_* siblings. An agent can identify the operation without opening the schema.

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

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

Gives clear context for invocation: the domain must be owned by the caller and the user should be consulted before calling. It does not name an alternative or explain when removal is inappropriate versus, say, updating spam settings, so it falls short of the explicit alternatives required for a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description still adds value the annotations cannot: an explicit instruction to confirm with the user and the ownership constraint on the domain argument.

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

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

Three short sentences with no waste: what it does, the constraint on inputs, and the safety instruction. The destructive warning is placed last, right before invocation, which is the most useful position.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 full annotation coverage and no output schema, the description covers purpose, ownership precondition, and the confirmation requirement. It could optionally note whether removed entries can simply be re-added, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents both parameters with formats and examples. The description adds a semantic constraint not in the schema — that the domain must be owned by the caller while the whitelist entry itself is account-wide.

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

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

States a specific verb and resource ('Removes an entry from the account-wide spam whitelist'), plus the scope of the affected list. An agent can immediately distinguish this from remove_spam_blacklist_entry and add_spam_whitelist_entry among the siblings.

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

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

Gives a clear precondition (the domain must be one you own, while the list is account-wide) and a usage rule (confirm with the user before calling). It does not name the sibling alternatives explicitly, so it falls just short of the top band.

Agents often have multiple tools that could apply. Explicit usage 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, and the description adds specificity beyond them: blackhole silently discards mail (mail is lost) and the agent should confirm with the user first. It does not, however, describe the response shape or what happens to existing catch-all configuration.

Agents need to know what a tool does to the 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 tight sentences, front-loaded with the action, then the enum semantics, then the conditional parameter rule and the safety warning. Every sentence carries load.

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

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

No output schema exists and none is strictly needed for a settings mutation; the description covers the action, the enum behaviors, the conditional requirement, and the destructiveness warning. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds a constraint the schema omits: `address` must be omitted when type is not 'address'. It also restates the enum semantics, which is redundant with 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?

Names a specific verb and resource (set how mail to non-existent addresses is handled) and enumerates the three behaviors. It is clearly distinguishable from the read-only sibling get_catch_all, which is not mentioned but is obviously the read counterpart.

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

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

Gives a clear operational instruction ('Destructive: confirm with the user before calling'), which tells the agent when extra care is needed. It does not explicitly name the get_catch_all alternative for reading current settings, so it stops short of full when-vs-alternative routing.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds genuine consequence context: 'Disabling stops MXroute from handling mail for the domain.' 'Safe to repeat with the same value' largely restates idempotentHint, but the effect disclosure and the confirm-first directive add real value.

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

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

Four short sentences, front-loaded with the core action, then consequence, then safety guidance. No filler; every sentence contributes.

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

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

For a destructive mutation tool with no output schema, the description covers the action, its consequence, idempotency, and the confirmation requirement. It could note return/effect on other domain settings, but it is sufficient to call 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%, so both parameters (domain pattern example, enabled boolean meaning) are already fully documented in the schema. The description adds no parameter-level detail beyond that, making 3 the correct baseline.

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

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

States a specific verb pair (enables/disables) and resource (mail hosting for a domain), so the agent immediately knows the capability. It does not name a sibling to contrast with, but the capability is distinct from the domain/account/spam tools around it.

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

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

Provides a clear operational directive ('Destructive: confirm with the user before calling') but gives no explicit when-to-use-vs-alternatives guidance or prerequisites. Usage is implied by the purpose rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, yet the description adds real value beyond them: the specific failure mode for non-reseller accounts (403), the deployment-level MXROUTE_USERNAME restriction, and an explicit instruction to confirm with the user before calling.

Agents need to know what a tool does to the 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 tight sentences: effect first, eligibility constraints second, safety warning last. Every sentence earns its place and nothing is repeated from the schema or annotations.

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

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

For a single-parameter mutation with no output schema, the description covers effect, reversibility, eligibility, error behavior and the required confirmation step. An agent has everything needed to decide whether and how to call it.

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

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

Only one parameter and schema description coverage is 100%, with the schema already giving the format and an example ('johndoe'). The description adds nothing about the parameter itself, 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?

States a specific verb and resource ('Suspends a user account') and immediately scopes the target ('Reseller accounts only'), which distinguishes it from the sibling delete_reseller_user (permanent) and unsuspend_reseller_user (inverse). 'Interrupts their service until unsuspended' makes the reversible, temporary nature 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?

Gives clear when-not conditions: regular accounts are refused (typically 403) and the tool is unavailable when MXROUTE_USERNAME is in `reseller|user` form. It does not explicitly name unsuspend_reseller_user or delete_reseller_user as alternatives, so it falls just short of the top band.

Agents often have multiple tools that could apply. Explicit usage 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 cover the safety profile (non-destructive, idempotent, open-world), and the description adds genuinely new behavioral context: the 403 refusal for non-reseller accounts and the runtime configuration constraint on MXROUTE_USERNAME that can make the tool unavailable. It does not discuss what state the account returns to or any rate limits, but for a simple idempotent restore this is solid added value with no contradiction of 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?

Two sentences, front-loaded with the core action and free of filler; the eligibility constraints are compressed into the second sentence. The MXROUTE_USERNAME clause is dense and slightly opaque on first read, which keeps it just short of ideal, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 state-change tool with annotations carrying the safety hints, the preconditions (reseller-only, config-form availability) are the main things an agent needs and they are present. Success return values are not described, but there is no output schema and this is a simple idempotent restore, so the omission is minor.

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

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

With a single parameter at 100% schema description coverage, the schema already documents `username` fully (including an example), so the baseline is 3. The description only reinforces that the username belongs to the reseller's user account, adding no syntax or format information beyond the schema.

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

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

The description opens with a specific verb and resource — 'Restores a suspended user account' — which directly names the state transition and makes it easy to distinguish from the sibling suspend_reseller_user, delete_reseller_user, and update_reseller_user. It also scopes the tool to reseller accounts, so an agent knows exactly which object class it acts on.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states a clear exclusion ('Reseller accounts only (regular accounts are refused, typically with 403)') and a configuration precondition (not available while MXROUTE_USERNAME is in `reseller|user` form), which is real when-not guidance. It stops short of naming an alternative tool for regular accounts or explaining what an agent should do when it hits the 403, so it is clear but not fully prescriptive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior beyond the annotations: 'Changing the password locks out anyone using the old one' is a real side effect an agent must know, plus the partial-update semantics.

Agents need to know what a tool does to the 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 tight sentences, each earning its place: scope, input constraint, and the destructive warning. The consequence of the password change and the confirmation instruction are front-loaded where the agent will see them.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 covers purpose, input constraint, partial-update behavior, and the key destructive side effect, and annotations cover the safety profile. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented, giving a baseline of 3. The description adds the important at-least-one-of constraint and the 'omitted fields stay unchanged' behavior, neither of which is expressible in the given schema (which only marks domain/username as required).

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

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

States a specific verb (Changes) plus the exact mutable fields (password, quota, daily send limit) of a mailbox, which functionally distinguishes it from create_email_account, get_email_account, and delete_email_account. It does not name a sibling explicitly, so it falls short of the 5 bar.

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

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

Gives concrete usage conditions: at least one of password/quota/limit must be supplied, omitted fields stay unchanged, and 'confirm with the user before calling' before a destructive change. There is no explicit comparison to sibling tools, so no exclusions or alternatives 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new behavior: omitted limits are preserved (partial update, consistent with idempotentHint), the call requires a reseller account, and failures surface as 403. The environment gating on MXROUTE_USERNAME is unusual context an agent could not infer.

Agents need to know what a tool does to the 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, no filler. The core action and the partial-update contract come first, and the account/environment caveats follow. Every clause carries 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 mutation tool with no output schema, it covers semantics, auth gating, and error behavior. It does not say what the response contains or what happens if the package name does not exist, but those are minor gaps given the otherwise thorough treatment.

Complex tools with many parameters or behaviors need more documentation. 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, but the description adds meaning the schema cannot express: at least one limit must be supplied, and unspecified limits are left untouched rather than reset. That is directly relevant to how the agent fills the five optional limit parameters.

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

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

The description opens with a specific verb and resource: "Changes a package's limits." That cleanly separates it from create_package/delete_package/list_packages, though it never names a sibling explicitly. An agent knows what the tool mutates without opening the schema.

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

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

It gives explicit prerequisites and exclusions: reseller accounts only, regular accounts refused with 403, and unavailable while MXROUTE_USERNAME is in `reseller|user` form. It also states the partial-update rule (at least one limit required). It stops short of pointing to an alternative tool, but the when/when-not coverage is strong.

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

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

Goes well beyond the annotations: it warns that a password change locks out holders of the old password, states the reseller-only authorization requirement and its typical 403 error, notes an environment-dependent unavailability, and advises confirming the destructive action with the user — matching destructiveHint=true rather than contradicting it.

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

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

The core action is front-loaded in the first sentence, with preconditions, side effects, and the destructive warning following in tight, waste-free sentences. No repetition of schema or annotation 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 three-parameter mutation tool with no output schema and rich annotations, the description covers partial-update rules, authorization scope, side effects, and confirmation policy — everything needed to call it safely.

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

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

Schema coverage is 100%, so field formats are already documented; the description nonetheless adds the crucial at-least-one-of-quota/password constraint and the partial-update semantics ('omitted fields stay unchanged'), which the schema's lone required field cannot express.

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

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

States a concrete verb ('Changes') plus the exact mutable fields ('disk quota and/or password') on a named resource ('a user', scoped to reseller users). It is clearly distinguishable from siblings like change_reseller_user_package or update_email_account without opening either schema.

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

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

Provides a real precondition ('Provide at least one; omitted fields stay unchanged'), an account-type restriction with the expected failure mode (403), and a configuration exclusion. It does not name an explicit alternative tool for related operations (e.g. package changes), so routing between siblings is inferred rather than stated.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real substance: the risk profile of low thresholds (deleting legitimate mail), a specific failure mode (unconfirmed-save) with a recovery path, and an explicit user-confirmation requirement. This is behavior an agent cannot infer from the annotations alone.

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

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

Three compact sentences, all front-loaded: what it does, how to interpret the value, then the failure/recovery and safety instructions. No filler or restatement of the tool name.

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

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

For a two-parameter mutation with no output schema, the description covers the effect, the risk of the value chosen, the error-recovery path, and the confirmation requirement. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what high_score actually means in practice: lower values are stricter and risk deleting legitimate mail. That semantic framing is not derivable from the schema's 'Auto-delete score threshold, 1-50'.

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

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

Opens with a specific verb+resource and scope: it sets the high_score threshold (1-50) for automatic spam deletion. This clearly separates it from the read-side sibling get_spam_settings and the whitelist/blacklist tools. An agent knows exactly what mutation this performs.

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

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

Names get_spam_settings explicitly and the condition that should route the agent to it (an unconfirmed-save error before retrying), and instructs the agent to confirm with the user first. It does not give a full when-not-to-use rule, but the routing condition and the pre-call confirmation requirement are concrete.

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