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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is structured. The description adds real value beyond that: the 409 duplicate-error semantic, case-insensitive matching, wildcard support, and the important scope fact that sender lists are shared across all domains on the account.

Agents need to know what a tool does to the 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 clauses, front-loaded with the action and its effect, followed by the wildcard format, error semantics, and account-wide scope. 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?

With an output schema present, annotations covering safety, and full schema coverage, the description supplies everything else an agent needs for a 2-parameter mutation: duplicate handling, matching rules, and account-wide reach. Only a note on cross-domain authorization or immediate-effect timing would improve it further.

Complex tools with many parameters or behaviors need more documentation. 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 `entry` are already documented, including wildcard examples and patterns; the schema itself carries the heavy lifting. The description reiterates the wildcard example and adds the case-insensitivity note, but does not explain per-parameter syntax beyond what the schema states, 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 ('Adds an entry to the spam blacklist') and immediately gives the resulting behavior ('blacklisted senders are always treated as spam'). This is unmistakably distinct from the sibling remove_spam_blacklist_entry and get_spam_blacklist, so an agent can select it without opening a 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?

Usage is implied by the name and effect statement, and the 409 note tells the agent what happens on a duplicate, but there is no explicit when-to-use-vs-alternatives guidance (e.g., blacklist vs. whitelist conflict, or when to prefer update_spam_settings). Adequate but with a clear gap.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive mutation, and the description adds genuinely new behavior: a 409 response when the entry already exists, case-insensitive matching, and the fact that whitelists are shared across all domains. It does not describe auth requirements or the response payload, but the output schema covers the latter.

Agents need to know what a tool does to the 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 tight clauses, front-loaded with purpose followed by syntax, error behavior, and scope. Each sentence carries distinct information, with only minor overlap between the wildcard note and 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?

An output schema exists, so return values need no explanation. For a two-parameter mutation the description covers purpose, accepted syntax, duplicate handling, and scope semantics, leaving nothing an agent needs in order 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 already 100%, so the baseline is 3; the description earns above that by explaining that wildcards like `*@trusted.com` are valid and that matching is case-insensitive. The note that sender lists are shared across all domains is especially valuable because it clarifies that `domain` does not scope the entry itself.

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

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

"Adds an entry to the spam whitelist; whitelisted senders bypass spam filtering" gives a concrete verb, resource, and the effect of the operation. The name alone separates it from add_spam_blacklist_entry and remove_spam_whitelist_entry, but the description never states those distinctions explicitly, 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 context is implied by the tool name and reinforced by notes on wildcard support and the account-wide sharing of sender lists, which tells the agent the entry is not scoped to one domain. However, there is no explicit when-to-use or when-not routing against add_spam_blacklist_entry, update_spam_settings, or a prerequisite of checking get_spam_whitelist first.

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

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

Beyond the annotations, the description discloses the verification prerequisite, expected DNS propagation time, return fields, and the 409 conflict behavior. These details materially help an agent avoid calling the tool prematurely or misinterpreting an already-existing domain.

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

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

The description is front-loaded with purpose, followed by the verification workflow, return behavior, and error case. It is efficient overall, though the return-value sentence slightly duplicates what the output schema already captures.

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

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

Given the prerequisite verification workflow and output schema, the description covers what an agent needs: when the domain must be verified, how to verify it, expected propagation delay, return fields, and the duplicate-domain error. No critical invocation context is missing.

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

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

The schema already fully documents the single 'domain' parameter with format guidance. The description reinforces that the domain is for email hosting and appears in the TXT record name, but adds no new syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource: 'Adds a new domain to the account for email hosting.' It distinguishes the operation from sibling tools like create_domain_pointer by tying it to email hosting and domain verification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear preconditions: verify the domain first by calling get_verification_key, adding a TXT record, and waiting for DNS propagation. It also explains the 409 error for existing domains, though it does not explicitly compare alternatives such as get_domain or list_domains.

Agents often have multiple tools that could apply. Explicit usage 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, and destructiveHint=false, so the agent knows this is a non-idempotent write with no destructive effect. The description adds useful context that the pointer is 'attached to an existing domain' and that alias mode serves the target's mailboxes, but it says nothing about permission/verification requirements, duplicate-pointer conflicts, or what happens on repeat calls.

Agents need to know what a tool does to the 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 zero filler; the core operation is front-loaded and the alias semantics follow immediately. Slight redundancy with the schema's alias description is the only inefficiency.

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

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

An output schema exists, annotations cover the safety profile, and the full parameter set is schema-documented, so the description need not explain return values. What remains thin is the precondition/error context around attaching a pointer, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description's alias=true/false explanation largely restates the schema's own parameter description, adding no new syntax, constraints, or defaults beyond it. Baseline 3 applies 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?

The description uses a specific verb and resource: 'Attaches a pointer domain to an existing domain,' and immediately distinguishes the two resulting behaviors (alias vs redirect). It does not explicitly differentiate itself from siblings such as delete_domain_pointer or list_domain_pointers, but the name and verb make the create-only role unambiguous.

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

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

There is no explicit guidance on when to use this tool versus create_domain, delete_domain_pointer, or list_domain_pointers, nor any stated prerequisites (e.g., the target domain must exist on the account). The alias/redirect explanation clarifies a mode choice once the tool is selected, but not the tool-selection decision itself.

Agents often have multiple tools that could apply. Explicit usage 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 (not read-only, not idempotent, not destructive), so the description's job is to add context. It does add useful notes about server-side password-strength enforcement and default quota/limit application, but omits prerequisites (domain must exist), behavior when the mailbox already exists, and irreversibility of creation.

Agents need to know what a tool does to the 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 front-loaded sentences with the core action first, then parameter clarification. It is efficiently sized, though the parameter recap partially duplicates the already-complete 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?

An output schema exists, so return values need not be explained, and the parameter space is covered. However, for a creation tool with five parameters and many sibling tools, the absence of prerequisites and duplicate-name behavior leaves a meaningful gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates what the schema already documents (username as local part, 8-72 char password, quota in MB, daily send limit) rather than adding new meaning such as quota interaction with the account's disk quota or username collision behavior.

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

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

"Creates a mailbox under a domain" gives a specific verb and resource, and the mailbox framing separates it from sibling tools like create_domain, create_forwarder, and create_domain_pointer. It stops short of explicitly naming which sibling handles adjacent cases (e.g. update_email_account), so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 or when-not-to-use guidance: nothing says the domain must already exist and be verified, nor how this differs from update_email_account for an existing mailbox. Usage is only inferable from the tool name and 'Creates a mailbox under a domain.'

