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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them: it fixes the scope to the authenticated user and implies an auth dependency (a configured API key), which is behavioral context the annotations do not carry.

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

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

Two tight sentences: the return payload is front-loaded, and the usage hint follows. Every clause earns its place 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?

There is no output schema, so the description must carry the return contract, and it names the four key fields. It could go one step further by noting what happens on an invalid/absent key (error vs. empty result), which is exactly the scenario the usage hint points at.

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

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

Zero parameters, so there is nothing for the description to disambiguate — the baseline is 4. The description correctly does not invent parameters.

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

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

States a specific verb and resource ('Return the authenticated SimpleLogin user's info') and enumerates the concrete fields returned (name, email, premium/trial status, alias limit). The enumerated payload distinguishes it from account_get_stats and settings_get without the agent 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 a clear intended use case — 'a quick check that the configured API key is valid' — which tells the agent when this tool is the right pick. It stops short of naming alternatives or when-not conditions (e.g., vs. account_get_stats or settings_get).

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

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

Annotations already declare readOnly/ idempotent/ non-destructive, so the safety profile is covered. The description adds useful scope context that annotations do not: the counters are lifetime and aggregated across all aliases. It stops short of any pagination or refresh semantics, which are not relevant for a single summary object.

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

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

Two tight sentences, front-loaded with the primary action and field list, then the disambiguation pointer. Every clause earns its place with no 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?

There is no output schema, so the description carries the burden of explaining return values and it does so by naming each counter and its meaning. Combined with the sibling pointer, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is no parameter surface to document. Baseline 4 applies; the description correctly implies a straightforward no-argument call.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Return the account's lifetime counters') and enumerates the exact counters returned (nb_alias, nb_forward, nb_reply, nb_block). It also names the sibling it is not, allowing an agent to distinguish it from alias_activity_list 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?

Explicitly routes the agent: use this for account-wide totals and use alias_activity_list for the per-alias breakdown behind these totals. The when-to-use and the alternative are both stated directly.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so safety is covered. The description adds real behavior beyond that: results are ordered most-recent-first, capped at 20 per page, and each entry carries an action type, from/to addresses, a Unix timestamp, and a reverse-alias address. Auth requirements and failure modes are still 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?

Two dense sentences front-loaded with the resource and scope, then pagination mechanics and the reason for it. No filler or restated title text.

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

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

With no output schema, the description compensates by enumerating the returned entry structure, the sort order, and the page size, and explains the pagination contract. That is everything an agent needs to call and consume this tool correctly.

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

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

Schema coverage is 100% (baseline 3), and the description goes further by explaining page_id is zero-based and that the per-page cap is why paging is required instead of expecting a full dump. alias_id gains no extra semantics beyond the schema's own wording.

Input schemas describe structure but not intent. Descriptions should explain 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 (List) plus the exact resource (forward/reply/block activity history) scoped to a single alias. This clearly separates it from alias_list, alias_get, and alias_update in the sibling set 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 clear operational context: use page_id for pagination and page through rather than expecting full history in one call. It does not name an alternative tool or state an explicit when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world write, so the safety profile is covered. The description adds genuinely useful non-annotation context: the required dependency on alias_options_get, the can_create precondition, and the verbatim pass-through requirement for signed_suffix. It stops short of describing failure behavior when can_create is false or what a duplicate-prefix attempt does.

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

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

Two sentences, no filler, and the prefix/suffix framing is front-loaded before the workflow. The second sentence is dense and slightly run-on, but every clause carries a required action.

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

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

For a mutation tool with no output schema, the description covers the full call workflow and preconditions well. It omits what the tool returns (e.g. the new alias id) and how errors surface, which would help an agent chain follow-up calls, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by sourcing parameters to other tools (signed_suffix from alias_options_get, mailbox_ids from mailbox_list) and flagging name/note as optional. The schema alone states signed_suffix's origin, so the added value is modest but real.

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

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

