Emailens MCP

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantial behavior: findings carry loc (line, column, offset) and alsoAtLines for HTML input, detail:'full' yields fix snippets, non-html formats are compiled first, and an unlabeled pasted Vue file is compiled as maizzle. It also conveys the relative cost of summary vs full (~10x smaller).

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 sentences, all informative, with the core purpose front-loaded and the sibling redirect last. Slight density and some overlap with schema text (detail summary vs full) keep it below a 5, 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?

There is no output schema, so the description carries the return-format burden and does so: it describes per-client scores, one finding per problem, affected-client listings, and loc/alsoAtLines for source editing. For a 5-parameter tool with three enums, nothing needed to call or interpret it is missing.

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

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

Schema description coverage is 100% and the schema already explains detail, format, clients, and targetingPolicy in detail, so the baseline is 3. The description mostly restates the detail/clients semantics and adds the format complication ('Anything but html is compiled') that the schema already covers, contributing little new parameter meaning.

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

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

States a specific verb and resource ('Quick CSS compatibility analysis') plus the shape of the output ('per-client scores and one finding per problem, listing the clients it affects'). It distinguishes itself from siblings by explicitly contrasting with audit_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?

Names the alternative explicitly ('Use audit_email for a full quality report (spam, links, a11y, images, etc.)') and gives the condition that selects the quick path. It also routes to detail:'full' and clients for narrowing, so an agent knows both when to use it and how to scope it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context: how compatibility findings are collapsed, that detail:'full' yields per-client entries with fix snippets, that HTML findings carry loc (line, column, offset), and the non-obvious semantics of targetingPolicy. This is disclosure well beyond the annotation surface.

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?

It is front-loaded with the core purpose and the parameter guidance trails at the end, which is reasonable. But the middle is one sprawling run-on sentence listing every check plus lengthy parenthetical asides, so size and structure are only adequate, not tight.

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-format burden and mostly does: it explains the collapsed compatibility shape, detail:'full' output, and loc metadata. It does not describe the overall response envelope (severity/score fields), leaving a small gap for a complex, 16-check audit 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 description coverage is 100%, so the schema already documents all six parameters and three enums. The description largely restates these (detail summary/full, targetingPolicy values, clients narrowing) and adds only a little (the '16 KB ceiling'/'every rule after }}' rationale), so the baseline 3 applies.

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

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

The opening states a specific verb+resource ('Comprehensive email quality audit') and then enumerates the concrete check domains it covers, so an agent knows exactly what it does. It never names or differentiates itself from close siblings like analyze_email or check_deliverability, which an agent must disambiguate on its own, so it stops short of 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 solid in-tool usage guidance for options ('pass detail:full for the per-client breakdown', 'use skip to omit checks', 'clients to narrow which clients are reported'). However it offers no when-to-use-this-vs-alternatives routing, and with analyze_email/check_deliverability present the agent gets no explicit selection rule.

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, openWorldHint=true, idempotentHint=false — the agent knows this is a mutating, non-idempotent, external-calling operation. The description adds useful context (real browsers, CDN hosting, API key requirement) but doesn't explain cost, rate limits, or latency implications of rendering 21 clients.

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 capability, then supporting context, then the API-key prerequisite. The '?ref=mcp' affiliate suffix at the end is promotional noise that slightly dilutes the otherwise tight 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 non-idempotent, open-world tool that renders and hosts content on a CDN, the description covers what it does and where it runs, but omits output shape (no output schema exists), pagination for 21 clients, and failure modes when the API key is missing or quota is exhausted.

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

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

Schema description coverage is 100%, so all five params are documented in the schema. The description adds no parameter-specific detail beyond noting clients and modes exist. 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 clear verb+resource (capture email screenshots) with impressive specificity: 21 clients named, light/dark variants, real browsers, CDN hosting. This distinguishes it from preview_email and other siblings, though it doesn't explicitly name the difference.

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

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