Agents often have multiple tools that could apply. Explicit usage 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 the mutating, non-idempotent, non-destructive profile, but the description adds a genuinely non-obvious side effect: forwarding to Gmail/Yahoo/AOL automatically enables Expert Spam Filtering for the domain. It also explains the semantic effect of the special destination values, which is real behavioral information beyond the safety hints. It does not cover duplicate-alias handling or failure modes.

Agents need to know what a tool does to the 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, front-loading the core action before the special-destination semantics and the domain-wide side effect. Nothing is padded or repeated unnecessarily for a tool of this scope.

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

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

An output schema exists, so return values need not be explained, and the annotations carry the safety profile; the description fills its remaining duty by disclosing the automatic spam-filtering side effect. The only material gap is preconditions and duplicate/error behavior for an alias that already has a forwarder.

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

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

Schema description coverage is 100%, with the alias/domain formats and the :blackhole:/:fail: constants already documented in the schema itself, so the baseline is 3. The description re-states the special destination meanings in behavioral terms but adds no syntax, format, or constraint information the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Creates an email forwarder for an alias on a domain'), which is enough for an agent to distinguish it from sibling tools such as create_email_account or delete_forwarder. It stops short of explicitly naming the sibling it differs from, so it lands just below the top score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 purpose statement; there is no explicit when-to-use versus when-to-use-delete_forwarder or create_email_account guidance. It also omits prerequisites, such as the domain already existing on the account, or what happens when a forwarder for that alias already exists.

Agents often have multiple tools that could apply. Explicit usage 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 state readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered; the description adds the authentication mode requirement and the fact that unset limits fall back to API defaults. It does not say what happens on a duplicate package name or whether defaults are frozen or inherited at creation time, leaving a small gap.

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

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

Purpose and the reseller-auth constraint are front-loaded and earn their place, but the middle sentence enumerating all five default values duplicates the schema descriptions verbatim and is pure redundancy. Two strong sentences padded by one expendable one.

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

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

With an output schema present the description need not explain return values, and annotations cover the mutation safety profile; purpose, defaults and auth mode are all addressed. The only missing piece is failure behavior (duplicate name, invalid quota) and how a created package is later assigned, which is minor for a straightforward create tool.

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

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

Schema coverage is 100% and every parameter description already states its own default (quota default 1, domains default 1, email_accounts default 100, domain_pointers default 10, email_forwarders default 100). The description's default list therefore restates schema content rather than adding meaning, so the baseline 3 for a fully documented schema is right.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Creates a package") and immediately defines what a package is for ("reseller users can be assigned to"), which separates it from create_reseller_user and from the list/get/update/delete_package siblings. An agent can decide between this and update_package without opening a 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 a real precondition: it is a reseller-level operation and must be called while authenticated as the reseller, not while impersonating a user. That is actionable context an agent would otherwise get wrong. It stops short of explicit when-to-use-vs-alternative routing (e.g. "use update_package to modify existing limits"), so not a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered; the description goes further by disclosing the auth context requirement and the 422-exists error semantics, both non-obvious. It does not address duplicate-username behavior or what happens to the created user's initial state, which matters given idempotentHint=false and an output schema it never contextualizes.

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

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

Three sentences, each carrying a distinct load: what is created, the auth constraint, and the prerequisite/error. The critical call-condition constraint is front-loaded in the second sentence where it will be read before invocation.

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

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

For a four-required-parameter mutation with full annotations, a 100%-covered schema, and an existing output schema, the description covers the gap-prone parts: auth mode, prerequisite, and error interpretation. The only shortfall is leaving duplicate-username/collision behavior unstated for a non-idempotent create.

Complex tools with many parameters or behaviors need more documentation. 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 formats, lengths, and patterns for all four parameters are already documented in the schema, making the baseline 3. The description restates the same four field names without adding syntax or validation detail, and its "package must already exist (see list_packages)" note duplicates what the package property description already says.

Input schemas describe structure but not intent. Descriptions should explain 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+resource ("Creates a user under the reseller account") and enumerates the identifying fields (username, contact email, password, package), so an agent knows exactly what is produced. It implicitly separates itself from create_email_account by scoping the operation to the reseller account, though it never names the sibling create tools it could be confused with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the precise call condition (authenticate as the reseller with the plain reseller username) and an explicit when-not (not while impersonating a user), which is the main failure mode for this API surface. It also gives a prerequisite and points to list_packages for satisfying it, plus the 422 signal when the package is missing.

Agents often have multiple tools that could apply. Explicit usage 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, but the description adds the concrete blast radius beyond that flag: mailboxes and forwarders under the domain stop working and inbound mail is no longer handled. It does not say whether deletion is immediate or reversible (e.g. a grace period), which is the remaining behavioral gap for a destructive operation.

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

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

Three short sentences with zero waste: action first, consequences second, safer alternative last. Every sentence earns its place and the destructive warning 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 one required parameter, full schema coverage, an output schema, and annotations carrying the safety profile, the description covers what an agent needs to call it and what will break. Minor gap: it does not state whether the removal is permanent or whether prerequisites (e.g. no active pointers) apply.

Complex tools with many parameters or behaviors need more documentation. 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 already documents format and an example, so the baseline of 3 applies. The description adds no additional meaning about the parameter, such as whether the domain must be verified or owned by the account first.

Input schemas describe structure but not intent. Descriptions should explain 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 the domain from the account'), scoped to this account. It is clearly distinguishable from the sibling delete_domain_pointer (which deletes a pointer, not the domain) and from set_domain_mail_hosting by naming that alternative 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?

Gives an explicit alternative and the condition that selects it: use set_domain_mail_hosting to pause mail service without deleting the domain. The agent can decide between destructive deletion and temporary suspension without inference.

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

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

Annotations already declare destructive=true, idempotent=true and readOnly=false, so safety is structured. The description still earns credit by spelling out the actual effect — the pointer domain stops serving the target's mailboxes while the target is unchanged — which is real blast-radius information annotations cannot convey. It stops short of stating whether the pointer record is recoverable or what happens if the pointer does not exist.

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

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

Two short sentences, effect first and scope-reassurance second, with no filler. Every clause carries information an agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 delete with an output schema and full annotation coverage, the description supplies the key missing piece: what breaks and what does not. Minor gaps remain around error behavior for nonexistent pointers and whether the change is reversible, but nothing essential to calling it correctly is absent.

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

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

Schema coverage is 100%, but both parameters carry identical boilerplate ("Domain name on this account..."), leaving the domain/pointer roles ambiguous in the schema alone. The description resolves this by framing it as removing a pointer domain from a target domain, which is genuine added meaning. It still does not state the expected format or which direction the alias points.

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

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