States a specific verb+resource ('Create a custom SimpleLogin alias') and immediately narrows scope with 'with a chosen prefix and suffix', which distinguishes it from the sibling alias_create_random. 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?

Gives an explicit prerequisite chain: call alias_options_get first, confirm can_create is true, then pass that exact signed_suffix along with mailbox_ids obtained from mailbox_list. This is when-to-use and ordering guidance with named alternatives, not 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 readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation/no-retry profile is covered. The description adds that the address is system-generated and that note/hostname are optional attachments, but says nothing about quota consumption, account requirements or what object is returned.

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

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

Three compact sentences that front-load the core action before detailing mode and optional fields. Every clause carries information; only the mode explanation slightly duplicates 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?

For a 3-optional-parameter creation tool whose annotations carry the safety profile and whose schema is fully described, the description covers action, address generation variants and optional attachments. The only minor gap is not indicating what the created alias response contains, which is defensible given no output schema is declared.

Complex tools with many parameters or behaviors need more documentation. 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 already 100%, so mode, note and hostname are fully documented structurally. The description restates mode semantics and the 'omit for account default' behavior without adding syntax or format detail beyond the schema — 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 ('Create a new random SimpleLogin alias with a system-generated address'), and the phrase 'random'/'system-generated' implicitly separates it from alias_create_custom. It never names that sibling explicitly, so the differentiation requires a small inference.

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

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

Explains the mode options and that omitting mode falls back to the account default, which is useful selection guidance at the parameter level. However, it gives no explicit when-to-use vs. alias_create_custom or any prerequisite/auth context, leaving the alternative routing 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 flag destructiveHint=true and idempotentHint=false, but the description goes further by concretely describing the consequence: deletion is irreversible and mail sent to the address afterward is rejected. It also discloses the required confirm=true acknowledgement, adding real behavioral context beyond the structured hints.

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

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

Three tightly written sentences with zero filler. The irreversible nature is front-loaded, followed by the safer alternative and then the parameter requirement.

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

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

For a two-parameter destructive tool with no output schema, the definition covers purpose, consequence, alternative routing, and the required confirmation flag. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema (confirm as an explicit acknowledgement, alias_id as the numeric id). The description restates the confirm requirement and the id lookup but adds no syntax or format detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a SimpleLogin alias by id'), including the permanence qualifier and lookup key. It is immediately distinguishable from the sibling alias_set_enabled, which 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?

Provides explicit routing guidance: 'Prefer alias_set_enabled with enabled=false to merely disable an alias.' This names both the alternative tool and the condition that should select it, leaving nothing 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context on what the returned entries mean (is_custom user-owned vs SimpleLogin public), but says nothing about auth requirements, pagination, or result size.

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

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

A single front-loaded sentence that states the resource and the meaning of the key returned flag, with no filler. Every clause earns its place.

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

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

For a zero-parameter, read-only listing tool with annotations covering safety, the description supplies what is missing (what the list contains and what is_custom means). No output schema exists, but the description adequately characterizes the return.

Complex tools with many parameters or behaviors need more documentation. 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 rubric the baseline is 4. There is no parameter syntax or filter information an agent would need, and the description does not need to document any.

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

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

Clear specific verb+resource: 'List the email domains available for creating aliases on this account.' It also clarifies the is_custom flag semantics. It does not, however, explicitly distinguish itself from the sibling custom_domain_list, which an agent might otherwise confuse it 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?

Usage is only implied by the phrase 'available for creating aliases'; there is no explicit when-to-use, when-not-to-use, or routing to sibling tools such as custom_domain_list or alias_create_random. Minimum viable but with clear gaps.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld behavior, so the safety profile is covered. The description adds what data comes back (note, mailboxes, enabled/pinned, PGP status, counters), but says nothing about auth needs, error behavior for unknown ids, or rate limits.

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

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

One sentence, front-loaded with the verb and resource, with the identifying detail immediately after. Nothing is padded or redundant.

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

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

