email59

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds the meaningful downstream effect: campaigns to that list (or every list) skip the address. That is the operational consequence an agent needs, and it goes beyond the structured fields. It stops short of noting permission requirements or behavior when the address is already opted out.

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, the core action front-loaded and the scoping nuance second. Nothing is wasted and no filler or restated title 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 2-parameter tool with full schema coverage and annotations covering safety and idempotency, and with no output schema, the description supplies the effect of the write and the list scoping. The main gap is any distinction from the blocklist siblings.

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 list_id's meaning ('Empty = every list.') is already documented in the schema, so the description's scoping sentence largely repeats it. Baseline 3 is appropriate since the schema carries 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 and resource ('Record an opt-out') that an agent can act on immediately. It does not, however, differentiate itself from the sibling 'block'/'list_blocklist' tools, which describe a closely related suppression concept, so the agent must infer the boundary.

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

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

The description gives no when-to-use guidance and names no alternative; it never explains when an agent should call add_unsubscribe versus block or unblock. The list_id scoping rule is behavioral detail, not usage guidance.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the two-step OTP flow, the signup side effect and quota, and how to use the returned key via the Authorization header. Missing only operational details like code/session expiry 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?

Front-loaded with the core action, then the flows in call order, then the header usage. Dense but virtually every clause carries information; the parenthetical quota note is the only slightly tacked-on element.

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

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

No output schema, and the description compensates by explaining that the flow yields a session key and how to send it. Both auth paths are covered. It stops short of error handling, session expiry, and OTP retry behavior, which would complete the picture for a mutation-capable auth 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% so the 3 baseline applies, but the description goes further by explaining the relationship between parameters (email triggers the OTP email, otp is the code from it, api_key is an alternative to email) and the e59_live_ prefix convention. That is genuine added meaning over 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 ('Sign up or sign in to email59') and immediately distinguishes itself from siblings like create_api_key or get_account by covering the session-acquisition role. An agent knows exactly what this tool is for.

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 between two paths: pass email to trigger a 6-digit code then call again with email+otp, or pass api_key to swap for a session key. It also discloses the side effect (new email = account with 200 free emails/day), giving the agent enough to choose deliberately.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the actual effect ('sends to it are refused'), but says nothing about reversibility, whether already-queued mail is affected, or auth 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 short sentences, zero filler, with the action and its effect front-loaded. Nothing could be trimmed without losing information.

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

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

For a simple 3-parameter mutation with rich annotations and no output schema, the description covers purpose, scope and consequence. The remaining gaps (the 'reason' parameter and behavior on duplicate/invalid values) are minor but real.

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 only 33%: 'value' is documented and 'kind' is an enum, but 'reason' is unexplained in both schema and description. The description's 'email address or a whole domain' partly compensates by mapping to the kind enum, but it adds no syntax, format, or meaning for the undocumented 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?

Specific verb (block) plus the two resource types (email address or whole domain) and the account scope. It is clearly distinct from the obvious sibling 'unblock', but it never names or contrasts with any sibling, so it stops short of full differentiation.

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

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

'Sends to it are refused' implies the use case (stopping inbound mail) but gives no explicit when-to-use/when-not guidance and never points to list_blocklist or unblock for inspection/removal. 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?

Beyond the annotations (readOnlyHint=false, idempotent=false, openWorldHint=true), the description discloses that this only starts a purchase, returns a checkout_url for a human to pay, that credits land only after payment clears, that credits never expire, and that a 5% (min $0.50) fee applies. That is meaningful behavioral context an agent cannot get from the 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?

The description is front-loaded with the action and pricing, and every clause carries real information (price tiers, credit math, fees, checkout flow, policy gate). It is dense with parentheticals in the first sentence, which slightly impedes scanning, but nothing is 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 three-parameter write tool with no output schema, the description covers preconditions, side effects, timing of credit delivery, cost, and the return value (checkout_url). An agent has everything needed to invoke it safely and 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 67%, and the description compensates by spelling out pack_id values (pack_5/pack_10/pack_50) and the credit-per-dollar ratio, which the schema leaves undefined. The agree and policy_version semantics largely duplicate the schema descriptions, but the added linkage to GET /v1/policy clarifies their source.

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 concrete action (start buying a pack), enumerates valid pack values with prices, and explains what the resulting credits are. It is clearly distinguishable from siblings like get_pricing (lookup) and order_status (post-purchase), so an agent can route correctly 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?