"Removes a domain pointer (alias or redirect) from a domain" names a specific verb and resource, and the parenthetical disambiguates what a pointer actually is. The follow-up clause separates this from delete_domain by stating the target domain is untouched, so the agent can distinguish it from siblings 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?

The description implies when this applies (detaching a pointer/alias from a domain) but never states preconditions, alternatives, or exclusions. It does not point to create_domain_pointer or list_domain_pointers as the complementary or lookup operations, so routing must be inferred from sibling names.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is known. Beyond that, the description adds what the annotations cannot say: that stored mail is destroyed, that the address stops accepting mail immediately, and that deletes are casing-sensitive while updates are not, with ambiguous matches rejected.

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

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

Three sentences, front-loaded with the destructive consequence, then the parameter clarification, then the casing prerequisite. No filler, and the most consequential fact comes 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 two fully documented parameters and an output schema, return values need no explanation. The description covers the destruction scope and the casing pitfall well. It stops short of stating permission or authentication requirements, which is the only notable gap for a destructive two-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?

Schema coverage is 100%, and the schema already explains that user is the local part before the @. The description nonetheless adds meaning the schema lacks: that deletes must use the exact stored casing while updates resolve case-insensitively and reject ambiguous matches. It adds little about domain, but nothing is missing.

Input schemas describe structure but not intent. Descriptions should explain 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 first sentence gives a specific verb and resource plus scope: 'Permanently deletes a mailbox and its stored mail.' That is clearly distinct from sibling deletes like delete_domain, delete_forwarder, and delete_domain_pointer, and from create_email_account and update_email_account.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 names a real prerequisite workflow: call list_email_accounts or get_email_account first and use the exact stored casing. It does not explicitly rule out alternatives or state when not to delete, but for a terminal delete operation the relevant guidance is the lookup step, which is spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the concrete consequence ('Mail sent to the alias is no longer forwarded after deletion'), which tells the agent what is actually lost. It stops short of noting permission requirements or behavior when the alias is missing, but it meaningfully exceeds the annotation coverage.

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

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

Three short sentences: purpose first, then effect, then the preparative instruction. No filler and nothing redundant with structured fields.

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

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

For a destructive two-parameter tool with an output schema and full annotation coverage, this covers what to pass and what happens. Only secondary details (permissions, not-found behavior) are absent, which is reasonable.

Complex tools with many parameters or behaviors need more documentation. 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 a genuinely non-obvious constraint: the alias must be passed with its exact stored casing, which the pattern/regex in the schema does not convey. That materially affects correct invocation.

Input schemas describe structure but not intent. Descriptions should explain 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 by its alias') plus the scope of the effect, which cleanly distinguishes it from create_forwarder and list_forwarders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisite workflow: read the alias's exact stored casing from list_forwarders and pass it unchanged. It doesn't state when not to delete (e.g., alternatives or confirmation expectations), but the actionable context is clear.

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

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

Beyond the annotations, the description discloses the 422 dependency failure, the need to move users before deletion, and the reseller authentication requirement rather than user impersonation. It also explains the 404 case, adding meaningful operational context for a destructive operation.

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

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

Three tight sentences front-load the action, then immediately cover the failure precondition, authentication constraint, and error handling. Every sentence carries distinct operational information with no filler.

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

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

For a single-parameter destructive tool with an output schema and rich annotations, the description covers the missing pieces an agent needs: preconditions, auth scope, and error interpretation. Nothing material is left unspecified.

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

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

There is only one parameter, 'name', and schema description coverage is 100%, so the schema already documents its format and constraints. The description does not add syntax or naming semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource ('Deletes a package'), making the operation unambiguous. It also clarifies the reseller-level scope, though it does not explicitly contrast with other package-management siblings beyond naming set_reseller_user_package as a prerequisite step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 exactly when deletion fails (422 while users are on the package) and tells the agent what to do first via the sibling tool set_reseller_user_package. It also specifies the required authentication context and the meaning of a 404, leaving little to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known; the description adds value beyond that by disclosing the cascade scope ("everything under it"), the irreversibility, the possibility of failure per DirectAdmin behavior, and the auth-context requirement. Nothing here contradicts 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?

Four tight sentences with the danger warning front-loaded before auth and error details, and no padding. The phrase "may fail or cascade" is somewhat hedged and could be sharper, but 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?

For a one-parameter destructive tool with an output schema already available, the description covers everything an agent needs to act safely: scope of deletion, auth context, and error interpretation. Return values are correctly left to the output schema.

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

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

Schema description coverage is 100% — the single username parameter already carries type, pattern, length, and character rules. The description only adds the caution to double-check the username first, which is operational advice rather than new semantics, 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?

Opens with a specific verb and resource ("deletes the user and everything under it") and immediately scopes the blast radius. An agent can distinguish it from suspend_reseller_user, delete_domain, and delete_email_account 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 a clear precondition that is easy to get wrong — call while authenticated as the plain reseller, not while impersonating a user — and explains what a 404 means. It does not explicitly route an agent to the non-destructive alternative (suspend_reseller_user) when reversibility is desired, 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context by decoding the returned setting: the three `type` values with their mail-handling meaning and the conditional nullity of `address`. It stops short of stating error behavior for an unknown domain or any account/permission requirements.

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

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

Two compact sentences: the purpose first, then the value semantics. Every clause carries information an agent would otherwise have to guess from the enum values, 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 one fully documented parameter, safety annotations, and an output schema, the remaining burden is small, and the description covers the interpretation of the returned values. The only gap is failure behavior (nonexistent domain, insufficient permissions), which an agent might want before calling.

Complex tools with many parameters or behaviors need more documentation. 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 already documented with format constraints (letters, digits, hyphens, at least one dot). The description contributes no additional meaning about the parameter, 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 ("Returns the domain's catch-all setting") and immediately defines the resource in domain terms ("how mail addressed to nonexistent local parts is handled"). This distinguishes it cleanly from the write-side sibling set_catch_all and from unrelated getters like get_spam_settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 counterpart to set_catch_all, but the description never says when to call it (e.g., to inspect current routing before changing it) or what to do if the domain is missing. No exclusions or prerequisites 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds two genuinely useful behavioral facts beyond that: results can be stale because 'Data is refreshed hourly', and a quota limit of 0 means unlimited, which prevents misreading the return 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?

A single sentence, front-loaded with the verb and resource, where every clause carries information (sentinel value, category list units, grace period, refresh cadence). Nothing is redundant or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with an output schema and full annotations, the description covers what an agent needs: what comes back, the meaning of the 0 sentinel, and the hourly staleness window. Little 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add. It correctly avoids inventing inputs and instead spends its words on output 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?