For a single-parameter read tool with no output schema, the description usefully enumerates the returned fields, which compensates for the missing output schema. Only the lack of any statement about failure modes or usage context keeps it from being 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 coverage is 100% and the single alias_id parameter is fully documented in the schema, so the description's 'by its numeric id' adds no syntax or constraint information beyond it. Baseline 3 is appropriate when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain 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 (get details of a single SimpleLogin alias) and scopes it to one record by numeric id, which implicitly separates it from alias_list. An agent can tell it apart from sibling list tools 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?

Usage is only implied: the id-based lookup makes it clear this is for when you already have an alias id, but the description never states when to prefer it over alias_list or alias_options_get, nor any prerequisites such as needing the id from a prior listing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered externally. The description adds only the page-size/pagination convention, which the schema largely mirrors, and says nothing about result ordering, total counts, or behavior past the last page.

Agents need to know what a tool does to the 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 tight sentence front-loads the core action and page size, then layers pagination and filtering in descending order of importance. No filler, no repetition of the tool name, nothing that could be cut.

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

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

For a read-only, no-required-param list tool whose annotations already cover safety, the description supplies scoping, pagination, and filter semantics. The only real gap is that no output schema exists and the description never characterizes the returned alias objects, which an agent would otherwise have to discover empirically.

