Proxy Mail QA

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

Annotations declare a non-read-only, non-idempotent, non-destructive write; the description adds the non-obvious side effect that 'failed: true fails the run', which the annotations do not convey and which materially changes how an agent should call it. It does not, however, state whether the run must be open or what the call returns.

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

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

A single front-loaded sentence: the core action comes first, the illustrative examples follow, and the failure flag is tacked on last with no wasted words.

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

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

For a five-parameter mutation with no output schema and adequate annotations, the description covers the essential behavior including the failure side effect. It stops short of stating prerequisites (run must be in progress) or confirming whether notes are append-only, but nothing critical 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 60%; test and run_id carry their own schema descriptions, and the description explains the semantics of the otherwise-undocumented `failed` flag. The required `text` parameter and `address` gain nothing beyond the schema, so this sits at the baseline for partially documented schemas.

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

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

States a concrete verb+resource ('Adds a line of your own to a run') and immediately illustrates it with a real example ('Submitted the sign-up form'), which separates it cleanly from siblings like start_run and finish_run that bracket a run's lifecycle.

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 examples ('a step you took... or a failure of your own') imply usage during an active run, but the description never says when to reach for this versus finish_run or how it interacts with run state. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it is a non-blocking snapshot ('without waiting') that aggregates several processing stages (Proxy Mail QA limits, Cloudflare SPF/DKIM/DMARC rejections) and may return a diagnostic hint rather than raw counts.

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

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

Purpose and output contents are front-loaded in the first sentence, with the usage instruction in a short second sentence. The first sentence is dense and list-heavy, but every clause names a distinct category of result, so little is wasted.

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

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

With no output schema, the description must describe returns, and it does: arrival counts, last-arrival timing, refusal reasons, rejection reasons, and hint text. For a one-parameter read-only diagnostic, nothing an agent needs in order 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?