No when-to-use guidance. The description doesn't say when to call this vs preview_email or audit_email, nor does it specify prerequisites beyond an API key. The agent is left to infer routing from sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: it discloses the mechanism (DNS lookups) and the absence of an API-key/auth requirement, which matters for invocation. It stops short of noting lookup latency or DNS failure 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, zero waste, and the highest-value information (what it checks and what it returns) is front-loaded. The no-API-key note is a compact, useful trailing clause.

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

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

With no output schema, the description usefully compensates by stating the return shape (score 0-100 plus actionable issues). For a single-parameter, read-only tool that is nearly complete, though it leaves unclear how the score is weighted or what form the 'issues' take.

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

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

Schema description coverage is 100% and the schema already supplies an example ('company.com') and a regex pattern. The description only echoes that a domain is the target, adding no format, normalization, or subdomain-handling guidance beyond the structured field.

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 email deliverability for a domain') and enumerates the exact records examined (SPF, DKIM, DMARC, MX, BIMI). It does not explicitly differentiate itself from siblings like audit_email or analyze_email, though the domain-level DNS scope implicitly separates 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?

The description implies usage context by naming the record types and noting 'no API key needed', but gives no explicit when-to-use guidance or alternatives. An agent must infer whether this is a pre-send check, a domain audit, or a substitute for audit_email.

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 covered. The description adds value beyond that by disclosing the shape of the result (score deltas, fixed vs newly introduced issues, broken down per client), which matters because there is no output schema. It does not discuss permissions, sizes, or 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?

Two sentences, no filler. The core comparison behavior leads and the usage trigger follows, which is the right front-loading for a tool whose main differentiation is what it produces.

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

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

With no output schema and 100% parameter coverage, the description's job is mainly to explain the return value, and it does list the diff categories per client. It could be more complete about the structure/format of that report or whether the comparison is order-sensitive, but nothing essential for calling 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 the format enum is documented thoroughly in the schema (including compile behavior and the pasted Vue fallback). The description only implies the two-version input ('two email HTML versions') and adds no ordering or format guidance beyond the schema, 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 (compare/diff) and resource (two email HTML versions) and enumerates the diff outputs: score changes, fixed issues, and newly introduced issues per client. This is unambiguous and clearly separable from siblings like analyze_email (single input) or fix_email (mutation), so an agent can route 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 second sentence gives an explicit trigger: 'Use after making fixes to verify improvements.' That is real when-to-use guidance. It stops short of naming alternatives or when-not conditions (e.g., use analyze_email for a single unreviewed version), so it is clear context without exclusions.

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

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

Annotations already declare a read-only, idempotent, non-destructive operation, and the description is consistent with that ('Generate a fix prompt' rather than mutating code). It adds genuinely useful return-value context — markdown containing original code, detected issues, fix snippets, and format-specific instructions — which matters because there is no output schema.

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

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

Three tight sentences with zero filler; the artifact/return shape is front-loaded, followed by the workflow cue. 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?

With no output schema, the description supplies the return contract, and the schema plus annotations fully cover inputs and safety. An agent has everything needed to select and call this correctly after analysis.

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 parameter descriptions are rich (format enum semantics, scope/selectedClientId dependency, compiled-vs-pasted Vue behavior). The description adds nothing beyond the schema for parameters, so the baseline 3 applies.

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

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

Specific verb+resource: 'Generate a structured fix prompt for email compatibility issues', and it explicitly clarifies the artifact type (markdown with original code, detected issues, fix snippets). It implicitly distinguishes itself from siblings by being the 'fix' step after preview/analyze, though it doesn't name what it is *not* 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?

Explicit sequencing guidance: 'Use after preview_email or analyze_email', naming the two upstream siblings. No when-not or exclusion conditions are given, but the workflow position is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the returned data (IDs, names, engines, dark mode support), which matters since no output schema exists.

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

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

A single front-loaded sentence with no filler; the resource is stated first and the returned fields follow compactly.

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-param, read-only list tool with no output schema, the description supplies exactly the missing piece: what the list contains. Nothing an agent needs to invoke it correctly is absent.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies no inputs are needed.

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 resource ('every supported email client') and enumerates the fields returned (IDs, names, engines, dark mode support). An agent can tell immediately what this does, and none of the siblings (check_deliverability, preview_email, etc.) overlap with 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?