It gives explicit preconditions and sequencing: show the refund policy and terms from GET /v1/policy first, then pass agree=true and the matching policy_version only after the person agrees, and use GET /v1/pricing for totals. It does not state when this tool should be avoided (e.g. already-pending purchase, auth requirements), 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 readOnly/idempotent/non-destructive, yet the description still adds real value: it discloses the score range (0-99), the exact verdict vocabulary, and importantly that Gmail/Outlook bypass DNS, which materially affects result interpretation. Missing only operational details such as latency or behavior on malformed input.

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

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

The core capability and the no-sign-in/no-email-sent reassurances are front-loaded, and the returns are summarized compactly. The DNS record enumeration is a long list but each item is informative, so it earns its place; minor trimming possible.

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 present, the description compensates by defining both return fields (score 0-99, verdict enum values) and the major behavioral caveat about big providers skipping DNS. An agent has everything needed to call it and interpret the result.

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

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

A single parameter with 100% schema description coverage, so the schema carries the semantics. The description adds no format or normalization guidance (e.g. case handling, unicode domains) beyond what the schema states. 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+resource ('deep check of an email address') and enumerates exactly what is examined: format, provider username rules, disposable/role detection, and MX/SPF/DMARC/DKIM/MTA-STS/TLS-RPT/BIMI records. That is far beyond a restated title. It does not distinguish itself from close siblings like validate_email, verify_check or verify_start, 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?

Useful context is implied — 'free', 'no sign-in needed', 'No email is sent' — which signals a safe pre-flight check. However, it never says when to choose this over validate_email or verify_start, nor what kinds of inputs are unsuitable. Usage is inferable but not directed.

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, open-world behavior, yet the description still adds real value: no email is sent, format/provider rules plus one MX lookup per domain, a daily per-account quota, and that the response exposes remaining quota. It doesn't say what happens at the 1,000-address boundary or on partial 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?

A single tight paragraph that front-loads the batch size and input formats before the output shape and limits; nearly every clause carries information. A few fragments ('Format, provider rules and one MX lookup per domain') read telegraphically but still earn their 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?

With no output schema, the description still defines the return payload well: one status plus reason per address and counts per status, along with remaining quota. What's missing is edge-case behavior at the batch cap or with malformed CSV, which an agent would need before invoking at scale.

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 beyond it by specifying that CSV input must carry a column headed 'email' and that raw addresses are accepted as emails, which the schema does not state. It stops short of explaining mutual exclusivity or precedence between the two optional 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: bulk-checking a mailing list of up to 1,000 addresses supplied either as an array or as CSV text. The batch scope and the six possible statuses distinguish it in practice from check_email/validate_email, but no sibling is named, so the agent must infer the single-vs-list split.

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?

Implicit guidance comes from the 1,000-address cap and the daily per-account limit, which imply when this tool is the right choice. There is no explicit when-to-use/when-not statement and no pointer to the single-address siblings for one-off checks, leaving the routing decision 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?

Adds behavior the annotations cannot convey: a hard quota of 10 keys per account, the irreversible fact that the key is shown only once, and the exact semantics of test mode (prefix e59_test_, sends accepted and stored but never delivered, consumes no allowance). These are the details that determine whether an agent can safely call this.

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

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

Three short sentences, front-loaded with the action and quota, then the one-time-display warning, then the mode explanation. Every clause carries information; nothing is repeated from the schema or annotations.

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

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

For a 2-param creation tool with no output schema and annotations already covering safety, the description covers quota, one-time visibility, and mode behavior well. It does not explain the label parameter or how to subsequently retrieve/revoke the key, leaving a small 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 coverage is only 50% (label undocumented, mode merely 'Default live.'), and the description compensates strongly for mode by defining what a test key is and does. It adds no semantics for label, so it stops short of full coverage.

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

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

States a specific verb and resource ('Create a long-lived API key') plus the account-level cap (max 10), which no sibling (list_api_keys, auth) shares. An agent can distinguish this create operation from list_api_keys and get_account without inspecting 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?

Usage is implied by 'long-lived' and by the test-mode guidance for staging and CI, but there is no explicit when-to-use/when-not statement or routing to alternatives (e.g. when to prefer an existing key via list_api_keys instead of creating another). Adequate but leaves the choice 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the returned field list, but discloses no traits such as authentication requirements, whether values are live or cached, or refresh cadence for daily_limit/resets_at.

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

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

A single dense sentence with zero filler, and the identifying resource is front-loaded. It is a bare noun fragment with no verb, which makes it read as a data dump rather than an instruction, slightly weakening structure.

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

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