Complex tools with many parameters or behaviors need more documentation. 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, including the enum values and the zero-based page semantics. The description restates the same meanings (query fields, filter states, page start) without adding syntax, defaults, or interaction rules, 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 ('List the user's SimpleLogin email aliases'), which cleanly separates it from alias_domains_list, mailbox_list, and alias_activity_list by resource. It never contrasts itself with alias_get (single alias) or notes the list-vs-single distinction, so full sibling differentiation is not achieved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 operating context: pagination via page_id starting at 0, 20 per page, and optional filtering by enabled/disabled/pinned or free-text search. It does not state when to prefer alias_get instead, nor any exclusion or prerequisite, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: it enumerates the returned fields and the workflow dependency on alias_create_custom. It does not mention auth requirements or rate limits, but for a read-only options endpoint that is a minor omission.

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

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

A single sentence that front-loads the purpose, then lists the return contents and the downstream requirement in order of importance. No filler.

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

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

With no output schema, the description must carry the return-value burden, and it does by naming can_create, the prefix suggestion, and suffixes with signed_suffix. Combined with the annotation-declared safety profile, an agent has enough to call it correctly; only auth/error behavior is unaddressed.

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

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

There is a single optional hostname parameter and schema coverage is 100%, so the schema already documents it. The description repeats its purpose ('Pass the target website hostname to tailor the suggestion') but adds no format, default, or syntax detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the options needed to create a custom alias') and enumerates exactly what comes back: can_create, a prefix suggestion, and suffixes with signed_suffix. This clearly separates it from sibling creation tools like alias_create_custom, which it explicitly references.

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

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

Positions the tool as the prerequisite step for alias_create_custom by noting the signed_suffix is 'required by alias_create_custom', and tells the caller to pass the target hostname. It gives clear usage context but names no when-not condition or alternative for retrieving alias options.

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

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

Annotations already declare idempotentHint and destructiveHint; the description goes beyond them by explaining the actual effect of disabling (silent mail blocking with no data loss) and by stating the return value. The idempotency sentence largely restates idempotentHint=true, and no permission/auth requirements are mentioned, keeping it 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, front-loaded with the core action, then behavior, then idempotency, then return. No filler or restated title, and every sentence carries distinct information.

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

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

For a two-parameter toggle with no output schema, the description covers the action, the boolean mapping, the side effect of disabling, idempotency, and the returned value. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and both parameters are already documented, including the boolean meaning. The description's 'Pass enabled=true to enable or enabled=false to disable' duplicates the schema's own 'Desired state' text and adds no new syntax or edge-case guidance, 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 ('Set a SimpleLogin alias to a specific enabled state') and the exact control it exposes (enable vs disable). It also draws a boundary against the delete sibling by noting the alias is blocked 'without being deleted', so an agent can separate it from alias_delete/alias_update 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 conditions for use by spelling out the true/false semantics and the consequence of a disabled state, which is enough to choose it over alias_delete. It never names an alternative tool or states an explicit 'use X instead' exclusion, so it falls 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?

With destructiveHint already true, the description still adds real value: partial-update semantics ('Only the provided fields change'), validation behavior ('a call that changes nothing is rejected without contacting SimpleLogin'), and the concrete destructive consequence ('Replacing mailboxes can stop future mail from landing in removed mailboxes'). That is specific consequence disclosure rather than restating annotations.

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

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

A single front-loaded paragraph with no filler sentences; each clause carries a constraint or consequence. Slight redundancy in re-listing the field names already documented in the schema, which keeps it from a 5.

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

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

For a 7-parameter mutation tool with no output schema, it covers partial-update behavior, argument exclusivity, no-op rejection, and the destructive mailbox effect. It stops short of error/auth behavior (e.g. invalid alias_id or nonexistent mailbox ids), but the essentials for a correct call are present.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by declaring the mailbox_id/mailbox_ids mutual exclusion and clarifying that only supplied fields are replaced, semantics the schema descriptions do not state.

Input schemas describe structure but not intent. Descriptions should explain 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 (update) and resource (existing alias) and enumerates the mutable fields. It is clearly distinguishable from siblings like alias_create_random, alias_delete, and alias_set_enabled 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 concrete precondition ('Provide at least one field to change') and a no-op rejection rule, plus the mailbox_id/mailbox_ids exclusion. It does not, however, route the agent to alternatives such as alias_set_enabled for toggling enablement, which is the main missing usage cue.

Agents often have multiple tools that could apply. Explicit usage 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 (readOnly=false, destructive=false, openWorld=true), and the description adds value beyond them: the response semantics (reverse_alias_address, existed=true meaning nothing was created) and the premium-plan requirement. This is meaningful behavioral context an agent would not get from structured fields alone.

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

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

Purpose is front-loaded, followed by input format, response semantics, and a caveat. Each sentence carries distinct information with no filler, though it is slightly dense in the final sentence.

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

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

Both required parameters are documented, and with no output schema the description compensates by explaining the meaningful return fields and the existed flag. Nothing an agent needs to invoke or interpret this call correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds usable syntax guidance: bare address vs RFC-5322 display form with a concrete example. That goes beyond the schema's terse parameter descriptions.

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

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

States a specific verb and resource ('Create a contact (reverse alias) on an alias') and explains the underlying concept so an agent understands the object being created. It is clearly distinguishable from siblings like contact_list, contact_set_blocked, and contact_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use case ('so the user can send mail from the alias to that contact while keeping their real mailbox hidden'), which tells the agent when this tool applies. It stops short of naming alternatives or exclusions, but the context is unambiguous.

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

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

Annotations declare destructive/irreversible, but the description goes further by spelling out the concrete consequences: the reverse-alias address stops working and the correspondence history is removed. It also states the required confirm=true acknowledgement, adding context the annotations do not carry.

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

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

Three sentences, front-loaded with the destructive action and consequence, then the safer alternative, then the guardrail. 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 destructive, no-output tool with full annotation coverage, the description supplies everything an agent needs: irreversibility, data loss scope, the alternative path, and the confirmation guard.

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

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

Schema coverage is 100% and both parameters are already documented in the schema, including the const:true semantics of confirm. The description only restates the acknowledgement requirement, adding little beyond structured data.

Input schemas describe structure but not intent. Descriptions should explain 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 (permanently delete), resource (contact / reverse alias), and identifier type (numeric id). It is immediately distinguishable from siblings like contact_set_blocked or alias_delete.

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

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

Explicitly routes the agent: 'To merely stop receiving mail from the contact, prefer contact_set_blocked with blocked=true instead.' It names the alternative and the condition that selects it, plus the confirm=true prerequisite.

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

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

Annotations already establish the read-only, idempotent, non-destructive profile, so the bar is lower; the description goes further by disclosing pagination granularity (20 per page), the zero-based page origin, and the exact fields each returned contact carries. It does not mention ordering or rate limits, but it meaningfully adds behavioral context beyond the annotations.

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

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

Front-loaded with the core purpose, then the contact anatomy and finally the pagination convention; every sentence contributes. It is slightly dense in the middle clause enumerating fields, but there is no filler.

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

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

For a simple two-parameter read-only list with no output schema, the description is essentially complete: it explains scope, page size, page origin, and the shape of the returned records. Ordering and empty-result behavior are the only unstated details.

Complex tools with many parameters or behaviors need more documentation. 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 itself already states that page_id is zero-based, defaults to 0, and yields 20 contacts per page, so the description's pagination note largely duplicates it. The only marginal addition is framing alias_id as a single-alias scope rather than a general filter.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List the contacts ... for a single SimpleLogin alias') and immediately clarifies what a contact is (a reverse alias). This clearly separates it from siblings like contact_create, contact_set_blocked, and contact_delete, which act on the same object.

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

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