Uses a specific verb+resource ('Returns account disk usage') and enumerates the data returned: total used, quota limit with 0=unlimited sentinel, percent used, category breakdown, and grace period. This makes it distinguishable from the narrower get_email_usage sibling, though it never names that 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 by the tool's scope — an agent can infer it should call this for account-wide quota checks. There is no explicit when-to-use or when-not guidance, and no routing to get_email_usage for email-only usage figures.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses which record types come back and, importantly, that `dkim` and `verification` are null when not applicable — a behavioral detail an agent would otherwise have to discover from a failed lookup.

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

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

Two sentences, front-loaded with the core purpose, then the null-semantics caveat. Nothing is repeated from the title and no wording 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?

With an output schema present and annotations covering safety, the description only needs to frame purpose and unusual return cases — both done. It stops short of noting whether records are generated by MXroute or read live from DNS, which would be the last useful detail for a read-only diagnostic tool.

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

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

There is a single `domain` parameter with 100% schema description coverage including format constraints, so the schema does the work. The description adds no syntax, format, or constraint detail beyond it — 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 the DNS records') and enumerates exactly what is included: MX plus SPF, DKIM, and verification TXT records. The stated purpose ('to configure at the domain's registrar for MXroute mail delivery') makes it unmistakably different from siblings like get_domain or get_verification_key.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 domain's registrar for MXroute mail delivery' implies the setup context in which this should be called, but there is no explicit when-to-use, no prerequisites (e.g. must the domain already exist / have mail hosting set?), and no routing to alternatives such as get_verification_key for the verification record alone.

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

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

The annotations already declare this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds the returned fields, but because an output schema exists, this return-value detail is largely redundant; it does not mention permission requirements, error behavior, or domain-not-found handling.

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

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

Two compact sentences with no wasted wording, and the primary purpose is front-loaded before the sibling-tool recommendation. Every sentence contributes useful information for selecting and invoking the tool.

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

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

For a simple one-parameter read tool with annotations and an output schema, the description covers purpose, returned data, and discovery of valid domain names. It is nearly complete, with only minor gaps around domain-not-found behavior or prerequisites not being mentioned.

Complex tools with many parameters or behaviors need more documentation. 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 already has a clear description with format examples. The tool description adds only that the domain must be one on the account and points to list_domains for discovery, which is marginally useful but does not meaningfully extend the schema.

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

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

The description states a specific verb and resource ('Returns the details of one domain') and enumerates the exact details returned: mail hosting status, SSL status, and domain pointer aliases. It also names the sibling tool used for discovery, so an agent can distinguish it from list_domains 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?

It explicitly directs the agent to use list_domains to discover domain names before calling this tool, which gives clear usage context and names the alternative. It does not state exclusions or what to do if the domain is unknown, but the core when-to-use guidance is present.

Agents often have multiple tools that could apply. Explicit usage 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 that this is a safe, idempotent read operation, so the description does not need to restate that. It adds useful interpretation for quota values ('0 = unlimited') but does not describe error behavior, authentication requirements, or what happens when the mailbox does not exist.

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

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

The description is two compact sentences with no filler. The core behavior is front-loaded, followed by a clarifying note about the 'user' parameter.

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

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

For a simple read-only getter with full schema coverage, annotations, and an output schema, the description is largely complete. The only minor gap is that it does not mention failure behavior when the mailbox or domain does not exist.

Complex tools with many parameters or behaviors need more documentation. 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 are already documented in the input schema. The description repeats that 'user' is the mailbox local part but adds no new format or constraint details beyond the schema.

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

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

The description states a specific verb and resource: it returns details of one mailbox, and it lists the exact fields returned. The phrase 'one mailbox' clearly distinguishes it from list_email_accounts and other domain-level sibling tools.

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

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

Usage is implied by 'one mailbox,' which suggests the tool is for fetching a single existing account rather than listing accounts. However, there is no explicit when-to-use guidance, no exclusions, and no mention of the sibling list_email_accounts.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the data is refreshed hourly (staleness caveat) and results are sorted largest-first. It doesn't discuss truncation or limits for accounts with very many mailboxes.

Agents need to know what a tool does to the 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 what is returned and in what order, followed by the use case and the freshness caveat. Every sentence carries information an agent would otherwise lack.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with an output schema, this covers nearly everything: scope, ordering, field set, use case, and refresh cadence. The only gap is whether results are ever truncated or capped for accounts with many mailboxes, which matters given there is no pagination parameter.

Complex tools with many parameters or behaviors need more documentation. 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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly signals that the response is account-wide and unfiltered.

Input schemas describe structure but not intent. Descriptions should explain 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 per-mailbox disk usage for the account") plus the ordering (largest first) and returned fields (email address, size in bytes, last update time). This is distinguishable from the sibling get_disk_quota, which covers account-level quota rather than per-mailbox consumption.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use case: finding mailboxes to trim when the account nears its quota. It doesn't explicitly name alternatives or exclusions (e.g., how it differs from get_disk_quota or list_email_accounts), so it stops short of full routing 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 declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral context: null means unlimited for quota and limits, email_accounts excludes the system mailbox, and a 404 has a defined meaning. Only edge behaviors such as permissions failures beyond the reseller-auth note are left unstated.

Agents need to know what a tool does to the 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 ordered by importance: what is returned, then authentication constraint, then error semantics. The parenthetical null definitions are dense but each earns its place; 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?

Despite being a single-parameter read tool, the definition covers the two things an agent can actually get wrong — the reseller authentication mode and interpreting nulls/404. An output schema exists, so return-shape explanation is not required, and the remaining need is met.

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

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

Schema coverage is 100% and the single 'name' parameter already documents its pattern (letters, numbers, underscores, hyphens). The description's detail is about returned fields rather than the name argument, so it adds nothing meaningful beyond the schema — 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 ('Returns one package's settings') and then enumerates exactly which fields come back (quota_gb, domains, email_accounts, email_forwarders, domain_pointers). The singular 'one package' combined with the sibling name list_packages makes the scope distinction obvious 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?

Gives clear preconditions for use: it is a reseller-level operation and must be called authenticated as the reseller rather than while impersonating a user, plus what a 404 implies. It stops short of explicitly naming list_packages as the alternative for enumerating packages, so it is context-rich but lacks explicit 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the required authentication context (reseller-level, non-impersonated session), the meaning of a 404 (user does not exist), and the null-vs-numeric semantics of the quota field. These are the details an agent needs to interpret failures and results correctly.

Agents need to know what a tool does to the 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 what is returned, then the auth constraint, then the error meaning. No filler, and each 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 single-record read with an output schema, the definition covers return contents, auth context, and the 404 case, so it is largely sufficient. The remaining gap is that, in a family of reseller-user tools, it does not position itself against the list/update/delete siblings or clarify how the username is scoped to the authenticated reseller.

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

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