For a zero-parameter read with full annotation coverage there is no output schema, and the description compensates by enumerating the exact fields returned. It stops short of clarifying field semantics (e.g., units or what resets_at references), but an agent has enough 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 the baseline is 4. The description correctly implies a no-argument call by simply naming the signed-in account, and there are no parameters whose semantics need elaboration.

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

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

The description names the specific resource ('the signed-in account') and enumerates the exact fields returned, which clearly distinguishes it from the sibling update_account and the various list_*/check_* tools. It lacks an explicit verb, but the read intent is unambiguous from the field list and the 'Get account' title.

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 statement of when to call this versus alternatives, nor any mentioned prerequisite such as needing an authenticated session. A sibling like update_account or auth could plausibly be confused with it, and the description offers no 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that: no authentication is required. It does not describe caching, refresh behavior of the 'daily' emails, or the response shape.

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

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

A single compact sentence with no filler, and the most distinctive fact (free daily emails) is front-loaded. The telegraphic noun-list style is slightly terse but wastes nothing.

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 burden of conveying what comes back; it does partially satisfy this by listing the three content types. However, it gives no sense of structure (list of packs? currency? limits on the free daily emails), so an agent knows the topic but not the shape of 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Nothing in the description is needed to clarify parameter usage, and none is provided or expected.

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 enumerates the payload contents (free daily emails, email credits per dollar, packs on sale) rather than stating the action, but the enumeration makes it inferable that this returns pricing/plan information. It never uses a verb+resource formulation and does not distinguish itself from siblings such as buy_pack or get_account, so an agent must infer the purpose from the content 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The only usage-relevant signal is the trailing 'No sign-in needed,' which implies it can be called pre-auth, but this is incidental rather than stated as 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 readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuinely useful context beyond that: it discloses the shape of the returned data and reassures that secret key material is never exposed, which matters for a credentials-related 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?

A single short sentence with no filler, and the most important scoping fact (only ids and labels, never secrets) is front-loaded into the same breath. Nothing is 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?

With no output schema, the description must carry the return-value burden, and it only partially does: it states the fields returned but says nothing about ordering, pagination, or result count. For a simple zero-parameter read that is adequate but leaves a real gap for a listing tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description makes no parameter claims, which is correct since the schema is an empty object.

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

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