Usage is only implied: as a zero-parameter enumeration tool it is obviously for looking up available clients, but the description never states when to call it (e.g., before other client-keyed calls) or any alternative. Adequate but with a clear gap.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructiveHint, openWorldHint=false), so the bar is lower, and the description usefully adds that this compiles/transforms source across 21 named clients, simulates dark mode, and checks inbox preview and size. 'Transforms HTML' could momentarily read as a mutation, but in context (preview, readOnly annotation) it clearly means render-time transformation, so it is not contradictory. It does not say what the response contains, which is the only remaining gap.

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

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

Purpose is correctly front-loaded in the opening clause, and each listed clause carries information. But the whole body is one comma-spliced run-on sentence with no grouping, making the feature list dense to parse for a tool with this many distinct capabilities.

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, four-parameter tool with no output schema and a rich annotation set, the description covers what is computed but not what is returned, and gives no routing context against the many overlapping sibling tools. Adequate as a minimum viable definition, but an agent still lacks the material needed to choose this tool over analyze_email or audit_email.

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 enum semantics of format, targetingPolicy, and clients are fully documented in the schema itself, establishing a baseline of 3. The description only gestures at parameters indirectly (the 21-client list maps loosely to `clients`), adding no format, ID, or policy syntax 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+resource ('Full email compatibility preview') and enumerates the concrete analyses it performs (client transforms, CSS analysis, scoring, dark mode, inbox preview, size). However, it never distinguishes itself from close siblings like analyze_email, audit_email, or capture_screenshots, and the 'analyzes CSS'/'generates scores' clauses actively overlap with those tools, leaving an agent to guess which one 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?

There is no when-to-use, when-not-to-use, or alternative-routing guidance at all, despite a crowded sibling set (analyze_email, audit_email, fix_email, capture_screenshots, check_deliverability). The description implies it is the broad preview step but never says when an agent should prefer one of the narrower tools instead.

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 and idempotentHint=false, and the description is consistent with that by disclosing the possible side effect ('or create a new one'). It further adds value beyond the annotations by naming the auth requirement (EMAILENS_API_KEY) and the exact SMTP host/port for sending test mail.

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

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

Two compact sentences, front-loaded with the core action, followed by the practical connection and auth details. 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?

With no output schema, the description adequately conveys what is returned (an active test address) and how to use it. It is slightly thin on what happens when a new inbox is created (e.g., lifetime, reuse behavior), but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100% and the single optional 'name' parameter is fully documented in the schema. The description adds nothing about the name parameter's effect (e.g., whether it changes the address or just a label), so it sits at the baseline.

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

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

States a specific verb and resource ('Get your active Emailens sandbox test address') and explicitly notes the get-or-create duality, which is the key behavioral distinction. It is clearly separable from siblings like sandbox_list_messages and sandbox_wait_for_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?

The description explains how to use the returned address (SMTP endpoint smtp.emailens.dev:2525 or inbound routing) and the API key prerequisite, which is genuinely useful context. However, it never states when to prefer this tool over the sibling sandbox tools or when an agent should call it in a workflow, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new context: the exact content returned (HTML/text parts, extracted OTP, magic links, headers, spam analysis) and the API-key auth requirement.

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

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

Two tightly packed sentences with zero redundancy; the return-value enumeration is front-loaded and the auth requirement trails as a short qualifier. 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?

With no output schema, the description usefully enumerates what comes back and flags the credential requirement, which is enough for a single-parameter read tool. Only the missing sibling differentiation 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 description coverage is 100% with a single parameter ('messageId' documented as 'ID of the sandbox message'), so the schema does the heavy lifting. The description adds nothing about where that ID comes from or its format, which is the expected baseline when coverage is complete.

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

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