There is a single parameter at 100% schema description coverage, and the schema already documents the variant/+tag behavior thoroughly. The description adds no additional parameter semantics, 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 description states a specific verb and resource ('Explains an address's mail without waiting') and enumerates exactly what it reports: arrival count, last arrival time, QA refusals, Cloudflare rejections by SPF/DKIM/DMARC, and delivery hints. This clearly separates it from the wait_* and check_email siblings, which block or examine a single message rather than summarizing an address's whole delivery picture.

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?

'Use it when a wait finds nothing' gives an explicit trigger condition that routes the agent here after a wait_for_code/wait_for_link failure, and 'tell the person what it says' prescribes follow-up behavior. It does not name the alternative wait tools explicitly or state when not to use it, 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?

Beyond the annotations, the description discloses that verdicts only are returned ('never the email's text or links'), that each check yields pass/fail/warn/skipped with a one-line reason, and that checks for disabled features are omitted. It doesn't contradict the annotations (readOnlyHint=false is consistent with the description's 'added to its report' via run_id).

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 a single enormous run-on sentence densely packed with every possible check, making it nearly impossible to scan. While the first clause is front-loaded, the rest is an undifferentiated wall of detail with no grouping or bullets, violating conciseness and 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 complex 14-parameter tool with no output schema, the description is quite complete: it explains the verdict model, the gating by Labs settings, the reporting side effect, and the meaning of major checks. It is comprehensive but so dense that an agent may struggle to extract the key info efficiently.

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 operational meaning: expect_host controls the link-destination check and is skipped without it, expect_text reports only missing phrases, expect_within works with since (e.g., 5m), and expect_attachment accepts types, extensions, or wildcards. This is more than repeating the schema.

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

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

The opening clause gives a specific verb and resource ('Checks the newest matching email at the address (or email_id, from count_emails)') and enumerates the checks performed. It is clear what the tool does, but it never directly contrasts itself with siblings like wait_for_code, wait_for_link, or check_delivery, so an 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?

'Wait for the email first' states the key precondition, and the Labs feature gating (marketing/coupon checks, harmful_attachment and spam_risk) tells the agent when certain checks will be absent. It does not explicitly name alternatives or say when NOT to use it, but the practical usage context is clear.

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

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

Annotations mark this readOnlyHint=false with no destructive hint, and the description reconciles that by disclosing the side effect: with run_id it records to the run report and can fail the run. It also discloses a hard prerequisite (Labs Marketing and offer emails must be enabled) and the resulting error behavior, plus a known measurement limitation (dot trick). It stops short of describing the full response shape or what happens on partial failures.

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 content is dense and mostly earns its place (reuse semantics, Labs gate, dot-trick exclusion), but the first sentence is a fragment that forces re-reading, and the Labs paragraph is long for a conditional setup note. Front-loading is decent—reuse detection appears early—but the prose could be tightened considerably into shorter declarative sentences.

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

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

With no output schema, the description carries return-shape duty and does name the key fields (reused, same_code, run_id effect) and the reuse condition. It also covers the setup prerequisite, an error mode, and a limitation. Missing: what a 'sender' scope contains and whether results are per-run accumulative, which an agent might want before calling.

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

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

Schema coverage is already 100%, so baseline would be 3; the description earns above that by explaining run_id's consequence (a failing run is recorded against that run) and by defining the output flags reused and same_code, which no structured field covers. The address-variant behavior is also restated meaningfully ('acts on the plain address'). Test is left entirely to the schema.

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

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

The description conveys that this tool reports, per sender, the coupons received at an address and which address variant each went to, and names its sibling alternative (get_address_variants) for signing up with variants. The opening clause is grammatically broken ('For each sender, its coupons at this address and which version...') with no verb, so the exact operation is inferred rather than stated. Still, an agent can distinguish it from check_email/check_delivery/count_emails by the offer-reuse focus.

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

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

Explicitly routes the agent to get_address_variants for creating variants, states the Labs prerequisite that must be enabled before the call will succeed, and rules out the Gmail dot trick as untestable here. It stops short of saying when NOT to call it (e.g. when no one-time offer is involved) or of sequencing itself relative to start_run/finish_run.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds the exclusive-lease semantics, the selection ordering (least recently used first), the lease bounds (default 10, max 60 minutes), the need to hold the checkout token, and the shape of the exhausted-matches error. That is substantive behavioral context well beyond the structured fields.

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

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

Two sentences, front-loaded with the action and its scope; the long trailing clause packs in lease, token, and error behavior without filler. The mid-sentence parenthetical about filters is slightly tangled but every clause earns its place.

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

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

For a 9-parameter, all-optional tool with no output schema, the description covers matching semantics, lease lifecycle, token handoff, and the failure mode. What the call actually returns (address, label, credential availability) is only implied, which is the main 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 coverage is 67% and the description maps its filters to the undocumented ones — tags ('for its state, such as verified or premium'), country, age, saved password, and text (search) — and restates the minutes default/bound. It doesn't add format or syntax detail for test/run_id, but those are already described in 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 ('Borrows a test account in a known state from the project') and immediately distinguishes the sibling return_account plus the exclusivity constraint ('that no other test has checked out'). An agent can tell this apart from return_account, create_address, and list_addresses 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 clear context (borrow for a test, return with return_account and the token) and describes the fallback when nothing is free ('the error says when the first comes free'). It does not state when not to use checkout (e.g. reusing an account you already hold) or prerequisites for the lease, so it stops short of explicit 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?

Adds substantial behavior beyond the readOnly/idempotent annotations: the exact result vocabulary per step, the `done`/waiting polling contract, that subjects are matched but never returned, the `within` tolerance default, and the Labs-gating error behavior. This is exactly the context annotations cannot carry.

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

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

One dense paragraph that is front-loaded with the core purpose before drilling into step semantics and the Labs caveat. Every sentence carries information, though the run-on parentheticals make it heavier than needed.

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 fully specifies the return shape (per-step status plus timing, and the `done` flag), the polling expectation, and the environment prerequisite. An agent has everything required to call it and interpret results.

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?

At 67% schema coverage the description meaningfully compensates: it explains `since` as the series start, what each step's fields mean (subject phrase, category, code/link, after, within), and supplies the `within` default (a tenth of `after`, min 10 minutes) that the schema omits.

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 — checks a welcome series / drip campaign by expecting each step's email in order after `since`. It reads clearly as distinct from siblings like check_email or wait_for_code, which wait for a single message rather than verifying an ordered series.

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

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

Gives clear operating context: steps answer pass/early/late/missing/waiting, and `done` is false while any step is waiting 'so call again later', plus the Labs prerequisite. It does not explicitly contrast with sibling alternatives (check_email, wait_for_code/link), so a 4 rather than a 5.

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

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

Beyond the annotations, the description discloses important behavior: passed is false when any post-unsubscribe marketing email arrives, run_id makes that failure affect the run, and transactional emails like receipts and password resets are excluded. It also explains the Lab-gated error condition, though it does not cover rate limits or full response structure.

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 dense but front-loads the core behavior and packs useful exclusions and prerequisites into a short space. The Lab sentence is slightly tangential at the end but still earns its place by preventing avoidable errors.

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 tool with no output schema and sparse annotations, the description gives enough detail to understand what is checked, what is excluded, what passed=false means, and how run_id affects the run. Some details such as exact return shape or behavior when no unsubscribe exists are left implicit, but the essential semantics are present.

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

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

Schema description coverage is 100%, so parameter definitions are already well documented. The description adds some meaning by linking address to mark_unsubscribed and noting that run_id causes failures to fail the run, but it does not substantially expand beyond the schema for address or test.

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

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

The description states a specific check: for each sender the address unsubscribed from, it reports marketing emails that arrived afterward by id and elapsed time, while excluding content. It explicitly ties itself to mark_unsubscribed and distinguishes the verification role from the unsubscribe action.

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 makes clear this is used after mark_unsubscribed to verify whether marketing emails still arrived, and it states the Labs prerequisite that must be enabled first. It does not name alternative checks such as check_delivery, but the context for using this specific tool is otherwise clear.

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

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

Adds value beyond the annotations by disclosing the non-waiting behavior and the return shape ("summarised by when it came, its sender and the kind of its code or link, never its content"). However, annotations declare readOnlyHint=false on what reads as a pure count; the description never explains the write side effect (that results are added to the run report, only hinted at in the run_id parameter). That gap keeps it at 3.

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

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

Three sentences, front-loaded with the verb and resource, then the sequencing rule, then the return summary. Nothing is redundant with the title or restates the schema.

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

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

With 8 parameters and no output schema, the description usefully covers what comes back (time, sender, kind of code/link, not content) and when to call it. It does not mention result limits, ordering, or how the count relates to run-report output, which are minor given full schema coverage.

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 every parameter including the enum values and subtype list is already documented in structured data. The description only gestures at filters via "when it came, its sender and the kind of its code or link", adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Counts the emails that reached the address") plus a concrete use case ("exactly one verification email"). The line "Doesn't wait" implicitly contrasts it with the wait_for_code/wait_for_link siblings, but the closest read sibling, check_email, is never named, so the agent must infer the 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?

Gives explicit sequencing guidance: "call it after the wait for the first email has returned, so a duplicate has had time to arrive." That is a real when-to-use rule an agent could otherwise get wrong. It stops short of naming alternatives such as check_email or expect_no_email, so there are no explicit exclusions.

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

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

Annotations cover the safety profile (mutating, non-idempotent, not open-world), and the description adds the things annotations cannot: the generated address always has a "wel-" prefix, the password is shown only once at creation and is thereafter stored on the address, and the address lifetime is capped at 30 days. Those are the facts an agent needs to avoid losing credentials.

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 action and the workflow follow-up, and every sentence is functional. It runs slightly long and restates a few details already in the schema (the 16-character password composition, the default domain), which keeps it from a 5.

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

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

With 13 optional parameters and no output schema, the description must explain what comes back — and it does: the address, an optional persona, optional date of birth, optional country, and optional password. It also states the ownership boundary (it does not sign up for you) and the next step, leaving nothing an agent must guess before calling.

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

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

Schema coverage is 100%, so per-parameter meaning is already carried by structured data (baseline 3). The description earns above baseline by explaining cross-parameter dependencies the schema doesn't spell out: age adds a date of birth to the persona, country adds a residence, and password: true both returns and saves a password.

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

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

The description opens with a specific verb and resource ("Creates a disposable email address in the project") and immediately scopes it to the app under test and the @mailclub.dev domain. It also draws a hard line against sibling tools: it explicitly says it does not register anything in the app and routes the agent onward to wait_for_code or wait_for_link.

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 names the concrete workflow conditions — sign up yourself, or hand the address (and password) to the person if you can't open the app — and then names the follow-up tools to call. The domain parameter guidance ("choose another only if the app under test rejects it") is an explicit when/when-not rule as well.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds real value beyond them: it discloses that all associated mail is destroyed and that the address name is permanently retired, which is the key irreversibility fact an agent needs. It stops short of describing auth requirements or failure modes.

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

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

Two short sentences, zero filler, with the destructive scope front-loaded before the permanence note. Every clause carries information an agent needs.

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

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

For a one-parameter destructive tool whose annotations and schema are both thorough, the description supplies the one thing structured fields cannot: the irreversible loss of the name and its mail. Nothing material is missing 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 coverage is 100% and the single parameter's schema description is unusually rich, explaining variants, capitalisation and +tag behavior. The description adds no parameter meaning of its own, so the baseline 3 for fully-covered schemas 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 (deletes) and resource (the address) plus the blast radius (all its mail), which cleanly separates it from sibling create_address/update_address. The second sentence adds a unique consequence — the name is never issued again — that no sibling shares.

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

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

Usage is implied by the destructive semantics but never stated: there is no guidance on when to prefer update_address or create_address, nor any note about preconditions or confirmation. The reader can infer intent from the name and effect, which is the definition of implied usage.

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

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

Beyond the annotations, the description discloses the watch duration, early return behavior, what is reported when an email arrives, that content is never revealed, and the polling protocol for longer windows. This is exactly the behavioral detail an agent needs for a timed negative check.

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 dense but front-loaded and every sentence carries operational meaning. A few phrases are packed tightly, such as 'Pass since as the time the action happened,' but there is little wasted text.

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

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

For a complex timed check with ten parameters and no output schema, the description supplies the critical return and polling semantics. Combined with the fully documented schema, it is complete enough for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds useful meaning beyond the schema by explaining how to set since, how until extends the window, and how to poll with the same since and until while done is false.

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

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

The description states a specific verb and resource: it watches an address and passes if no matching email arrives. It also gives concrete example use cases, which makes its purpose distinct from sibling tools like check_email, wait_for_code, and wait_for_link.

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

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

It clearly explains when to use the tool, including examples such as an unsubscribed user receiving nothing or a rate-limited reset request. It also explains the longer-window polling pattern, though it does not explicitly name an alternative sibling tool for comparison.

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 mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds the hold concept and how to release it, but its numeric details (default 10, max 60) merely restate the schema, and it says nothing about what happens if the hold has already lapsed or what a repeated call does.

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

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

Very tight: the core action and the minutes constraint come first, followed by one short sentence of context and one of follow-up. The second sentence is fragmentary but earns its place by explaining why the tool exists.

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

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

There is no output schema, so the description should carry the whole burden, and it covers purpose, the token source, and the release path. It omits what the call returns and how failures (expired checkout, exceeding the cap) behave, which keeps it short of complete.

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

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

Schema description coverage is 100%, so the schema already documents token, address, and minutes including bounds. The description repeats the minutes default/cap and the token source rather than adding format or edge-case meaning, 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+resource ('Keeps an account from check_out_account held for longer') and names the mechanism (minutes from now). It explicitly ties itself to check_out_account and return_account, so an agent can distinguish it from those siblings without reading schemas.

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

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

Gives a clear triggering condition ('For a test that runs past the hold') and a lifecycle follow-up ('give it back with return_account when done'). It does not state a when-not or a fallback for an already-expired hold, so it falls short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavior beyond them by enumerating the exact pass/fail conditions (missing email, unexpected email, failed check, failing note, failed: true), which tells the agent what outcome to expect. It does not clarify whether a failing run errors out or simply returns a failing report, leaving one behavioral ambiguity.

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

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

Three sentences, front-loaded with the action and output format; the middle sentence packs the failure conditions efficiently. 'Show the person the report' is a little colloquial but earns its place as an output-handling instruction.

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-value burden and does so by specifying Markdown format and intended destination. Pass/fail logic is covered. The one missing piece is the failure mode (does the call raise or return a failing report), which matters for a non-read-only 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 50%: run_id is documented in the schema but 'failed' is not. The description compensates by explaining the failed flag ('failed: true says your test failed'), giving the agent the meaning of the undocumented parameter. The run_id semantics ('what this call sees is added to its report') come from the schema, not the description.

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 ('Finishes a run') plus the return artifact ('report in Markdown'), which is enough to distinguish it from start_run, add_run_note and the check_* siblings by the 'run' concept. It stops short of explicitly naming which sibling to use instead, so it is clear but not fully differentiated.

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

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

'ready for a pull request comment or a reply' and 'Show the person the report' give downstream usage context, implying this is the closing step of a run. There is no explicit when-to-call/when-not-to-call statement and no named alternative, 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 flag a non-read-only, non-idempotent operation; the description adds the concrete side effect (a new test address is created), that the new address's password is persisted and surfaced only here, that an existing address's password is not returned, and how unmapped fields come back as null with a note. That is meaningful context beyond the annotations, though error/rate-limit behavior is absent.

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 key point (what values it produces) is front-loaded, but the text is a run of long, clause-heavy sentences with stacked parentheticals that make it harder to scan than it needs to be. The content mostly earns its place, but the structure is dense rather than economical.

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 10-parameter tool with no output schema, the description carries the return-value burden well, explaining the per-field value mapping, null-plus-note fallback, consent handling, and address reuse semantics. Remaining gaps (failure modes, how unknown field kinds are treated beyond null) are minor.

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

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

With 90% schema coverage the schema already documents most parameters, but the description adds real meaning: which field attributes to send (type, name, label, placeholder, autocomplete, rules, options), the role of `id` as a fallback identifier, and the relationship between the returned values and field ids. This goes beyond restating 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: it returns the value to type or pick for each field of a sign-up form, optionally tied to a new or previously created test address. The purpose is unmistakable, though it never names or contrasts a sibling tool, relying on the uniqueness of the task instead.

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

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

Gives clear context: pass a new address or an existing one via `address`, and it explicitly points to the sibling `record_consent` for recording the marketing-consent choice. It also draws the boundary that the tool does not fill in or submit the form, but stops short of stating explicit when-not-to-use conditions.

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

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

Annotations already declare read-only, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely useful semantics beyond that: delivered variants deliver to the same inbox, undeliverable ones are refused before arrival, and the wait linkage to a specific variant.

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

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

Front-loads the purpose and keeps to two sentences, but the first sentence is dense with stacked parentheticals that slow parsing. Efficient overall, slightly overstuffed.

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 explains the three result categories an agent will receive, and the usage note covers the intended workflow. Sufficient for a single-parameter read tool, though it never says whether results are ordered or how many variants are returned.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents the address/variant behavior in detail. The description adds workflow context but no syntactic or format meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Lists') and resource ('versions of a test address') and enumerates the returned categories (delivered, undeliverable, invalid), so an agent knows exactly what comes back. It does not name a sibling (e.g. list_addresses or check_email) to disambiguate, which is the only missing piece for 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?

Gives clear context (checking that the app accepts valid-but-unusual addresses and rejects invalid ones) plus a concrete workflow ('Sign up with a delivered one, then wait on that same variant'). No explicit when-not or named alternative tools, so it stops short of a 5.

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

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

Annotations already declare this a read-only, idempotent, closed-world listing, so the safety profile is covered. The description goes beyond that by disclosing the semantics of each bucket — notably that store_as_text values must be stored and displayed verbatim, never executed — which is real behavioral context an agent would not otherwise have. It stops short of describing the exact return shape (flat list vs. grouped), which is why this is a 4 rather than a 5.

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

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

The content is dense with useful detail and front-loads the purpose, but the entire description is one ~230-word run-on sentence stitched together with colons, em-dashes and nested parentheticals. Nothing is strictly redundant, yet the flat structure makes the four value buckets hard to scan.

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 fixture-provider tool with no output schema, the description supplies the value categories and the follow-up workflow, which is close to what an agent needs in order to act. The remaining gap is that the return structure is never stated, and the misleading address/email cross-reference could send an agent to the wrong sibling.

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

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

Schema coverage is 100% and the schema already explains max_length, but the description still adds genuine meaning: it says the fixture falls back to 64, 128 and 255 characters when no maximum is given, and that out-of-range values are generated from the supplied maximum. The field enum is left entirely to the schema.

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

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

Opens with a specific verb and resource ('Lists values for testing what the app under test does with a name field') and explicitly names the sibling fixture tool it mirrors, so an agent can place it immediately among the variants/check tools. The four value buckets (accept, reject, store_as_text, decide) further pin down what it produces.

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

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

It states the operating context plainly ('Type each into the field yourself and report what the app did: accepted, rejected, or changed it'), which tells the agent both when to call it and what to do with the result. However, the cross-reference 'as get_address_variants does for the email field' is inaccurate — address variants are presumably for an address field — and that muddies the routing signal.

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 disclose read-only, non-idempotent, non-destructive behavior. The description adds meaningful context beyond that: each call makes fresh passwords, it specifies the categories and edge cases generated, and it notes the bcrypt 72-byte nuance. It does not contradict 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?

The definition is front-loaded and every major clause contributes a concrete testing rule or usage step. It is dense and written as one long sentence, which slightly hurts scanability, but it does not waste much space on redundant or irrelevant content.

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

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

With no output schema, the description still explains that the tool returns categorized passwords (accept, reject, decide) and gives enough context to use them correctly. It does not specify the exact response shape, such as whether passwords are grouped into arrays or objects, but it is otherwise complete for invocation.

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

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

Schema coverage is 100%, so the schema already documents min_length, max_length, and symbols. The description adds value by explaining how those rules drive generated variants, including exactly-minimum/maximum lengths, symbol-class coverage, and the over-72-byte bcrypt pair.

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 clearly states the specific verb and resource: it lists passwords for testing an app's password field within that field's rules. It is easy to distinguish from sibling set_password because it generates test variants rather than setting a password, but it never explicitly names or contrasts with sibling tools.

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

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

It gives clear usage context: use the generated passwords to test accept/reject/decide behavior, set one with the form, and verify sign-in, including the composed/decomposed accent cross-check. It does not state when not to use it or explicitly name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds real behavioral context by disclosing the quota rules (Free: 500 total, 50 a day; Team: no limit) and the areas the project tests. That is the kind of policy detail an agent cannot get from the schema, though it does not mention any auth or scoping caveats.

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

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

A single sentence that front-loads the resource identity before the field list, with no filler. It is a long run-on enumeration, but every clause maps to a returned field, so nothing is wasted.

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

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

With no output schema and no parameters, the description carries the return-value burden and does so thoroughly, covering identity, domains, prefix, lifetime, quota with plan-specific limits, and test areas. An agent knows exactly what a call yields without inspecting anything else.

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 disambiguate; baseline 4 applies. The description correctly implies the project is fixed by the connection rather than passed in.

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 resource ('the project this connection works in') and enumerates exactly what it exposes: name, website, mail domains, email prefix, address lifetime, quota, and tested areas. An agent can tell it is the read side of project state, though it never names update_project as the write counterpart.

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

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

Usage is implied by the read-only framing and the enumerated fields, but there is no explicit 'use this when you need X' or exclusion pointing to update_project or the check_* siblings. Nothing misleading, but routing is left 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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond the schema: results are ordered newest first, each row carries persona/tags/newest code-or-link, and filters are AND-combined ('every filter given must match'). Pagination/limit behavior is left unexplained.

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 the second sentence carries only the filtering contract and example. The first sentence is dense with parenthetical lists but no sentence is filler; slight run-on cost.

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 9-parameter, zero-required read-only tool with no output schema, the description covers what an agent would otherwise miss: return fields, ordering, and cross-filter AND semantics. Remaining gap is result-size/pagination behavior (limit has no schema description), which an agent must infer from the default.

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 89%, so the baseline is 3, and the description earns above that by explaining the semantics filters share: all supplied filters must match simultaneously, illustrated with a combined country + max_age + has_password example. The one undocumented parameter (limit) is not covered by the description either.

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

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

States a specific verb and resource (lists addresses in the project), plus the ordering ('newest first') and the shape of each returned row ('persona, tags and newest code or link'). This is clearly distinguishable from create_address, delete_address, update_address and get_address_variants without opening any schema.

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

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

Gives a concrete when-to-use condition — find a test account that already exists 'instead of creating another' — with a worked filter example (country GB, max_age 17, has_password true). It stops short of naming its alternatives explicitly (create_address) or stating exclusions, so it's strong but not fully enumerated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation profile is covered. The description adds real behavioral context the annotations don't: what marking actually changes (links pass check_email's local-links check instead of failing) and the consequence of not marking. It stops short of saying whether a mark can be removed or what happens on repeat calls beyond the idempotent hint.

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, with rationale following. The 'as in Project settings:' aside and stacked parentheticals add some clutter, but every sentence still contributes information about behavior or usage.

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

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

For a one-parameter, non-destructive, idempotent mutation with no output schema, the description covers purpose, effect on downstream checks, and when to use it. The main omission is the inverse operation (how to unmark a host), which is minor given the tool's narrow scope.

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

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

Schema description coverage is 100% and the single 'host' parameter is fully documented in the schema, including the 'localhost:3000' example. The description adds no format or syntax detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Marks a host as a dev environment of this project') and immediately ties the effect to a named sibling, check_email's local-links check. An agent can distinguish this from sibling tools like check_email or update_address 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?

Explicitly names the trigger ('Use it when testing an app that runs on your machine') and the counterfactual ('links to an unmarked localhost still fail'), which tells the agent both when to call it and when calling it would be wrong. The rationale about catching staging/live mistakes reinforces the boundary.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds real behavioral context beyond them — the marketing-email side effect, sender scoping rules, and a documented error response until the Labs setting is enabled. It does not mention idempotency behavior for repeated calls.

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

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

Front-loaded with the core action and effect, then the parameter rule, then the Labs caveat. Dense but every clause carries information; the run_id/test parameters are left to the schema, which is appropriate.

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 covers the meaningful return condition (error message until Labs is enabled) and the side effect of the change. It omits what happens on a repeat call given idempotentHint=false, a minor gap for a 5-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds conditional semantics the schema cannot express: sender is optional only when a single sender is watched, otherwise email_id or service must be supplied. That materially improves correct invocation.

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

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

States a specific verb and resource: ends an unsubscribe watch once the address has subscribed again, and explains the consequence (marketing email no longer fails). This clearly distinguishes it from the sibling mark_unsubscribed.

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

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

Gives the triggering condition (address has subscribed again) and conditional parameter routing: no sender needed when only one sender is watched, otherwise pass email_id or service. It also states the prerequisite for the Labs variant. It never explicitly names mark_unsubscribed as the inverse alternative, so it falls short of a 5.

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

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

Far exceeds the annotations: it discloses the downstream effect (marketing mail from that sender 'fails after_unsubscribe in check_email and shows in check_unsubscribe, however long after'), confirms repeat safety in prose ('Marking twice is harmless'), and explains the gated 'In Labs' behavior including the specific error surfaced until the setting is enabled. Nothing an agent would need to predict behavior is left implicit.

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 and the manual-unsubscribe precondition, and the sender-naming rule follows immediately. It is one dense paragraph where the Labs caveat and the 'at' note could be ordered more crisply, but nearly every clause carries actionable information.

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

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

With 7 parameters, no output schema, and annotations that only cover safety/idempotency, the description fills the remaining gaps: the manual precondition, default sender resolution, back-dating, idempotency, and a failure mode (Labs off) with its error message. An agent can call this correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the email_id-vs-service choice and the default resolution rule ('with neither, the newest marketing email decides'), plus the purpose of 'at' for back-dated unsubscribes. It does not, however, touch grace, test, or run_id except indirectly.

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 precise verb and resource ('Records that the address unsubscribed from a sender') and immediately scopes the tool's role: it only records an unsubscribe the user performed elsewhere ('after you did it in your own browser or in the app'). This cleanly separates it from mark_resubscribed and from the check_* siblings that merely observe state.

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

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

Explicit preconditions ('after you did it in your own browser or in the app'), explicit exclusion ('Proxy Mail QA never opens unsubscribe links'), and explicit alternative selectors ('Name the sender with email_id ... or service ...; with neither, the newest marketing email decides'). It also names the tools whose output feeds it (count_emails) and the ones affected by it (check_email, check_unsubscribe).

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

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

Annotations already declare the tool is non-read-only, idempotent, and non-destructive. The description adds important behavioral details beyond annotations: the Labs feature gate (must enable 'Marketing and offer emails' or it returns an error), partial-update semantics ('Give only what changed'), and the return format ('answers with the consent as recorded').

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

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

The description is front-loaded with purpose but then devotes several sentences to check_email's jurisdiction coverage and output fields, which are tangential to this tool. This extra detail dilutes focus and could be trimmed for better conciseness.

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

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

Given the mutation tool's complexity (5 parameters, 1 required), full schema coverage, and no output schema, the description covers purpose, usage sequence, feature gate, and return behavior adequately. It is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining double_opt_in self-confirmation ('it confirms itself when the verify link is used') and by clarifying that only changed fields need to be supplied, which affects how parameters are used in practice.

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

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

The first sentence states a specific verb and resource: 'Records what the address agreed to at sign-up' and lists the consent fields (marketing, prechecked, double_opt_in). It also distinguishes this tool from the sibling check_email by noting that check_email 'judges' the recorded consent, making the division of labor clear.

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 provides clear usage context: 'after you filled in the form' and 'check_email then judges', indicating the sequence and purpose. It lacks explicit exclusions or alternatives, but the implied workflow is sufficient for correct selection.

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 the verdict rule set (accepted after end date, offer already used at another address variant, double-use when one_time is true; warnings on error or unexplained refusal), the side effect that a failed verdict fails an associated run, and an environment prerequisite that returns an explicit error until Labs settings are enabled.

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?

Every clause carries information: preconditions, verdict logic, run coupling, Labs gating. It is, however, a single dense semicolon-chained block with the core purpose buried behind the checkout precondition, which makes it harder to scan than a front-loaded statement would be.

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 burden and does so: it answers with every result for the coupon plus the coupon_result verdict, and enumerates which conditions produce fail versus warn. Combined with defaults, run integration and the Labs error path, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics: code defaults to the newest coupon at the address, email_id is the alternative identification path, and one_time is explained as the trigger for the double-acceptance verdict rather than just 'offer is one per person'.

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

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

States a concrete verb and resource: records whether checkout accepted, refused (rejected) or errored on a coupon, together with the app's message. It also distinguishes itself from siblings by name, pointing at check_offers for the 'already given to another address variant' condition and by requiring the caller to do the checkout with their own browser tools rather than as a sibling tool.

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

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

Gives clear timing ('after applying a coupon at checkout'), the environment precondition ('on staging with test payments only, never real card details') and the Labs gating condition with its fallback behaviour. It stops short of an explicit when-not-to-use alternative, but for this workflow no real sibling substitutes exist.

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 supply generic hints (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds real behavioral context beyond them: the token must originate from check_out_account, and add_tags/remove_tags exist to record the account's post-test state so the pool stays accurate. It still omits failure modes (invalid/expired token) and whether tags are validated against existing pool state.

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

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

Two sentences, front-loaded with the core action and the token dependency, then the tag semantics with a compact example. No filler, though the parenthetical example is the only part that could be trimmed.

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

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

There is no output schema, but the description covers the essentials for a 4-parameter release tool: what it does, what token to supply, and what the tag parameters mean. Missing only error/edge behavior, which keeps it short of a 5.

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%: token and address are documented in the schema, but add_tags and remove_tags have no schema descriptions. The description compensates by explaining exactly what those two arrays do and gives a concrete example ('add cancelled, remove premium'), which is more than the schema alone provides.

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

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

States a specific verb and resource ('Gives a checked-out account back') and explicitly names the counterpart tool check_out_account, so an agent can immediately tell this is the release half of the checkout lifecycle rather than a read or a mutation of account data.

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 makes the usage context clear ('for the next test', using the token from check_out_account), which implies this is called at the end of a test run. It does not state explicit exclusions (e.g. what to do if the checkout expired), but the pairing with check_out_account gives adequate routing context.

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

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

The annotations already declare this is a read-only, idempotent, non-destructive search tool, so the description does not need to repeat safety semantics. It adds useful behavioral context beyond the annotations by explaining that it returns the best-matching passages, each with the page title and address, which helps the agent understand the response shape. It does not describe ranking, pagination, or coverage limits in detail, so it falls just short of the highest score.

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

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

The description is front-loaded with the core action and then efficiently lists query domains, return behavior, and the alternative tool. It is longer than a minimal description but the topic list and routing sentence earn their place by helping the agent formulate useful searches and avoid misuse.

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 appropriately explains the return format: best-matching passages with page title and address. The parameters are fully covered by the schema, and the description supplies enough usage context, topical scope, and sibling differentiation for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so both the query and limit parameters are already documented in the schema, including an example query and the default/maximum for limit. The description adds topical examples of what can be searched but does not add parameter-specific syntax or constraints beyond what the schema provides, making the baseline score appropriate.

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

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

The description states a specific verb and resource — searches Proxy Mail QA's docs and guides — and enumerates concrete topic areas such as MCP client setup, REST/npm/Python usage, Playwright/Cypress/pytest waits, delivery troubleshooting, and plans. It also explicitly distinguishes itself from the sibling tool get_project, so an agent can tell which tool to select for documentation versus project-specific settings.

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

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

It gives clear when-to-use guidance by listing the kinds of how-to, integration, troubleshooting, and plan/limit questions this tool handles. It also states when not to use it: 'For this project's own settings and limits, use get_project,' which directly routes the agent to the correct sibling.

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, readOnlyHint=false, and idempotentHint=false, so the mutation profile is known. The description adds real value beyond that: it explains the prior saved value is replaced, that omitting the password generates a 16-character one, and that the generated value is returned only once — a critical one-shot disclosure the annotations do not convey.

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

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

Front-loads the core action and scope in the first sentence, then covers the generation fallback and the safety boundary. Slightly wordy with some restatement of the replacement behavior, but every sentence carries usable 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 3-parameter mutation tool with no output schema, the description covers what is written, what is overwritten, the generation fallback, and the one-time return of a generated value. Only minor gaps remain (e.g., what happens if the address does not exist), so it is nearly complete.

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

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

Schema coverage is 100%, so the schema already documents label, address, and password, including the +tag variant behavior. The description only adds the 16-character length for the generated password and restates the omission behavior, which is a modest increment over structured data — baseline 3.

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

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

States a specific verb and resource — saves/replaces the password for a test account address — and clarifies the scope ('the test account's password in the app under test, never a real person's'). An agent can distinguish this from address/account siblings like create_address or check_out_account without opening the schema.

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

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

Gives concrete triggers for when to use it ('after testing a password change or reset in the app under test, or when a sign-up form needed a different one') and a clear scope exclusion (never a real person's password). It stops short of naming an alternative tool or explicit when-not conditions, so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond that: it explains the run lifecycle, that finish_run produces a Markdown report for a PR, and that the run is visible in the app. It does not, however, warn that repeat calls create separate runs or note any 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?

The purpose is front-loaded in the opening clause, which is good, but the second sentence is a long, comma-heavy enumeration ('the code or the link's site (never its query), checks, and emails that never came') that is hard to parse and spends words on sibling tools rather than this one.

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

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

With no output schema, the description usefully conveys the surrounding workflow and what finish_run yields. It does not explicitly state what start_run itself returns (a run_id), though that is strongly implied by the instruction to pass run_id onward, leaving a small gap for a tool whose output the agent must capture.

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 all six parameters documented in the schema (name, agent, branch, commit, repository, pull_request), so the baseline of 3 applies. The description adds no parameter-level detail (e.g., that name/agent identify the session) beyond what the schema already provides.

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

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

States a specific verb and resource ('Starts a run') and even defines what a run is ('a record of one test session'), which an agent can use to tell it apart from sibling tools like finish_run. However, roughly half the text describes sibling tools' behavior rather than this tool's own purpose, which dilutes the focus.

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

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

Clearly signals the sequencing: pass the returned run_id to create_address, the waits, count_emails, expect_no_email, check_email and check_out_account, and names finish_run as the closing step. It gives context for when to reach for this tool (start of a test session) but never states when NOT to use it or any prerequisite conditions.

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. The description adds useful behavioral detail beyond those annotations: partial update semantics, empty-string clearing, notes length limit, and the password alternative. It is consistent with the destructive annotation.

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 compact and informative, with the main purpose and field list front-loaded. The first sentence is somewhat long, but the extra clauses earn their place by covering all updatable fields and the password exclusion.

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 9-parameter mutation tool with annotations and no output schema, the description covers the essential behavior: what can be changed, how to clear fields, and where to go for passwords. Remaining gaps around tags/label semantics and return behavior are minor given the annotations and lack of an output schema.

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

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

Schema coverage is only 33%, so the description must carry meaning, and it does: it identifies the mutable fields, groups them into identity details and usage metadata, states that notes are up to 2,000 characters, and explains empty-string clearing. It does not fully document tags or label behavior, but it adds substantial semantic value over the schema alone.

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

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

The description states a specific verb ('Changes') and resource ('a test account's details') and enumerates the mutable fields, making the tool's scope clear. It also distinguishes the password case by routing to set_password, which is a relevant sibling.

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

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

It gives clear operational guidance: send only fields to change, use an empty string to clear a field, and use set_password for password changes. It does not explicitly contrast with create_address or delete_address, but the context for when to use this tool is clear.

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

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

Annotations already declare readOnly=false, destructiveHint=true, and idempotentHint=true. The description adds important context beyond them: required permissions (project lead, organisation owner, or admin), activity-log behavior, partial-update semantics, exclusions, and the return shape ('as get_project does'). It does not explain the destructiveHint or reversibility explicitly, so a 4 is appropriate.

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

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

The description is front-loaded with purpose and field scope, then adds partial-update behavior, permissions, exclusions, and return shape. Every sentence contributes useful information with no repetition or fluff.

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 five optional parameters, no output schema, and rich annotations, the description covers what an agent needs: purpose, permissions, partial-update behavior, excluded operations, and return shape. Safety characteristics are already carried by annotations.

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 documents each field's meaning, limits, enum, and empty-to-remove behavior. The description lists the same field names and adds 'Only the fields given change,' but does not add per-parameter syntax or format details beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description names the specific verb and resource ('Changes this project's...') and enumerates the settings it affects (name, website, environments, email prefix, default mail domain). This clearly distinguishes it from the read-only sibling get_project and from address-focused update tools.

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

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

It supplies clear usage context ('as in Project settings') and explicit exclusions: 'Archiving or deleting a project, and keeping whole emails, stay in the app.' It also clarifies partial-update behavior with 'Only the fields given change.' It does not name an alternative tool for excluded operations, so it falls short of a full 5.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, so the description adds real value: the 30-second cap, the instant return for mail from the last 15 minutes, and the fact that 'unused' excludes codes already returned by an earlier wait (implying waits observe/consume state). It still doesn't say what a timeout or no-match response looks like, which matters for a tool flagged as not read-only.

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

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

Three dense but purposeful sentences, front-loaded with the timeout and return shape before the kind and since variants. Nothing is redundant with the schema or the title.

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

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

With 8 parameters and no output schema, the description still states the main return fields (code, sending service, expiry, after_seconds) and the timing behavior, which is what an agent needs to call it correctly. It falls short only on failure/timeout response shape and on the meaning of readOnlyHint=false.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining the since/after_seconds relationship and the retry implication, and by clarifying the coupon semantics of kind. Remaining params (test, service, unused, address variants) are only covered in 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 ('waits ... for a verification or login code') plus the scope variants (otp vs coupon vs any), so an agent knows exactly what arrives in the result. It never names the obvious sibling wait_for_link, so the code-vs-link routing decision is left to inference from the tool names.

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

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

Gives concrete when-to-use context ('after signing up for an offer, say') and a retry rule ('offers often come minutes later, so call again if nothing has come yet'). It lacks an explicit exclusion, e.g. when to prefer wait_for_link or check_email/check_offers 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?

The annotations mark this readOnlyHint=false, which the description never explains — nothing says that a wait consumes or claims a link, even though the 'unused' parameter strongly implies it. It does usefully disclose that the link is returned unopened and that the send arrives within a 30-second budget.

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

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

Two sentences, front-loaded with the action and time bound, ending on the important 'has not been opened' qualifier. Nothing wasted.

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

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

With no output schema, the description does state the return value (the link plus sending service), which is the main thing an agent needs. The remaining gap is the side effect implied by readOnlyHint=false and the 'unused' parameter.

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

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

Schema coverage is 100%, so every parameter already has a thorough description (including variants, unused, and timeout behavior). The description adds no parameter detail beyond the implicit 'address', 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 description uses the specific verb 'waits' and names the resource — a verify, magic sign-in, invite, or password-reset link — plus the return payload. It's clear what the tool does, though it never names the obvious sibling wait_for_code to say how the two differ.

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 30-second ceiling tells the agent when this is the wrong tool for a slow send, but there's no explicit guidance to use wait_for_code for codes or check_email for full message bodies. Usage is implied by the link-focused wording rather than stated.

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