The description implies when to use it by scoping the operation to a single alias, but never states when to prefer it over alternatives (e.g. contact_create for adding, contact_set_blocked for toggling forwarding) or any prerequisite for holding a valid alias_id. Usage is inferable rather than explicit.

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

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

Annotations already declare idempotentHint=true, destructiveHint=true, and readOnlyHint=false, so the mutation/safety profile is covered. The description adds genuine value beyond that: it explains why alias_id is required (reading current state first), confirms a same-state call is a no-op, and states the returned block_forward field, which no output schema provides.

Agents need to know what a tool does to the 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 three sentences are front-loaded with the core action, then usage semantics, then the requirement and return value. Every sentence earns its place and nothing is redundant.

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

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

For a 3-parameter mutation tool with no output schema, the description supplies the missing pieces: the reason for the required alias_id, the no-op idempotent behavior, and the return field. Combined with annotations covering the safety profile, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents all three parameters. The description goes further by explaining the semantic role of alias_id (the contact belongs to it, needed for the read-before-write) and the boolean's meaning, adding meaning beyond the field descriptions.

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

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

The description names a specific operation (set/unset forwarding block from a contact to its alias) with a clear verb+resource. It is unambiguous and distinct from the surrounding contact_list/contact_create/contact_delete siblings, though it does not explicitly reference any of them for contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 how to use the tool by mapping blocked=true/false to the intended outcome (stop mail vs. allow it) and explains the no-op case. There is no explicit 'when-not' guidance and no alternative is named, but no real alternative exists among the siblings, so the context is adequately clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. With no output schema, the description carries the return-shape burden and does so well by listing the fields returned. It omits pagination/ordering behavior, which is a minor gap for a list tool.

Agents need to know what a tool does to the 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 resource and field enumeration before the downstream-tool pointer. Every clause earns its place and nothing is redundant.

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

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

For a zero-parameter read-only list with no output schema, the description supplies the returned fields and points to the tools that consume the ids. It lacks pagination or result-ordering details, but is otherwise sufficient to invoke and use correctly.

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

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

The tool takes no parameters, so there is no parameter semantics to clarify — the baseline of 4 applies. The description doesn't need to document inputs and correctly focuses on output shape instead.

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

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

States a specific verb (List) plus resource (custom domains) and enumerates the returned fields, including id, verification status, and recipient mailboxes. This distinguishes it clearly from siblings like alias_domains_list and mailbox_list 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?