States a specific verb and resource ('Get complete captured email details') and enumerates the payload (HTML/text parts, OTP, magic links, headers, spam analysis). It does not, however, distinguish itself from the very similar siblings sandbox_list_messages and sandbox_wait_for_email, leaving the agent to infer that this fetches one full message by ID.

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

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

The only guidance is a prerequisite ('Requires EMAILENS_API_KEY'). There is no statement of when to use this versus sandbox_list_messages to enumerate an inbox or sandbox_wait_for_email to poll for a new arrival, which are the obvious alternatives an agent must choose between.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description usefully adds the auth prerequisite and the 'recently received' recency scoping, but says nothing about result count limits, ordering, or pagination 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 short sentences with the core purpose front-loaded and the auth requirement trailing. No wasted words, though it is terse enough that it omits information the agent would benefit from.

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 could reasonably say something about the shape or volume of results (list of messages, recency window, ordering). Annotations cover safety, but the listing semantics remain underspecified for a tool whose main value is its return payload.

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 single inboxId parameter is already documented as an optional filter. The description's plural 'sandbox inboxes' implies multi-inbox results but adds no filtering syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (recently received test emails in sandbox inboxes), which is clearly distinguishable from write-oriented siblings like fix_email or sandbox_wait_for_email. It does not explicitly name the sibling it differs from (e.g. sandbox_get_message for a single message), 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?

The only guidance is a prerequisite ('Requires EMAILENS_API_KEY'), not a when-to-use condition. There is no statement of when to choose this over sandbox_get_inbox, sandbox_get_message, or sandbox_wait_for_email, leaving the agent to infer the routing.

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

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

Annotations already declare readOnly, non-destructive, open-world, and non-idempotent. The description adds genuinely new behavior: this call polls/blocks until a match arrives, auto-extracts 4-8 digit OTP codes and action links, and requires EMAILENS_API_KEY auth. It stops short of describing what happens on timeout or how results are shaped.

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

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

Three short sentences, front-loaded with the core blocking behavior, then the value-add (OTP/link extraction), then the prerequisite. No filler; every sentence carries information.

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

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

With no output schema, the description usefully signals what the agent gets back (OTP codes, action links) and flags the auth prerequisite. It omits timeout/failure semantics, which matters for a polling tool, but the schema covers the timeout parameter itself.

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 sender, inboxId, subject, and timeoutSeconds are fully documented in the schema. The description adds no syntax, matching semantics, or default/max hints beyond what the schema already provides; 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: 'Poll and wait for a matching incoming test email in the sandbox.' The blocking/polling nature distinguishes it from read-once siblings like sandbox_get_message, though no sibling is named explicitly.

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

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

Usage is only implied by the phrase 'zero-regex test assertions' and the required API key, which suggest an end-to-end test flow. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as sandbox_list_messages for non-blocking checks.

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 non-read-only, non-idempotent, open-world, non-destructive, but disclose nothing about requirements. The description adds genuinely useful context beyond them: the EMAILENS_API_KEY env var dependency, the paid Dev plan gate, and the fact that recipients view the analysis unauthenticated.

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

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

Three tight sentences, front-loaded with the action, then the recipient benefit, then the prerequisites. No filler; the pricing detail is arguably incidental but small.

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 does cover the return concept ('shareable link') and the recipient-side view, plus auth/plan prerequisites. It lacks any note on link lifetime, revocation, or whether repeated calls produce distinct links, which for a non-idempotent open-world tool is a minor remaining gap.

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

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

Schema description coverage is 100% with 3 well-documented params including an enum for `format`, so the schema carries the burden. The description adds no parameter-level detail (e.g., whether `title` is optional or how `format` interacts with `html`), 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: 'Create a shareable link for an email preview.' This distinguishes it from sandbox/preview siblings that generate previews rather than share them, though no sibling is named explicitly.

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

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

Usage is implied rather than stated — the agent can infer you call this when you want to share a preview externally, but there is no explicit when-to-use vs. when-not or named alternative (e.g., preview_email vs. share_preview). Prerequisites (API key, Dev plan) are given, which helps but is not the same as routing guidance.

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