The description names the specific resource (the account's API keys) and clarifies the returned fields (ids and labels), which lets an agent distinguish it from the sibling create_api_key. The list verb is only implied via the name/title rather than stated, so it is clear but not maximally 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?

There is no guidance on when to use this tool versus alternatives such as create_api_key or get_account, and no prerequisites or exclusions are mentioned. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the useful scope detail that both addresses and domains are returned, with no pagination, ordering, or count information.

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 short fragment with zero filler; the resource is front-loaded immediately. It is efficient, though its brevity is partly under-specification rather than deliberate density.

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

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

For a low-complexity, zero-parameter read with rich annotations, the description covers what is listed and whose list it is. It stops short of describing the return shape (no output schema exists) or whether the list is paginated, which an agent may still want.

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 nothing for the description to clarify beyond what the (empty) schema shows. Baseline 4 applies for a parameterless tool.

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

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

The description is a noun phrase naming the resource ('blocked addresses and domains') and its scope ('the account's'), which is slightly more than the title's 'List blocked addresses' because it adds domains. However, it states no verb and does not distinguish itself from siblings such as block/unblock beyond the resource name, leaving purpose only implied.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to the obvious alternatives (block to add, unblock to remove, or add_unsubscribe for a related list). The agent must infer that this is the read side of the block/unblock pair.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the description's added value is the domain behavior: test emails are accepted and stored but never delivered, ordering is newest first, and a verify_start code is embedded in the returned html/text. That is genuine 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?

Two dense, front-loaded sentences with no filler; the resource and its nonexistent-delivery behavior come first, then the parameter modes. It is telegraphic but each 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?

With no output schema, the description carries the return-value burden and largely does so: it names the fields (id, html, text) and the verify_start code contents for the single-email mode. The list-mode return shape and the limit cap are left to the schema, a minor gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further than the schema: it explains that id returns one email including its html and text and that a verify_start code lives there, and that to filters by recipient. It does not mention limit, which the schema documents adequately on its own.

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

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

States a concrete resource with a sharp qualifier: emails sent with a test key, accepted but never delivered, newest first. An agent can distinguish this from check_email or list_api_keys without opening the schema. It stops short of naming which sibling to use instead for live/delivered mail.

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 how to use the parameters (pass id for one email, pass to to filter) but never states when to reach for this tool versus the other mail-related siblings such as check_email or verify_check. Usage is implied by the test-key scope rather than declared.

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 this as a read-only, idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds the possible status values, but it does not mention authentication requirements, what happens for an unknown order, or any 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?

A single short sentence with the key return states front-loaded. There is no filler or redundancy.

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

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

For a simple one-parameter read tool with rich annotations, the description is close to adequate, but it omits what happens when the order is not found and how the order_id is obtained. Those gaps matter for correct invocation.

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

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

Schema description coverage is 0% and the single required parameter order_id is left unexplained in the description. 'Order from buy_pack' hints at provenance, but the description does not clarify the integer ID format, where to obtain it, or how it behaves in lookups.

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

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

The description names the resource (order status) and explicitly ties it to the sibling operation buy_pack, with the possible return states (pending or paid). It stops short of fully differentiating from other order-adjacent tools, but the verb+resource is clear enough to select 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?

Mentioning 'from buy_pack' implies this is a follow-up check after purchasing a pack, giving some usage context. However, it does not state prerequisites, when not to use it, or which sibling to use for related order 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?

Goes well beyond the annotations: it discloses that the unsubscribe link is injected automatically, that invalid/role/blocked/unsubscribed recipients are skipped at no cost, that each accepted recipient consumes one email of the daily allowance, and that an oversized campaign is refused atomically. That is exactly the context an agent needs before an irreversible send (idempotentHint=false).

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

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

Two tight sentences with the core action and the 1,000-recipient bound front-loaded, followed by the billing and refusal rules. No clause is 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 non-idempotent, open-world send with six parameters, the description covers the side effects, skip logic, quota and refusal behavior, which is what matters most. It does not hint at what a successful call returns, a minor gap with no output schema 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 50%, so the schema documents from, list_id and recipients while html, text and subject are bare. The description adds the 1,000-recipient cap and the list_id/unsubscribe relationship, but leaves the html/text split and subject semantics unexplained. Baseline 3 is appropriate given the partial coverage.

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

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

States a specific verb+resource (send a marketing email) and bounds it precisely (up to 1,000 recipients), which separates it from the sibling send_email. An agent can identify the operation without opening the schema.

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

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

The cost/allowance model implies this is the bulk-marketing path, but the description never explicitly says when to use this instead of send_email, nor states prerequisites such as needing a verified sender or purchased allowance. Usage context 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 cover read-only, idempotency, open-world, and destructive hints. The description adds useful delivery behavior: HTML branded template with a text part, text/html/both guidance, and a quota consumption rule ('Uses 1 email of today's allowance'). It does not contradict 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 and compact. The four short sentences each carry distinct information: scope, format, quota, and bulk alternative. No filler.

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

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

Given 15 parameters, nested brand object, two enums, and no output schema, the description covers the key operational context well: single-recipient sending, body format, quota, and bulk routing. It is not exhaustive on per-parameter behavior, but the schema supplies substantial detail and annotations cover safety.

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 moderate at 73%, so many parameters are already documented in the schema. The description adds some integrated meaning around text/html bodies and marketing category behavior, but it does not cover most of the 15 parameters, including brand, from, reply_to, template, and button fields.

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: 'Send one email to one recipient.' It also clearly distinguishes transactional vs marketing use and explicitly separates itself from the bulk sibling send_campaign.

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

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

Names the bulk alternative explicitly and gives the selecting condition: 'Many recipients at once: send_campaign.' It also indicates the transactional/marketing distinction and the single-recipient scope.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds nothing beyond this—no note on permissions required, whether removal affects in-flight sends, or what the effect on future messages is.

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

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

A single efficient sentence with no wasted words, front-loading the action and resource. Brevity here is appropriate though it leaves gaps elsewhere.

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 an enum parameter, zero schema coverage, and no output schema, the description should clarify the kind/value inputs and prerequisites. Annotations cover safety but the description leaves the parameter contract unexplained.

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 0%, so the description must compensate, but it never mentions the 'kind' or 'value' parameters. The phrase 'an email address or domain' loosely maps to the kind enum, but the value parameter and format expectations are entirely undocumented.

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 ('Remove') and resource ('email address or domain from the blocklist'), which is clear and distinguishable from the sibling 'block' by inversion. It does not explicitly name or contrast with siblings, so it falls just short of a 5.

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

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

The description offers no when-to-use guidance, no prerequisites, and no alternatives (e.g., when to use this versus 'block' or 'add_unsubscribe'). Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds a useful semantic point that brand controls 'the look of every email the account sends,' but does not disclose that omitted/empty values clear or overwrite existing settings.

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

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

A single front-loaded sentence with no filler; the parenthetical is the only slight syntactic clutter, but it earns its place by explaining 'brand'.

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

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

For a nested-object mutation with no output schema, the description leaves out important behavior: whether brand sub-fields are partially updatable, what happens when a parameter is omitted, and confirmation of the clearing behavior only documented inside the schema.

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

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

The description names the three top-level parameters (name, company, brand), matching the schema, but adds no format, required-ness, or replace-vs-merge semantics. With schema coverage at only 33% (name and company undocumented), the description does not fully compensate for the gap.

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 (Set) and resource (name, company or brand on the account), and the parenthetical explains what brand means functionally. It is distinguishable from read-oriented siblings like get_account, 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?

There is no statement of when to use this tool versus alternatives (get_account, create_api_key, etc.) or any prerequisite/precondition. The only usage signal is the verb 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by enumerating the verdict vocabulary (ok, invalid, no_mx, disposable, role), which tells the agent what kinds of outcomes to expect beyond what 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?

Two short sentences, front-loaded with the purpose before the outcome vocabulary. Every clause earns its place and nothing is 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?

With no output schema, the description usefully discloses the return vocabulary (ok, invalid, no_mx, disposable, role), which is exactly what an agent needs to interpret results. It omits cost/quota or rate-limit context, but for a single-parameter read-only check it is largely 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% for the single 'email' parameter, so the schema carries the parameter burden. The description's verdict list describes outcomes rather than the parameter, adding no syntax or format detail, 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 ('Check an address') and a purpose timing ('before sending'), so the job is clear. However, it offers no differentiation from closely overlapping siblings like check_email, verify_check, and verify_start, leaving the agent to guess which check tool to pick.

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?

'before sending' implies a usage context, so guidance is present but only implied. There is no when-not guidance and no routing to or away from the multiple competing check/verify siblings, which is the biggest ambiguity here.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description explains WHY the call is not idempotent ('a right code works once'), documents a lockout behavior ('5 wrong codes lock it'), and notes billing impact ('Uses no allowance'). These are behavioral traits well 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?

Dense and front-loaded: usage, parameter selection, then return values. The status enumeration is long but each term is load-bearing; phrasing is slightly telegraphic in places ('Give to ... or id, and code').

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, yet the description fully enumerates the return shape (valid boolean plus status values) and covers the failure and lockout paths. Nothing an agent needs to call or interpret this tool 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 real meaning: `to` resolves to the newest code for that address and `id` is the identifier from verify_start, which the schema descriptions only gesture at.

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 ('Check a code from verify_start') and identifies the sibling that produces the input, so the agent can place it in the flow without opening the schema. It is clearly distinct from verify_start and from unrelated siblings like check_email or validate_email.

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?

States the precondition (a code from verify_start) and clarifies the `to` mode ('checks the newest code sent there') versus supplying `id`. It gives no explicit when-not guidance, but the entry point 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 only declare the mutation profile (readOnlyHint=false, idempotentHint=false); the description adds the operational facts an agent cannot infer: the code is never returned, resends are limited, codes expire, one email is consumed from a daily allowance, and a new code supersedes the waiting one. That is substantive behavioral disclosure well beyond the annotation set.

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 the first clause, and everything after it (quota, expiry, replacement, chaining) earns its place. The middle clause stack ('makes the code, sends it, limits resends and expires it') is dense and slightly run-on, costing a point.

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

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

For a mutating tool with no output schema, the description covers the important unknowns: what it returns ('Returns an id'), what it costs, how long the code lives, and what to call next. Error and rate-limit specifics are left implicit, 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%, with enums-free but documented ranges and defaults for expires_in and code_length, so the schema carries parameter meaning. The description adds only that the destination is 'an address' and that the code is never surfaced to the caller, which is useful but not parameter-specific. 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 ('Email a one-time verification code to an address') and immediately scopes it with the use cases it serves. An agent can distinguish it from send_email, check_email, and validate_email 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?

Names the follow-up sibling and the trigger for it ('Then call verify_check with what the person typed'), which is exactly the routing an agent needs. It also explains replacement behavior for repeat calls. It stops short of an explicit exclusion ('don't use send_email for this'), so it is clear context rather than a full when/when-not rule.

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