The second sentence names the downstream tools (custom_domain_update, custom_domain_trash_list) and conditions their use on ids returned here, which is clear workflow context. However, it doesn't state when to choose this over alias_domains_list or other list tools, so no explicit alternatives/exclusions 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 cover read-only/idempotent/non-destructive, so the bar is lower; the description still adds real context by disclosing the catch-all recreation behavior and that the endpoint has no server-side pagination and is locally paged. It does not mention auth requirements or rate limits, but discloses the key non-obvious behavioral trait.

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

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

Three sentences, each earning its place: purpose first, then why the trash exists (behavior), then pagination mechanics. Front-loaded and free of redundancy despite repeating a few schema facts.

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

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

With no output schema, the description compensates by naming the return fields (alias address and Unix deletion timestamp) and specifying the pagination contract. Nothing needed to call this read-only list tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents page_id and limit defaults/bounds; baseline would be 3. The description slightly exceeds baseline by explaining that pagination is local because the upstream endpoint lacks server-side paging, which adds meaning the schema cannot convey.

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

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

States a specific verb (List) and a precisely scoped resource (a custom domain's deleted aliases / trash), and no sibling tool covers trash listing, so it is immediately distinguishable. The parenthetical '(its trash)' removes any ambiguity about what 'deleted aliases' means.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance: audit what was removed, or verify an address is in the trash before reusing it. It does not name an alternative sibling or state exclusions, but the behavior rationale (catch-all not silently recreating) effectively frames the use case.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description adds real value beyond them: it explains partial-update semantics ('Only the provided fields change'), the no-op rejection, that the updated domain is returned, and specifically warns that disabling catch_all or replacing mailbox_ids 'can stop future delivery', naming the concrete harm.

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

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

The description is front-loaded with the core action, then walks each field efficiently in one sentence, and ends with the risk warning. It is dense but largely earns its length; the field glosses partially duplicate the schema descriptions, which is the only mild waste.

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

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

With no output schema, the description compensates by stating the updated domain is returned, and it covers partial-update behavior and destructive side effects. For a 5-param update tool that is essentially complete, though it doesn't mention auth/permission requirements that an openWorld mutation might entail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by cross-referencing mailbox_list as the source of ids, restating the 1–20 bound, and framing mailbox_ids as a full replacement rather than an append. This adds operational meaning the schema alone doesn't convey.

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

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

The description opens with a specific verb and resource ('Update a custom domain') and enumerates exactly which fields can change, so the agent knows the tool's scope immediately. It does not explicitly differentiate itself from siblings like custom_domain_list or custom_domain_trash_list, though none of those overlap in function.

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

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

It states a clear precondition ('Provide at least one change') and clarifies that a no-op call 'is rejected without contacting SimpleLogin', which tells the agent when a call is valid. It does not name alternative tools or describe when an agent should prefer a different operation, so it stops short of full when/when-not 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 the mutation profile (readOnly=false, destructive=false, openWorld=true), and the description adds substantial non-obvious behavior: a verification email is sent, the mailbox starts unverified, and it cannot own aliases or become the default until the link is clicked. This is exactly the kind of side-effect detail the schema cannot convey.

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

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

Front-loads the core action, then layers the verification consequence, the cross-reference to mailbox_list, and the plan caveat. Every sentence earns its place 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?

No output schema exists, but the description compensates by explaining the async verification outcome and pointing to mailbox_list for status. For a single-parameter creation tool, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the schema already documents the email parameter including its role in receiving the verification email. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb (Add) and resource (mailbox), and even disambiguates the concept by defining it as 'a real email address that receives alias mail.' This clearly separates it from siblings like mailbox_list, mailbox_update, and mailbox_delete.

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

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

Provides clear operational context: it names mailbox_list as the follow-up to check verification status and notes premium-plan implications for additional mailboxes. It stops short of an explicit when-to-use-vs-alternative statement, but the surrounding workflow is well implied.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: it discloses the cross-parameter invariant, the default-mailbox guard with a remediation path, the irreversibility, and the confirm=true acknowledgement gate. This is the level of behavioral detail an agent needs before a destructive call.

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

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

Five tightly packed sentences, front-loaded with the consequence ('Permanently delete') and then the preconditions. No filler, no repetition of the name or 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 destructive mutation with no output schema, the description covers consequences, prerequisites, alternatives, and acknowledgement requirements. An agent has everything needed to call this correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the cross-field constraint that exactly one of transfer_aliases_to/delete_aliases is required — an invariant the JSON schema cannot express. That elevates it above the baseline, though it doesn't add format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Permanently delete a mailbox') and disambiguates itself from siblings like mailbox_update by naming what it destroys. The word 'Permanently' plus the alias-handling requirement make further reading unnecessary to grasp intent.

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

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