Schema coverage is 100% and the schema already documents the username format (length, lowercase/digit/underscore pattern), so the description need not repeat it. However, the description's phrase 'plain reseller username' sits alongside 'one reseller user's details', leaving slight ambiguity about whether the parameter identifies the reseller or the target user; the description could have resolved this.

Input schemas describe structure but not intent. Descriptions should explain 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 one reseller user's details') and enumerates the returned fields (username, email, domain, package, suspended flag, quota), which also distinguishes it from list_reseller_users by scope (single record vs. listing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisite and a when-not: it must be called while authenticated as the reseller, not while impersonating a user. It does not name the alternative (e.g. list_reseller_users for enumeration, update_reseller_user for modification), so sibling routing is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still earns credit for non-obvious behavior: wildcard syntax, case-insensitive matching, account-wide sharing of sender lists, and treating an empty 200 as an empty list. It does not describe ordering or pagination of the returned entries, which is the remaining behavioral gap.

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

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

Four short sentences, each contributing a distinct fact, with the core purpose front-loaded before details about matching and list scope. No filler or repetition.

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

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

For a single-parameter read tool with full schema coverage, complete annotations, and an output schema that documents the return value, the description covers everything an agent needs: purpose, matching semantics, list scope, and empty-result behavior.

Complex tools with many parameters or behaviors need more documentation. 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 domain format (letters, digits, hyphens, at least one dot) is already fully documented in the schema. The description's note that sender lists are shared across all domains on the account sharpens what the domain parameter does and does not scope, but that is a modest addition over a fully described single parameter.

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

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

States a specific verb and resource ("Lists the spam blacklist entries for a domain"), which is enough to separate it from add_spam_blacklist_entry and remove_spam_blacklist_entry by name alone. It never explicitly contrasts itself with the sibling get_spam_whitelist, so the differentiation is implied 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?

The read-only listing framing implies when to use it, and the sibling names make the add/remove counterparts guessable. There is no explicit "use this when..." clause, no mention of when to prefer get_spam_settings, and no stated prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value by explaining that `high_score` is a 1-50 SpamAssassin-style threshold at which mail is deleted, which is behavior an agent could not derive from the annotations. It does not say whether whitelist/blacklist entries are included in the response or what defaults apply to an unconfigured domain.

Agents need to know what a tool does to the 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 core action, then one high-value clarification of a returned field. 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?

An output schema exists, so return values needn't be enumerated, and the description still clarifies the one non-obvious field. For a single-parameter read tool this is close to complete; only the interaction with the whitelist/blacklist and update tools is left 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 fully documented in the schema (format hints, example, character rules), so the schema carries the parameter burden. The description adds no further meaning about the domain argument, which matches the baseline 3.

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

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

States a specific verb and resource ('Returns the spam settings') scoped to 'a domain', which is unambiguous. It does not name or distinguish itself from the sibling update_spam_settings (nor get_spam_whitelist/blacklist), so the sibling differentiation is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 read-only retrieval intent is implied by 'Returns', and the presence of update_spam_settings as a sibling makes the read/write split reasonably inferable. However, there is no explicit statement of when to use this versus update_spam_settings or the whitelist/blacklist getters, and no prerequisites (e.g. domain must exist on the account) are given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: wildcard patterns, case-insensitive matching, and that sender lists are shared account-wide across all domains — the last of which materially affects how results should be interpreted. It says nothing about result ordering or volume, but that is minor.

Agents need to know what a tool does to the 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, each carrying distinct information: purpose, semantics of the resource, matching rules, and account-level scope. 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?

With an output schema present and full parameter coverage, the description only needs to supply behavioral context, which it largely does. The one gap is the mild tension between the required `domain` argument and the statement that sender lists are shared account-wide, which an agent may need to reason about.

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

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

Schema description coverage is 100% for the single `domain` parameter, so the schema already explains format and constraints. The description adds no further meaning about how `domain` affects the returned entries — notably, it does not reconcile the required domain argument with the claim that lists are shared across all domains.

Input schemas describe structure but not intent. Descriptions should explain 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 first sentence names a specific verb and resource ('Lists the spam whitelist entries for a domain'), which is unambiguous and distinct from the add/remove whitelist siblings. It does not explicitly differentiate from adjacent read tools such as get_spam_settings or get_spam_blacklist, leaving that routing to the agent.

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

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

The description explains what whitelist entries do ('Whitelisted senders bypass spam filtering'), which implies when to inspect them, but gives no explicit when-to-use versus alternatives such as get_spam_settings or get_spam_blacklist. Usage is inferable 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 say this is a read-only, idempotent, non-destructive call, so the safety profile is covered. The description adds genuinely new context: the DNS propagation window is typically 5-15 minutes, and the returned record contains the exact TXT name, type, and value. It does not say whether the key is stable or rotates, which slightly limits 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?

Three sentences: what it returns, followed by an actionable workflow, then a note about the return payload. The return shape is mentioned after the workflow rather than up front, and the ellipses are minor, but every sentence carries real 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 parameters, a full annotation set, and an output schema, this description carries only what structured fields cannot: the DNS setup procedure and propagation timing. The one gap is whether the key is per-account or per-domain and whether it rotates, but for a simple read tool it is otherwise complete.

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

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

The tool takes no parameters, which is the baseline case for a 4. The empty schema leaves nothing to misinterpret, and the description correctly does not invent parameter-like behavior.

Input schemas describe structure but not intent. Descriptions should explain 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 domain verification key.' That is clearly distinct from get_domain, list_domains, and create_domain, though it never explicitly contrasts itself with them, so the differentiation comes from the resource name rather than from a stated comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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-to-use path: get this key, publish it as a TXT record at the registrar, wait for propagation, then call create_domain. create_domain is named as the downstream tool, but there are no explicit exclusions or guidance about re-fetching the key, e.g., whether it changes over time.

Agents often have multiple tools that could apply. Explicit usage 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 establish a safe, idempotent read. The description adds the pointer categories and per-entry contents, but gives no further operational context such as empty-result or pagination behavior; the return summary is also less essential because an 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?

Two short sentences front-load the operation and scope, then succinctly explain the alias/redirect model. There is no filler or unnecessary repetition of the safety 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 simple list operation with one fully documented required parameter, read-only annotations, and an output schema, this supplies the invocation-critical resource scope and result concepts. Additional operational details would be optional rather than necessary for correct selection and invocation.

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

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

Schema coverage is 100%, and the domain parameter already includes an example and syntax constraints. The description clarifies that this is the domain whose pointers are listed, but adds no parameter format or validation detail beyond the schema, so the baseline 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 gives a specific verb and resource: listing domain pointers attached to one domain, with pointers defined as aliases and redirects. That scope and the type/target distinction separate it from list_domains, get_domain, and the create/delete pointer 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 provides clear selection context: use it to inspect the aliases and redirects attached to a particular domain. It does not explicitly route agents to list_domains or get_domain for other needs, which keeps it from 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, and an output schema exists, so the description's return-shape sentence adds limited new information. It does not add useful behavioral context such as result volume, ordering, or pagination for accounts with many domains.

Agents need to know what a tool does to the 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 core action, with no filler. The example array partially duplicates the output schema, which is mildly redundant but harmless for a simple list tool.

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

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

For a zero-parameter read-only list tool backed by full annotations and an output schema, the description covers purpose, return shape, and sibling routing. Nothing an agent needs in order to select and call it 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 baseline is 4; there is nothing parameter-wise the description needs to explain and it correctly says nothing about arguments.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Lists all domains on the account") and immediately distinguishes the tool from its detail-oriented sibling get_domain, so an agent can tell the two apart 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?

It explicitly names the alternative ("Use get_domain for the details of a single domain"), giving a clear routing rule. It does not mention other list-style siblings such as list_domain_pointers or state a when-not condition, so it falls just short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description then adds genuinely useful behavior by enumerating the returned fields and explaining that quota 0 means unlimited. It doesn't cover pagination, ordering, or behavior for an unknown domain, keeping it out of the top band.

Agents need to know what a tool does to the 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, purpose first and return contents second, with no filler. The field enumeration is long but each item carries information an agent would otherwise have to discover from the output 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?

For a one-parameter read tool with an output schema already present, this is nearly complete. The only missing context is what happens if the domain is unknown or empty, and the description already over-delivers on return values.

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

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

Schema coverage is 100% and the single domain parameter is fully documented in the schema, so the description only echoes the scoping. It adds no format or validation detail beyond what the schema already says.

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

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

The description uses a specific verb and resource ("Lists the mailboxes") and scopes it ("under a domain"), which distinguishes it from get_email_account and list_forwarders. It stops short of naming the singular sibling it complements, so an agent must infer that get_email_account is for one mailbox.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance, no prerequisites (e.g., the domain must already be configured on this account), and no mention of alternatives such as get_email_account for a single mailbox. Usage is only implied by the phrase "under a domain."

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds the per-entry shape (alias/local part, full forwarder address, destination addresses), which is helpful context about what is returned, but it largely restates what the output schema already provides and says nothing about volume, pagination, or ordering.

Agents need to know what a tool does to the 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, with the scope ('all ... on a domain') front-loaded before the return-value detail. Every sentence earns its place.

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

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

For a one-parameter read tool with full schema coverage, an output schema, and safety annotations, the description covers purpose and return contents sufficiently. Minor gaps (no mention of result set size or ordering) are low-risk given the output schema and the small, domain-scoped nature of the resource.

Complex tools with many parameters or behaviors need more documentation. 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 in the schema with format constraints (letters, digits, hyphens, at least one dot). The description's phrase 'on a domain' is consistent but adds no meaning 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 with scope: 'Lists all email forwarders on a domain.' The resource (forwarders) is clearly distinct from siblings like list_email_accounts or list_domains, so an agent can distinguish it, 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?

Usage is only implied by the verb 'Lists' and the domain scoping. There is no explicit when-to-use, when-not-to-use, or reference to an alternative such as create_forwarder or delete_forwarder. For a simple read-only list tool this is adequate, but it leaves routing to inference.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description is not obligated to restate safety. It adds real context the annotations cannot: the required authentication mode, plus the meaning of a 403 response (missing reseller privilege or active impersonation), which lets an agent self-diagnose failure.

Agents need to know what a tool does to the 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 filler: purpose first, then the authentication constraint, then error interpretation. Each sentence carries distinct information an agent needs, and the most important fact (what the tool returns) 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 an output schema present, return-value detail is unnecessary, and with zero parameters there is nothing schema-adjacent to explain. The one thing structured fields cannot convey for this tool, the reseller-level auth requirement and its failure mode, is fully documented.

Complex tools with many parameters or behaviors need more documentation. 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 baseline a 4 applies. Nothing in the schema needs semantic expansion, and the description does not waste space inventing parameter guidance.

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

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

"Lists the names of all packages defined under the reseller account" gives a specific verb (lists) and resource (packages) plus a scope (reseller account, names only). The "names only" framing implicitly separates it from get_package, but no sibling is named explicitly, so an agent must infer that distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear call-context guidance: invoke while authenticated as the plain reseller, not during user impersonation. It does not state when to prefer get_package or list_reseller_users instead, so routing between siblings is left to inference, but the credential condition that actually determines success is spelled out.

Agents often have multiple tools that could apply. Explicit usage 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 genuine behavioral context the annotations cannot express: the required credential mode and the meaning of a 403. It says nothing about result volume or ordering for large reseller accounts, which is the remaining gap.

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

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

Three short sentences: what it returns, then credential requirement, then error interpretation. The resource and scope are front-loaded with 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?

For a zero-parameter read tool with full annotation coverage and an output schema, the only things an agent needs beyond the schema are the auth mode and the failure meaning, both of which are stated. Nothing required for a correct first call 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?

There are zero parameters, so the baseline is 4; the schema has nothing for the description to clarify. The description correctly adds no parameter chatter and instead spends its words on authentication scope.

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

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

The description uses a specific verb and resource ('Lists the usernames of all users under the reseller account') and scopes the result to usernames only, which separates it from mailbox-listing siblings like list_email_accounts. It stops short of naming the closest sibling (get_reseller_user) as the single-user alternative, so differentiation is implied rather than 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?

It gives an explicit precondition (call while authenticated as the plain reseller username) and an explicit when-not (not while impersonating a user), plus a diagnostic for the 403 case. That is strong context, though it never names an alternative tool for retrieving a single user's details.

Agents often have multiple tools that could apply. Explicit usage 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, but the description adds genuinely new context: matching is case-insensitive so stored casing may differ, and the blast radius spans every domain on the account. It does not say whether removal requires prior existence or what happens on a miss, though idempotentHint covers that.

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

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

Three short sentences, each carrying distinct information, with the core action front-loaded. No redundant restatement of the title or 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?

Output schema and annotations are rich, so the description does not need to cover safety or return shape. The remaining gap is the role of the required `domain` argument given account-wide tooling, plus any permission requirements, which an agent would want before invoking a destructive operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description does add one piece of meaning beyond the schema, namely that entry matching is case-insensitive. However, it never explains why a required `domain` parameter exists when the list is described as shared across all domains, which leaves the most confusing parameter unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 spam blacklist"), which cleanly separates it from add_spam_blacklist_entry and the whitelist siblings. It does not explicitly name a sibling alternative, but the resource is unambiguous.

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

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

Usage is only implied by the operation itself; there is no when-to-use vs. add_spam_blacklist_entry / remove_spam_whitelist_entry guidance and no stated prerequisites. The account-wide scope note reads more as a warning than as routing 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 declare destructiveHint=true, idempotentHint=true, and non-read-only, so the safety profile is covered. The description adds genuinely new behavior: case-insensitive matching means the stored casing may differ, and sender lists are shared across all domains on the account, so the blast radius is wider than the per-domain `domain` parameter suggests.

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

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

Three short sentences, purpose front-loaded, each adding a distinct fact (action, matching semantics, scope). Nothing is redundant or padded.

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

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

An output schema exists and annotations cover safety, so the description's job is mostly matching and scope semantics, which it delivers. It leaves one ambiguity unresolved: what happens when the entry is not found (relevant given idempotentHint) and how the required `domain` relates to an account-wide list.

Complex tools with many parameters or behaviors need more documentation. 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 `domain` and `entry` are already documented, including the wildcard pattern syntax. The description only adds the case-insensitivity note, which is useful but does not clarify the domain-vs-shared-list interaction (why `domain` is required when the list is account-wide). 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 first sentence names a specific verb and resource ('Removes an entry from the spam whitelist'), which is unmistakable against siblings like add_spam_whitelist_entry or remove_spam_blacklist_entry. It doesn't explicitly route against those siblings, 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?

Removal intent is implied by the verb, and the account-wide scope hint nudges the agent to check before acting. There is no explicit when-to-use/when-not guidance or named alternative (e.g., 'use get_spam_whitelist first to find the exact entry').

Agents often have multiple tools that could apply. Explicit usage 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/idempotent/non-destructive profile, and the description adds meaningful consequence detail beyond them: `fail` bounces mail and `blackhole` silently discards it, which is exactly the operational risk an agent needs. It does not say that the setting replaces any existing catch-all configuration, which is the main residual gap.

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

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

Two sentences, zero filler, with the core behavior front-loaded and the conditional constraint placed second. 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?

With an output schema present and full parameter documentation, the description needs only to convey purpose and mode semantics, which it does. It is nearly complete; only the replace-existing-configuration behavior and permission expectations are left 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 schema already spells out both the enum meanings and the conditional requirement for `address`, so the description largely restates structured data. It adds no format or example detail beyond what the schema provides, making baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Sets') and resource ('how the domain handles mail addressed to nonexistent local parts') and then defines all three modes, so an agent immediately knows this is the write counterpart to get_catch_all in the sibling list.

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

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

It gives the conditional rule for `address` (required for type `address`, omitted otherwise) which is real usage guidance, but it never states when to reach for this tool versus get_catch_all for reading the current configuration, and mentions no prerequisites or account permissions.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description does not need to argue idempotency. It does add useful context beyond them: that this is a 'pure state change' and that the domain, mailboxes, and their settings are preserved, which is exactly the reassurance an agent needs before flipping hosting off.

Agents need to know what a tool does to the 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 earning its place: what it does, how to invoke each direction, and what is preserved. The most important constraint (non-destructive state change) is stated up front.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema present and annotations covering safety and idempotency, the description only needs to explain the state semantics and preservation behavior, which it does. It could go further by noting whether MX/DNS records must already be in place for enabled=true to actually deliver mail.

Complex tools with many parameters or behaviors need more documentation. 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 are already documented. The description reinforces the enabled semantics with operational framing ('have MXroute handle mail', 'pause mail hosting') but adds no format or edge-case detail beyond the schema, 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?

The description uses a specific verb and resource ('Enables or disables mail hosting for a domain') and its framing of enabled=false as a pause rather than a deletion implicitly separates it from destructive siblings like delete_domain or delete_email_account. It never names an alternative explicitly, which keeps it 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?

It clearly states the meaning of each parameter value (true = MXroute handles mail, false = pause), which tells the agent how to call it, but gives no guidance on when to choose this tool over delete_domain or create_domain, and no prerequisites such as DNS readiness.

Agents often have multiple tools that could apply. Explicit usage 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, it discloses blast radius that destructiveHint=false alone would not convey: the quota and limits of every domain under the user can change. It also documents the 422 failure mode and the authentication identity requirement, both of which are operationally essential and absent from 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?

Three tight sentences, front-loaded with the action, then impact, then error and auth notes. No filler or restatement of the title, and each 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?

The tool has an output schema, full annotation coverage and fully described parameters, so the description only needed to add behavior, failure modes and auth context, which it does. Nothing an agent needs to invoke this correctly appears to be missing.

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

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

Schema description coverage is 100%, with both username and package documented including format and pattern constraints, so the schema already carries parameter meaning. The description adds only the cross-reference that package names come from list_packages and that a bad value surfaces as 422, which is marginal over the schema baseline.

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

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

States a specific verb and resource ("Moves a reseller user to a different package") plus the return value ("returns the updated user"). It is clearly distinct from update_reseller_user and from list_packages, which it names only as a validation reference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 trigger (changing a user's package) and an explicit prerequisite: authenticate as the reseller with the plain reseller username, not while impersonating a user. It also routes the agent to list_packages when a 422 is returned. It stops short of contrasting with update_reseller_user, which an agent might otherwise consider for the same intent.

Agents often have multiple tools that could apply. Explicit usage 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=false, idempotent=true, destructive=false; the description confirms the non-destructive semantics ("without deleting data") and adds real context beyond them — the reseller-authentication requirement and the 404-means-not-found behavior. Restating "repeating the call is harmless" largely duplicates idempotentHint, which keeps this from a 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?

Four short sentences, each carrying distinct information: effect and scope, idempotency, authentication context, and error semantics. The most decision-critical facts (what it does, what it does not destroy) are front-loaded with no filler.

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

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

An output schema exists, so return values need not be explained, and the description covers the mutation's effect, safety profile, auth precondition, and the main error case. Minor gaps remain — nothing about whether existing sessions are terminated or how to reverse the suspension — but nothing required for a correct call 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 fully documented in the schema, so the baseline is 3. The description adds auth-context meaning (the value is paired with reseller-level, non-impersonated authentication) but no format or disambiguation detail beyond what the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain 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 reseller user") plus the effect ("blocking their access without deleting data"), which implicitly separates it from delete_reseller_user and unsuspend_reseller_user. It never names those siblings explicitly, so an agent must infer the routing rather than being told 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?

Gives a concrete invocation condition: call while authenticated as the reseller (plain reseller username), not while impersonating a user. That is exactly the kind of auth-context guidance that prevents failed calls. It stops short of naming the alternative tools (unsuspend_reseller_user for reversal, delete_reseller_user for removal), so when-not-to-use 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=false, idempotentHint=true and destructiveHint=false; the description adds the authentication-mode constraint (reseller vs impersonated user), which annotations cannot express, plus the 404 semantics. The idempotency sentence largely restates the idempotentHint annotation, so the added value is real but partly duplicative.

Agents need to know what a tool does to the 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 effect, followed by idempotency and the auth constraint. No filler or redundant restatement of the 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 single-parameter mutation with full annotations and an output schema, the description covers effect, idempotency, auth mode and the main error case. The only missing piece is the exact meaning of the username argument relative to the acting reseller.

Complex tools with many parameters or behaviors need more documentation. 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% (pattern, length bounds, and a description are all present), so the baseline is 3. The description adds only the framing that the call is made as the reseller, and does not clarify whether `username` names the target reseller user or the acting reseller — a small residual ambiguity the schema does not resolve.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Reverses the suspension of a reseller user, restoring their access.' This clearly separates it from the sibling suspend_reseller_user and from the CRUD siblings (get/update/delete_reseller_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 concrete usage context: call while authenticated as the reseller (plain reseller username), not while impersonating a user. It also notes the 404 case for a non-existent user. What it lacks is an explicit pointer to the suspend counterpart or any precondition such as 'only meaningful if the user is currently suspended'.

Agents often have multiple tools that could apply. Explicit usage 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=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new behavior: partial-update semantics ('Only provided fields change; omitted fields keep their current values') and the failure mode for passwords ('field-specific errors naming the password field'). It does not mention required permissions or what happens when the domain/local part is not found, so it stops short of full disclosure.

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

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

Four compact sentences with the core purpose front-loaded and no filler. Slight redundancy is the only flaw: the 8-72 character password constraint is already in the schema and is partially repeated here, though it is attached to new error-behavior 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?

An output schema exists, so return values need not be explained, and the mutation semantics are covered. However, for a partial-update mutation with five parameters there is no mention of authorization requirements, domain-existence preconditions, or side effects of lowering a quota below current usage — gaps an agent would want closed.

Complex tools with many parameters or behaviors need more documentation. 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 every parameter including ranges and patterns; the baseline is 3. The description does add two pieces of meaning beyond the schema: that unspecified optional fields are left untouched, and that the 'user' local part is resolved case-insensitively. The password length/strength restatement duplicates 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?

Opens with a specific verb+resource plus the exact mutable fields: 'Updates a mailbox's password, storage quota, or daily send limit.' That clearly distinguishes it from create_email_account, get_email_account and delete_email_account in the sibling list, though it never names an alternative 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 implied rather than stated: the agent can infer this is the tool for changing an existing mailbox's password/quota/limit. There is no explicit 'use this instead of X when Y', no stated prerequisite that the domain and mailbox must already exist, and no guidance on when not to call it.

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

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

Annotations declare readOnly=false and idempotent=true but say nothing about scope or failure handling; the description supplies both — the change affects every user on the package (blast radius) and a 404 means the package does not exist. It also flags the unit mismatch with the reseller-user quota endpoint, which no annotation 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?

Four short, front-loaded sentences covering mutation semantics, unit caveat, blast radius, auth requirement, and error meaning — no filler. Each clause carries information an agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema present and full schema coverage, the description need not explain return values, and it fills the remaining gaps that matter for a mutation tool: auth mode, partial-update behavior, scope of effect, units, and 404 meaning.

Complex tools with many parameters or behaviors need more documentation. 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 each field and its "omit to keep current value" behavior, giving a baseline of 3. The description adds genuine meaning on top: the quota unit is GB here versus MB on the reseller-user endpoint, preventing a costly unit error.

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

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

"Updates a package's limits" is a specific verb plus resource, immediately narrowed by "only provided fields are sent, the rest keep their current values," which establishes partial-update semantics. It also distinguishes itself from the reseller-user quota endpoint, so an agent can separate it from update_reseller_user or create_package without opening another schema.

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

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

The description gives a clear prerequisite and an explicit exclusion: call while authenticated as the reseller with the plain reseller username, not while impersonating a user. It does not name sibling operations (create_package, get_package, delete_package) as alternatives, but the operational context for correct invocation is unambiguous.

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

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

Annotations already declare idempotency and non-destructiveness, yet the description still adds material context beyond them: partial-update semantics ('only provided fields are sent; the rest keep their current values'), a required authentication mode, and the meaning of a 404. The 404 note is exactly the kind of error-behavior disclosure that prevents blind retries.

Agents need to know what a tool does to the 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 core action first and the auth constraint and error semantics layered after. Nothing is repeated for padding.

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

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

An output schema exists, so return values need not be explained; annotations cover the safety profile. The remaining gaps an agent would care about for this mutation — which auth context to use, what happens to unmentioned fields, and how to interpret a 404 — are all covered.

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

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

Schema description coverage is 100%, with patterns and the 'omit to keep current' semantics already documented per parameter. The description restates partial-update behavior but adds no syntax or format 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 (Updates) and resource (a reseller user) plus the exact mutable surface (disk quota and/or password). That field enumeration distinguishes it from set_reseller_user_package and suspend/unsuspend_reseller_user without needing to name them.

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

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

Gives a real usage condition: 'call while authenticated as the reseller (plain reseller username), not while impersonating a user' — a genuine precondition an agent would otherwise get wrong. It lacks explicit routing to sibling alternatives (e.g. use set_reseller_user_package for package changes), so it stops short of 5.

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

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

The annotations only cover safety and idempotency, so the description carries most of the weight: it explains the practical consequence of the value (more or less mail deleted), the account-wide serialization of writes, and the recovery procedure after a 503. It stops short of stating auth or permission requirements, so it earns a 4 rather than a 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?

Two dense sentences with the core action and its value semantics first, followed by the concurrency and retry caveat. There is no filler, and every clause adds 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?

With only two fully documented parameters, annotations covering the safety profile, and an output schema handling return values, the description covers everything an agent needs: what the write does, how the value behaves, and how to recover from a failed save. No material gap remains for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning beyond the schema by explaining what direction the high_score value moves deletion aggressiveness. The domain parameter gets no extra explanation in the description, so it does not reach a 5.

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

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

The description states a specific verb and resource: it sets the spam auto-deletion threshold for a domain. The direction of the setting ('Lower values delete more aggressively; higher values keep more mail') lets an agent distinguish it from the read-only sibling get_spam_settings 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?

It implies usage through the setting semantics and the retry advice, which implicitly points to re-reading via get_spam_settings, but it never explicitly names that alternative or states when not to use this tool. There is no mention of prerequisites such as domain ownership or package requirements.

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