Gives explicit when-conditions and alternatives: route aliases via transfer_aliases_to (pointing at mailbox_list) or delete_aliases=true, with exactly one required. It also states the blocking case (default mailbox) and the remedy (mailbox_update with set_default=true), leaving nothing 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 readOnly, idempotent, non-destructive and open-world behavior, so the description adds context rather than repeating it: the fact that both verified and unverified mailboxes are returned, the exact field set, and how the ids feed downstream calls. It omits ordering and pagination behavior, but the disclosure is well above the annotation baseline.

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

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

Two sentences, zero filler. The scope and only-these-fields information is front-loaded and the chaining hint follows immediately.

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

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

With no output schema, the description carries the return-value burden and does so by naming the fields returned. Minor gaps remain (no ordering, pagination, or empty-account behavior), but for a zero-parameter read tool the definition is essentially 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 zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly adds no spurious parameter semantics.

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

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

States a specific verb+resource ('List the account's mailboxes') and scopes it by including both verified and unverified mailboxes. It also enumerates the returned fields, so it is distinguishable from sibling mailbox_create/update/delete and alias_list 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 concrete downstream guidance: 'Use the returned ids as mailbox_ids when creating or updating aliases,' which tells the agent when this tool is a prerequisite step. It does not, however, contrast itself against alternatives like account_get_info or state any precondition.

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

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

Annotations only state the safety profile (not read-only, not idempotent, not destructive, open-world); the description goes well beyond that by disclosing the verification prerequisite for set_default, that email changes stay pending until verified, the one-way semantics of set_default/cancel_email_change, the mutual exclusivity of email and cancel_email_change, and that no-op calls are rejected locally without hitting SimpleLogin.

Agents need to know what a tool does to the 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 is front-loaded in a short first sentence, and the constraint detail follows. The second sentence is a dense run-on stacking several clauses, but each clause carries distinct operational information, so little 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 no output schema, the description need not explain return values, and with annotations covering the safety profile plus a thorough account of preconditions, side effects, and parameter interactions, an agent has everything required to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not convey: that set_default and cancel_email_change only accept true (constraint exists in schema but the reason is only in the description), and that email and cancel_email_change are mutually exclusive — an interaction the schema cannot express.

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

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

The description opens with a specific verb+resource ('Update a mailbox') and enumerates the three distinct mutations available (set_default, email change, cancel_email_change), which clearly separates it from mailbox_create/mailbox_delete. It does not explicitly name a sibling, 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?

It gives concrete operative conditions: at least one change is required, set_default requires a verified mailbox, and a no-op call is rejected before contacting SimpleLogin. That tells an agent when the call will succeed or fail, though it never routes the agent to an alternative sibling tool for related tasks.

Agents often have multiple tools that could apply. Explicit usage 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 establish read-only, idempotent, non-destructive behavior, and the description layers on real operational detail: fixed page size of 20, sort order (unread first, then newest first), zero-based page index, and the more=true terminal condition. This is meaningful context beyond what the annotations convey.

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

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

A compact, front-loaded passage: purpose and scope first, then pagination mechanics, then the return shape, then the sibling hand-off. No filler sentences.

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

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

With no output schema, the description carries the return-value burden and does it: id, nullable title, HTML message, read flag, human-readable created_at, plus the pagination continuation flag. An agent has everything needed to call and consume the result.

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

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

Schema description coverage is 100% and the single parameter is fully documented there ('Zero-based page number; 20 notifications per page. Defaults to 0'), so the description largely repeats it. The only added signal is the more=true exhaustion indicator, which is baseline-appropriate.

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

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

States a specific verb+resource ('List account notifications from SimpleLogin') and enumerates the content types (announcements, warnings like mailbox bouncing), which separates it cleanly from the sibling notification_mark_read, a mutation on the same resource.

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

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

Explains pagination usage ('Use page_id for pagination (starts at 0)') and routes the follow-up action to the sibling: 'Mark entries handled with notification_mark_read.' That is clear context, but it does not state when NOT to call this or what a caller should expect if there are zero notifications.

Agents often have multiple tools that could apply. Explicit usage 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's restatement of idempotency is partly redundant. However, it adds genuinely new context: marking an already-read notification succeeds with no change, and unread/delete are not possible via the API, which is not derivable from the annotations.

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

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

Three short sentences, each carrying distinct information (action, idempotency, negative scope). No filler and the core action is front-loaded.

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

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

For a one-parameter state mutation with no output schema, the description covers action, idempotency semantics, and capability boundaries. Only the response shape is unspecified, which is minor for this kind of 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% with a single well-documented integer id, so the baseline is 3. The description adds useful provenance ('the id from notification_list'), telling the agent where a valid value originates, which the schema does not.

Input schemas describe structure but not intent. Descriptions should explain 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 (mark as read), the exact resource (a single account notification), and scopes it to one item. It also names notification_list as the source of the id, distinguishing it from the sibling list tool.

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

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

Tells the agent where the required id comes from (notification_list) and rules out unread/delete operations, which prevents misuse. It stops short of explicitly saying when this is not needed, but the context is clear enough.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the exact return fields (alias_generator, notification, random_alias_default_domain, sender_format, random_alias_suffix), which is important because there is no output schema. It stops short of describing authentication or error behavior.

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

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

Two sentences, front-loaded with the core action and resource. The field enumeration and the sibling reference both earn their place, 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 zero-parameter read tool with rich annotations and no output schema, the description supplies the returned field names and brief meanings, which is largely sufficient. It could be more complete about the response structure or types, but no major gaps remain for correct invocation.

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

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

The tool takes zero input parameters, so there are no parameter semantics to document. The baseline for 0 params is 4, and the description appropriately does not discuss parameters.

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

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

The description uses a specific verb ('Return') and resource ('account-wide alias settings'), then enumerates the five setting keys returned. It also distinguishes itself from the sibling settings_update tool by naming it for changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routes the agent to settings_update for modifying settings, establishing a clear read-vs-update boundary. However, it does not state prerequisites or when-not to use this tool beyond that alternative.

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

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

Goes well beyond the annotations by disclosing partial-update semantics ("only the provided fields change"), that resulting settings are returned, that no-op calls are rejected before contacting the server, and the validation rules for random_alias_default_domain (premium/verified requirements). These are non-obvious operational behaviors an agent needs before calling.

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

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

The scope constraint and update semantics are front-loaded in the first sentence, and each subsequent sentence delivers distinct information (validation rules, rejection behavior) 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 mutation tool with no output schema, the description covers the important gaps: partial-update behavior, the returned result, validation preconditions, and what is explicitly out of scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine cross-field semantics the schema lacks: the domain parameter must come from alias_domains_list, premium domains require a premium account, and custom domains must be owned and verified.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Update the account-wide alias settings") and immediately bounds the scope to the five documented alias-behavior fields. An agent can distinguish this from settings_get and alias_update 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?

Clearly frames when to use it (alias-behavior fields only) and when not to (account email, password, payment, deletion stay in the web UI), which is unusually explicit exclusion guidance. It stops short of naming a sibling tool for those other settings, so it is clear context rather than a full routing rule.

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