Cooper Email

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

Annotations only declare destructive/openWorld/idempotent; the description goes far beyond by spelling out idempotent replay behavior (same domain returns current status, no duplicate), plan caps and the 402 upgrade_url path, DNS mode semantics (automatic vs external), and the DMARC p=reject state that silently blocks mail until DKIM verifies. These are non-obvious behavioral traits an agent could not infer from annotations or schema.

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

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

Front-loaded correctly with the trigger sentence, but the body is dense and partially redundant — 'Free includes 1' appears twice and plan tiers are restated. Several clauses (raw HTTP endpoint POST /api/v1/inboxes, notices payload shape) are useful but contribute to a wall of text that could be tightened.

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 with plan limits, DNS modes, and verification dependencies, the description covers prerequisites (auth), caps, return shape (status, records, mail flags, warnings, dns), and downstream next steps. Nothing an agent needs to call this correctly — or to avoid inventing MX/DKIM values — 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 already 100%, so the baseline is 3; the description adds real meaning on top by framing domain as a hostname example (agents.example.com) and by explaining that client_id is an idempotency key and that repeating the domain itself is also idempotent. That clarifies the interaction between the two parameters beyond the schema's own wording.

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

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

Opens with a specific verb and resource ('add a custom domain') and immediately names the boundaries relative to siblings: verification goes to cooper_verify_domain, and inbox creation is a separate later call. An agent can distinguish it from cooper_list_domains, cooper_verify_domain, and cooper_create_inbox 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 explicit when-to-use ('when the user wants to add a custom domain'), explicit alternatives ('check now with cooper_verify_domain, or subscribe to domain.verified'), and explicit exclusions ('Cooper does not register a domain, create a zone, or move nameservers'). It also maps failure conditions (402 plan limit, 409 domain_exists, 400 invalid_domain) to what the agent should do next.

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 genuine behavior beyond the annotations: auth is required, exactly one confirmation email is sent, nothing further is sent until the person confirms, and the return shape is listed. However, annotations declare destructiveHint=true and the description never explains what is destructive or irreversible about the call, leaving a significant declared trait unexplained. The idempotency claim is consistent with idempotentHint=true.

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 usage condition and side effects before the input list, and every sentence carries information. The 'Inputs:' enumeration largely duplicates the schema and could be trimmed, but the text remains tight.

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

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

Covers auth, side effects, idempotency, and output shape for a three-parameter mutation, which is substantial. Gaps remain: the destructiveHint=true trait is unexplained, and the relationship to cooper_confirm_owner (the follow-up the text implies) is never stated. Because an output schema exists, the return-value listing is redundant rather than compensatory.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the digest enum values. The description restates them ('email — the human's address', 'digest — immediate (default) or daily') without adding format, validation, or edge-case meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: registering a human owner who receives the agent's progress updates by email and can reply. The lead sentence ('Use this when a human should receive the agent's progress updates') makes the effect concrete. It does not, however, differentiate against adjacent siblings such as cooper_confirm_owner, cooper_ask_owner, or cooper_set_owner_preferences, even though it alludes to a confirm step.

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

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

Gives a clear usage condition tied to the outcome the agent wants (a human receiving updates and able to reply). No explicit when-not conditions or named alternatives, so the agent must infer routing among the owner-related siblings.

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 supplied annotations, the description discloses that auth is required, that the email goes to every verified owner, the long-poll mechanics of wait (creates then polls until answered/expired/canceled or wait ends), the full status lifecycle, error codes (409 no_verified_owner, 400 param), shared rate limits with cooper_notify_owner, and a security warning that answers are untrusted data. This is unusually rich behavioral context.

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 when-to-use trigger and organized logically: behavior, kind semantics, constraints, wait mechanics, return shape, failure modes, limits. It is dense but nearly every sentence adds actionable information; minor waste comes from repeating schema-documented limits like the 64-character value constraint.

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 an 11-parameter mutation tool with an output schema, the description covers everything an agent needs: auth, recipient scope, all parameter semantics and constraints, wait behavior, return statuses, error codes, rate-limit inheritance, and an untrusted-answer warning. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains what each kind does ('approve offers Approve and Deny', 'choose needs options', 'ask asks the owner to reply in free text'), clarifies that a reply answering the question does not create a task, and explains task_id grouping and client_id replay semantics. Some constraints are repeated from the schema, keeping it from a 5.

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

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

The description opens with a specific trigger and verb: 'Use this when the agent needs a human decision and should wait for a typed answer,' and follows with 'Sends a question email to every verified owner.' This distinguishes it from the fire-and-forget sibling cooper_notify_owner, which it references only for shared limits.

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

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

It clearly states the condition for use (needs a human decision and must wait for a typed answer), which implicitly excludes synchronous alternatives. It does not explicitly name cooper_notify_owner as the alternative when waiting is unnecessary, so there is no explicit 'when not to use' 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?

Much richer than the annotations: it discloses auth and permission requirements, renew semantics, that a renew emits no thread.assigned event, the 409 thread_claimed conflict shape with assignee/claimed_until, and the non-exclusive default when lease_seconds is omitted. These are exactly the mutation traits the readOnly/idempotent hints cannot convey, though the return contract is largely duplicated from the output schema.

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

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

The lead sentence is well front-loaded with the trigger scenario, but the 'Inputs:' block restates nearly every schema constraint verbatim (assignee charset, note limit, lease range, force default), which is redundant with structured fields. The tail of the paragraph is a dense run-on of error codes and a return shape that the output schema already covers.

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 six parameters, the description covers authentication, conflict behavior, renewal, error codes (thread_claimed, thread_not_found, inbox_not_found, invalid_*), and the default non-exclusive case. Nothing an agent needs to invoke it safely is missing, even though the output schema makes the return-value sentence optional.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics: lease_seconds makes the claim exclusive and sets claimed_until to now plus the lease, force overwrites another assignee's active claim, and omitting note preserves while null clears it. The character-class and range repetitions add little beyond the schema.

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

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

The description names a specific verb pair and resource ('hand a thread to a named assignee', 'take an exclusive claim') and gives the operational distinction between a plain assignment and an exclusive lease. An agent can distinguish this from cooper_update_thread or cooper_unassign_thread without inspecting 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?

It states the two concrete situations that call for this tool (triage handoff, worker exclusive claim so another worker doesn't double-reply), which is strong when-to-use guidance. It does not explicitly mention alternatives such as cooper_unassign_thread or cooper_update_thread, so routing against siblings is left partly to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description still adds real context by noting 'requires auth', 'no inputs', and the addons.available condition on Starter and Pro. The return-shape sketch is largely redundant with the existing output schema, which keeps this below 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?

Front-loaded with the use case, then behavior, then the return shape, then the sibling pointer — a sensible ordering with no filler sentences. The long inline enumeration of return fields is the one portion that costs more words than it earns, since an output schema already 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?

Covers purpose, prerequisites (auth), input expectations (none), return contents, and the follow-up tool for changes — everything an agent needs to call a zero-argument read tool correctly. The 402 diagnostic framing also ties it to the error path an agent is most likely to hit.

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

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

The tool takes zero parameters, so the baseline is 4, and the description correctly states 'no inputs' rather than leaving the agent to wonder whether a plan or period argument is needed. There is no additional parameter nuance to convey.

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

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

States a specific resource (the account's plan, quota usage, and limits) and a concrete diagnostic use case (explaining a 402 from send or inbox create). It is clearly separable from the write-side siblings cooper_set_addons and cooper_upgrade_link, which the description names explicitly.

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

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

Gives explicit triggers ('when you need to know the account's plan, how much of its monthly quota is used, or why a send or inbox create returned 402') and routes the mutation case to the correct alternative: 'Buy or change those quantities with cooper_set_addons.' An agent does not need to guess between this and the addon/upgrade tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered by structured data. The description still adds value beyond that: required scope (task_read), page ordering, and an explicit trust-boundary warning that owner messages are authoritative instructions while quoted email/web content inside them is untrusted data. It stops short of describing end-of-history/page-empty behavior, which keeps it from a 5.

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

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

Front-loads what the tool returns before the operational constraints, and the security warning lands where an agent will read it. A few clauses ("limit is 1 to 100", "before is an opaque cursor") duplicate schema text and could be trimmed without losing meaning.

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

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

An output schema exists, so return shape need not be explained, and the description covers auth, paging direction, conditional inbox scoping, ordering, and the live-loop alternative. The main omission is what an exhausted history or empty page looks like, which matters for a cursor-paged reader.

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 percent, so the schema already documents limit, before, and inbox_id in nearly identical wording. The description mostly restates those constraints; its only real addition beyond the schema is the within-page ordering ("oldest first"), 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 ("Read earlier chat messages in both directions") plus ordering semantics ("oldest first inside the page"). It implicitly distinguishes itself from cooper_chat_wait by telling the agent to loop that tool for live traffic, so an agent can route between them without opening either schema.

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

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

Gives concrete preconditions (auth plus task_read) and the conditional rule for when inbox_id can be omitted. It also names the alternative for live streaming (cooper_chat_wait in a loop), which is a real when-not signal, though it never explicitly contrasts with cooper_list_messages or cooper_search_messages.

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 non-readonly, non-idempotent, non-destructive, closed-world; the description adds the substantive behavior: this may silently create an account, an inbox, and an API key, and the key is returned only once. It also discloses a privacy detail (owner's full email not returned). It does not say what happens on an invalid or already-consumed pair code, which would complete the picture.

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

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

Four short sentences, front-loaded with the core action and immediately followed by the conditional paths; no filler. The telegraphic phrasing ("With a key, it links that key's inbox") is efficient, though the mode-switching could be structured more explicitly for a reader scanning conditions.

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

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

An output schema exists, so return values need not be described, and the description still flags the one-time API key and withheld email. Annotations cover the safety profile. What is missing is failure-mode behavior (expired/invalid code, repeat joins), which matters for a non-idempotent account-creating call.

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 code, inbox_id, username, and display_name, including the 'ignored when a key is sent' caveat. The description restates the same conditional logic at a high level rather than adding format, validation, or constraint detail beyond it. Baseline 3 applies when the schema carries the parameter burden.

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

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

The description gives a specific verb and resource ("Join a human's Cooper chat with a pair code") and immediately explains the two operating modes: no key creates an account/inbox/API key, a key links that key's inbox. That is far more than a restatement of the title. It does not name sibling tools such as cooper_onboard, cooper_create_inbox, or cooper_wait_for_code, so the agent must infer the boundary itself.

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

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

It clearly states the conditions that select each path: no key = account creation, key present = link, account-wide key = must pass inbox_id, inbox-limited key = uses that inbox. This is real branching guidance rather than vague context. It stops short of explicit exclusions or naming an alternative tool for related flows, so it is not a 5.

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

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

Adds real behavior beyond the annotations: idempotentHint=false is expanded with the client_id dedupe rule and the warning that a second call without it posts again. It also discloses the trust model (owner messages authoritative, quoted email/web content untrusted) and the conditional applicability of task_status, which annotations alone would 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 action and required auth, then walks parameters in schema order; nearly every sentence carries a rule. It is dense, with several clauses crammed into single sentences, so it reads as a checklist rather than flowing prose but wastes little.

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

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

With an output schema and annotations present, the description covers auth, required fields, idempotency, and the polling loop needed to use it correctly. Only notes on rate limits or error behavior are absent, which is a minor gap for a 6-param write 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; the description still adds value by explaining the token-scoping logic for inbox_id and the consequence of omitting client_id. It largely mirrors the schema's per-parameter text, so it does not reach 5.

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

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

States a specific verb and resource: 'Post a message to the verified owner,' which is more precise than the title and clearly places it in the owner-chat family. It does not name sibling alternatives (e.g. cooper_send_message, cooper_notify_owner, cooper_reply_task), so an agent still has to infer the boundary, keeping it below 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 concrete conditions: requires auth and task_reply, inbox_id optional only for a single-inbox token, and a keep-polling loop with cooper_chat_wait. It does not say when to prefer a different send/notify tool, so 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?

Beyond the annotations it discloses that auth and task_reply are required and that the typing indicator expires after 8 seconds, which an agent cannot infer from idempotentHint/destructiveHint alone. It adds no contradiction with readOnlyHint=false, since this is a state-setting write, and idempotentHint=true is consistent with a repeatable indicator flag.

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

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

The core facts are front-loaded, but the two sentences about owner messages being instructions and quoted email being untrusted data are tangential to setting a typing indicator and dilute an otherwise short description. The inbox_id rule also duplicates the schema wording almost verbatim.

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 an output schema, full parameter descriptions, and clear annotations, the description covers the remaining gaps: auth prerequisites, the 8-second lifetime, and the companion polling pattern. Nothing an agent needs to invoke this correctly is absent.

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

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

Schema coverage is 100%, so both parameters are already fully documented, including the enum values and the single-inbox token rule. The description restates the same facts (state values, optional vs required inbox_id) rather than adding new 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?

The opening sentence gives a specific verb and resource: signaling to the owner that this agent is typing. That is clearly distinct from cooper_chat_send (post a message) and cooper_chat_wait (block for a message), though the description never names those siblings as alternatives explicitly.

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

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

It states prerequisites (auth and task_reply) and the practical usage pattern: call with typing, and keep polling cooper_chat_wait in a loop to remain live. What is missing is an explicit exclusion, e.g. that this should not be used instead of actually sending a reply.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds what they cannot: required auth scope (task_read), the wait ceiling of 25 seconds, the returned object shape including owner_typing_until and timed_out, and a security posture warning that quoted email/web content inside owner messages remains untrusted. That is substantive behavior beyond 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?

Every sentence carries information and the most important constraint (auth, inbox_id conditionality) comes early. A few parameter facts, notably the wait default of 20 and the 25 cap, are restated verbatim from the schema, which is minor redundancy.

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

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

For a long-polling read tool, the definition covers authorization, cursor lifecycle across calls, return envelope, timeout semantics, and a safety caveat about untrusted embedded content. Even with an output schema present, the description supplies everything an agent needs to invoke this correctly in a loop.

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 adds real meaning on top: the wait default and hard cap, that after is an opaque cursor, the include default of 'owner' versus 'all', and the token-dependent requirement for inbox_id — useful clarifications even though some duplicate schema text.

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: 'Wait for the verified owner's next chat message.' That is clearly distinguishable from siblings such as cooper_chat_history, cooper_chat_send, and cooper_wait_for_message, and the 'verified owner' qualifier scopes the source precisely.

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

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

It gives explicit operational guidance: 'Keep calling cooper_chat_wait in a loop to stay live,' plus the conditional rule that inbox_id is optional for a single-inbox token and required otherwise. It doesn't explicitly name which sibling to use when you want history rather than a live wait, so it falls short of the top mark.

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

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

Goes well beyond the annotations by stating auth/message_read requirements, the monotonic no-op semantics for older cursors, and two specific failure modes (HTTP 400 invalid_cursor, HTTP 404 consumer_not_found). This is exactly the operational context annotations cannot convey.

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

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

Front-loaded with the trigger and auth, then inputs, then return and error semantics. Efficient, though the error-code sentences make it slightly dense and run-on; still every clause carries information.

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

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

Auth scope, input origin, return shape (consumer, committed cursor position), no-op behavior and two error cases are all covered; with an output schema present, the return explanation is a bonus rather than a necessity. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it clarifies client_id is the consumer id or original client_id, and that cursor is the evc1 cursor received from polling. That traceability of where the value comes from is value beyond the schema.

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

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

States a specific verb and resource ('commit' the cursor for the events consumer) and anchors it to a sibling ('after you have processed a page from cooper_poll_events'). An agent can immediately distinguish this from the poll tool and understand the pairing.

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

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

Gives an explicit triggering condition: use after processing a page from cooper_poll_events. It also documents the no-op case for an older cursor, so the agent knows when calling is harmless versus necessary.

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 (idempotent, non-destructive), the description discloses the auth requirement, the idempotent replay behavior ('a verified owner is returned again'), and the exact failure modes with status codes (confirm_invalid, confirm_expired, confirm_locked, owner_not_found, inbox_not_found). That is material context an agent can act on, though it doesn't say whether codes are rate-limited per attempt beyond confirm_locked.

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 trigger condition, then inputs, return shape, and error taxonomy in a tight sequence. The return-field enumeration is mildly redundant given an output schema exists, but the density of actionable information is high.

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

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

For a three-parameter confirmation mutation, the agent gets precondition, auth need, idempotent replay semantics, and every failure code. Restating the return schema is unnecessary since an output schema exists, which is the only real gap.

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

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

Schema coverage is 100% and the description mostly restates the schema (inbox_id accepting id/username/email, 6-digit code). Nothing about code formatting edge cases or owner_id scoping is added beyond structured fields, so baseline 3 applies.

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

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

The description states a specific verb and resource ('mark that owner verified') plus the precondition (human received the 6-digit code). It clearly distinguishes this from siblings like cooper_add_owner (registration) or cooper_wait_for_code (fetching the code).

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 a clear triggering condition: use when a human has the 6-digit code and you need to mark the owner verified to receive updates and open tasks. It doesn't explicitly name cooper_wait_for_code as the sibling that retrieves the code, so the hand-off between tools is left implicit.

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 (write, destructive, open-world, non-idempotent); the description goes far beyond that with permission requirements, failure semantics ('nothing is stored' on 403 and owner_required), the approval/send_mode flow for scheduled sends, and the client_id idempotency guarantee, which clarifies rather than contradicts idempotentHint=false.

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

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

It is front-loaded with the use case and permission model, and nearly every sentence carries operational weight. The single dense block is harder to scan than it needs to be, and the send_at permission rule appears both here and in the schema.

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

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

For a 17-parameter mutation with an output schema, this covers what is missing elsewhere: auth, permission variants, scheduling side effects, reply/forward derivation, idempotency, and error codes. An agent has enough to call it correctly and interpret failures without further lookups.

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 carries per-parameter meaning and the baseline is 3. The description adds real value on cross-parameter rules (omit to on a reply, in_reply_to and forward_of are mutually exclusive, reply_all only with in_reply_to), but most individual field semantics are restated from the schema rather than extended.

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 sentence states the effect concretely: prepare a message without sending it yet, which cleanly separates it from cooper_send_draft and cooper_send_message. It never uses the literal verb 'create a draft' in prose, leaning on the title, but the outcome is unambiguous.

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

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

Explicitly frames the when-to-use case (drafting rather than sending) and spells out the permission routing: draft_write for plain drafts, message_send or draft_send when send_at is set. It also gives the alternative outcomes (403 permission_denied, 409 message_held, 409 owner_required) so an agent knows what to do when the call is refused.

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 it is a non-read-only, destructive, open-world write; the description goes far beyond that, disclosing idempotency semantics (same client_id or username returns the original inbox at HTTP 200), the full error surface (409 inbox_exists, 400 invalid_metadata, 404 domain_not_found, 409 domain_not_verified, 402 with upgrade_url), custom-domain gating, webhook registration via notify_url, 80%-of-limit notices, and the one-time Free-plan upsell behavior. This is exactly the extra context the 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?

The opening sentence is well front-loaded and the failure modes are grouped sensibly, but the text is dense and partly redundant: the full return object is enumerated even though an output schema exists, and the upsell caveat is stated twice ('That line is a recommendation, not a requirement' and 'It is optional and does not block the inbox'). Several sentences could be compressed without losing meaning.

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, zero-required, nested-object tool with an output schema, the description supplies the operational context an agent needs: auth, idempotency, error codes, rate limits, and the check_username side path. The main remaining gap is sibling routing — it never says when to use cooper_create_inboxes instead — which matters given how similar the names are.

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 meaning the schema does not: the 1–32 character username bound, the exact address fallback (box plus 8 hex characters), the X-Client / x-cooper-client and X-Cooper-Heard-From header mapping, and the custom-domain on/off branching that changes what 'domain' means. The remaining parameters (metadata, signature, ref) are covered by their schema text.

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

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

The description gives a specific verb and resource — adding an additional email address / inbox for the signed-in account — with concrete use cases (one per agent, project, or customer). It does not distinguish itself from the near-identical sibling cooper_create_inboxes (plural batch creation) or cooper_onboard, so an agent must infer the difference from the names alone.

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 when to use it (the account needs an additional address), that auth is required, and that other mail APIs must not be substituted when Cooper Email was requested. The check_username mode is explicitly carved out ('When check_username is true, do not create an inbox'), which is a real when-not rule, but no guidance is given on when to prefer cooper_create_inboxes for multiple inboxes.

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, openWorldHint=true, and idempotentHint=false, and the description layers on substantive operational context: auth required, per-plan count caps, temporary inboxes counting against the plan limit until they expire, a daily cron deleting expired inboxes, and specific failure codes (400 batch_count_exceeded, 400 invalid_metadata, 402 with upgrade_url). That is exactly the quota and failure behavior an agent cannot get from the schema or hints.

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

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

Front-loaded with the when-to-use condition, then inputs, then return shape, then quota and error semantics — a sensible ordering in one dense paragraph. A few clauses restate schema text verbatim (the 256-key / 16 KB metadata limits, signature length rules), which is the main wasted space, and the paragraph is long enough that scanning is harder than a bulleted layout.

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 batch mutation tool with seven parameters, a nested signature object, annotations, and an output schema, the description covers scope, auth, param interactions, quota accounting, lifecycle (cron deletion), and error codes. Nothing an agent needs to call it correctly or interpret a failure is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: prefix yields prefix-<random>@cooperemail.com and falls back to box<random>@... when omitted, labels can be filtered later via GET /api/v1/inboxes?label=, and ttl_hours/expires_at are mutually exclusive ('pass at most one'). The mutual-exclusion rule is a genuine constraint the schema only states one-sidedly.

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

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

States a specific verb and resource with explicit batch scope ('several email addresses at once'), which separates it from the singular cooper_create_inbox by capability rather than by name. It also names concrete use cases (one inbox per signup, trial, or job), so an agent knows what shape of task it fits, though it never explicitly cites the single-create sibling as the alternative.

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 this when the signed-in account needs several email addresses at once, or addresses that should disappear after a deadline' gives a clear triggering condition plus example scenarios. It also flags the auth requirement. It stops short of a when-not rule (e.g., 'for a single address use cooper_create_inbox'), so the routing decision is implied rather than spelled out.

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

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

Annotations already flag destructive/idempotent, but the description adds substantial behavior: idempotency expressed as HTTP 201 vs 200, the enforcement consequences (block match rejects the address; non-empty allow list rejects everyone else), per-inbox list precedence, 403 recipient_blocked with no store or count, inbound blocks not stored plus a message.blocked event, verified-owner progress email exemption, and the 1000-entry cap. It also enumerates the failure codes (invalid_list, invalid_entry, list_full, inbox_not_found). This is far beyond what the annotations convey.

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

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

Front-loaded with the use case, then inputs, then enforcement and error behavior in a logical order. It is dense and telegraphic, however, and a few sentences (the per-inbox task allowlist note, the progress-email exemption) are narrow edge cases that lengthen it without helping tool selection.

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

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

For a destructive, multi-mode list mutation with an output schema, the description covers scope, enforcement effects, idempotency, limits and error cases. An agent has everything needed to invoke it correctly and anticipate outcomes, even though return values need not be spelled out.

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 enum values and inbox_id/entry semantics are already documented in the schema. The description restates the three required inputs and the optional ones almost verbatim, adding only light context such as account-wide scope and the reason note. Baseline 3 applies since the schema does the heavy lifting.

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

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

The opening sentence frames the intent (only mail approved recipients / ignore unwanted senders) and the input list makes clear this creates a list entry of type allow or block. Verb is implied by the title rather than stated directly in the description, and no sibling (e.g. cooper_delete_list_entry, cooper_list_list_entries) is named to sharpen the boundary, so it is clear but not maximally 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?

Explicit conditions are given: use when an agent should restrict outbound recipients or suppress unwanted senders, and 'omit inbox_id for the account-wide list' vs per-inbox scope. The direction semantics (send checks recipients, receive checks inbound, reply checks replies to an outbound Message-ID) directly guide selection. No explicit when-not-to-use or named alternative tool, which keeps it below 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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses failure semantics the agent could not otherwise know: 403 permission_denied with param actions stores nothing, 409 rule_limit at 20 rules, 400 invalid_rule, and 400 forward_target_not_allowed. It also explains idempotency concretely ('The same client_id returns the original rule and does not create a second one').

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 opening when-to-use sentence is properly front-loaded, but the remainder is a single dense run-on packing scopes, error codes, and per-parameter limits into one block with no grouping or line breaks. Nearly every fact earns its place, yet the lack of structure makes it harder 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 nested-object mutation tool this is thorough: auth scopes, cardinality limits, error codes, idempotency behavior, and nested field bounds are all covered, and the return value is summarized as the inbox_rule while a full output schema exists. An agent has what it needs to call it correctly and interpret failures.

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 a 3 is the baseline, but the description adds genuine constraints not present in the schema: from accepts an email, @domain, or bare domain; auth uses DMARC; forward_to must be another inbox on the account or a verified owner; auto_reply.text capped at 2,000 characters and cooldown 1–720 defaulting to 24. These are real additions rather than restatements.

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+resource ('Creating a rule', 'Returns the inbox_rule') and frames the intent as server-side mail handling ('labeled, filed, forwarded, or acknowledged on the server with no model call'). It does not explicitly name siblings like cooper_update_rule or cooper_list_rules, so differentiation is inferred from the create semantics rather than stated.

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

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

It gives a clear when-to-use trigger ('when mail like X should be labeled... with no model call') and lists prerequisites (auth plus message_update, message_send for forward_to/auto_reply). It does not point to alternatives for modifying or verifying a rule (update_rule, test_rule, list_rules), leaving that routing to inference.

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

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

Annotations only declare non-read-only, idempotent, non-destructive, closed-world; the description goes well beyond by disclosing that api_key is returned exactly once and is scoped to the sub-account, that the key is null on an idempotent repeat, that sub-account inboxes and sends bill against the parent's plan limits, and that nesting is not allowed. These are precisely the facts an agent cannot infer from 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?

The use case is front-loaded, then inputs, then return fields and billing caveats — a sensible order with no filler sentences. It loses a point for enumerating the full return object even though an output schema already exists, though the "api_key is returned only once" note inside that list does earn 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 state-changing, quota-affecting creation tool, the description covers the auth requirement, the billing coupling to the parent plan, the null-on-retry api_key behavior, and the nesting restriction. Nothing an agent needs in order to call this correctly or set expectations afterwards appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for client_id: the same key returns the original workspace and api_key comes back null. Name length and inbox_quota semantics largely duplicate the schema and add little.

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 concrete verb and resource — giving a project or another agent its own API key plus a fixed inbox quota — rather than restating the title. That framing separates it cleanly from siblings like cooper_update_workspace (editing an existing workspace) and cooper_create_inbox (adding an inbox inside an existing account).

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

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

"Use this when the signed-in parent account should give a project or another agent its own API key" is an explicit trigger condition, and "A sub-account cannot create another workspace" is an explicit exclusion. It stops short of naming a concrete alternative tool for the adjacent case (e.g. adding inboxes under the same account), so it is clear context without full alternative routing.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds material context the agent could not infer: the required auth scopes, that attachments are deleted along with the draft, and the 409 draft_sending failure mode for in-flight sends. That is exactly the pre-call risk information a destructive tool needs.

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 sentence order is well front-loaded: use case, then auth, then effect, then error, then return shape. The "Inputs: inbox_id (required), draft_id (required)" clause is pure duplication of the schema and could be dropped, but it costs only a few 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 two-parameter destructive delete, everything an agent needs is present: when to use, permissions, side effects on attachments, the one error case, and the response shape. Nothing is missing even though an output schema exists and would have covered the return value.

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 both parameters including the dft_ and inb_ id formats. The description only restates that both are required, adding no new meaning; 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 gives a specific verb and resource ("Deletes the draft") plus the scope detail that a scheduled send can be cancelled this way. An agent can distinguish it from cooper_update_draft, cooper_send_draft, and cooper_get_draft 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?

"Use this when a draft should be discarded, including a scheduled send you want to cancel" gives an explicit triggering condition and covers the non-obvious cancel-a-scheduled-send case. It stops short of naming the alternative tools (update_draft to modify, send_draft to send), so the routing is clear but not exhaustive.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real behavioral detail: the cursor is destroyed along with the consumer, auth plus message_read is required, and the 404 consumer_not_found conditions are spelled out.

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

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

Three tight sentences: what it does, what it requires, and what happens on error. The destination is front-loaded and nothing is padded.

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

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

Auth scope, destructive effects, and failure modes are all present, and an output schema exists so return values need not be spelled out. For a one-parameter destructive tool, this is close to 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 baseline is 3, but the description reinforces that client_id accepts either the evcon_… consumer id or the original client_id. That restates the schema rather than extending it, so the score stays just above baseline.

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

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

The description begins with a specific verb and resource: 'remove a durable event consumer and its cursor.' That is enough to distinguish it from near-siblings such as cooper_delete_event_subscription, though it never explicitly contrasts the two.

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

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

The phrase 'Use this to remove...' sets the operating context, and the description rules out two conditions that would fail: another account's consumer, and a consumer pinned to a different inbox than an inbox-scoped key. It stops short of pointing the agent to cooper_list_event_consumers for discovery or naming an alternative tool.

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 destructive and idempotent annotations, it discloses audit retention, the ended and retained result, cessation of delivery, exclusion from the 20-subscription cap, and exact repeat-delete behavior. It also documents authentication and webhook_write permission requirements, visibility-scoped 404 responses, and the 403 permission_denied failure mode.

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, followed by compact invocation, lifecycle, idempotency, and error details in a logical order. Although the input recap largely duplicates the schema, the description remains dense with operationally useful information and contains no filler.

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

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

For a one-parameter destructive mutation, it covers the id source, permissions, retained state, delivery effects, subscription-cap implications, repeated calls, and important error cases. An output schema is present, and the description still supplies the key returned-state semantics needed to predict the operation's effect.

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 the id prefix and its source in cooper_list_event_subscriptions. The description repeats that information and requiredness without adding new format, validation, or selection semantics, 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 opening sentence specifies the action, stopping, and the resource, an MCP event subscription, distinguishing it from sibling tools that delete consumers, webhooks, or other resources. Explaining that the row is retained with status ended further clarifies that this terminates delivery rather than physically deleting the record.

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

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

It explicitly says to use the tool when a subscription should stop and identifies cooper_list_event_subscriptions as the source of a valid id. It does not provide when-not guidance or explicitly contrast this operation with deleting an event consumer or webhook.

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 (destructive, idempotent, open-world), it discloses cascade behavior (messages are deleted too), an approval-mode 202 path that leaves the inbox present until a verified owner confirms an emailed link, the persistence of approval mode on username recreation, ownership scoping, and the inbox_not_found error for another account's inbox. It also warns that an API key cannot submit the confirmation link, which is real operational context an agent cannot infer.

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 use case and effect, then layers in caveats. A few sentences run long and split the ownership/approval narrative across several clauses, but nearly every sentence carries non-redundant 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 destructive single-parameter tool with an output schema, the description covers the cascade, ownership constraint, the approval-mode edge case, the error surface, and the auth limitation. An agent has everything needed to call it correctly and interpret the non-200 path.

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 already documents the inb_ prefix, username, and full email address forms. The description's 'inbox_id (required; inbox id, username, or email)' largely restates that, 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?

The description uses a specific verb and resource ('Deletes that inbox and its messages') and its effect (freeing the slot on the plan and workspace inbox quota) makes it trivially distinguishable from siblings like update_inbox, delete_thread, or delete_workspace.

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

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

It states a clear when-to-use condition: removal so the slot is freed on the plan and workspace quota. It does not explicitly name update_inbox as the alternative when the inbox should be kept and modified, so the routing guidance is good but not exhaustive.

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 destructive/idempotent annotations, it discloses that auth is required, that only one entry is affected, the exact success shape (list entry with deleted true), four specific failure codes including 404 list_entry_not_found, and that the per-inbox task allowlist is unaffected. That is precisely 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?

Telegraphic and dense but front-loaded: the when-condition leads, then auth, then scope, then inputs, then return/errors. Every clause carries information, though the compressed "Inputs:" list reads as schema echo rather than added value.

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

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

For a destructive four-parameter deletion with an output schema present, the definition covers trigger, auth, blast radius, error outcomes, and an explicit non-effect on the task allowlist. An agent has everything needed to call it correctly or decide not to.

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 four parameters including enum values and the "omit for the account-wide list" note. The description's enumerated inputs largely restate the schema, adding only the framing that entry accepts an email or domain, which the schema also states.

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: an address or domain leaving an allow or block list, and that exactly one entry is removed. This cleanly separates it from cooper_create_list_entry, cooper_get_list_entry, and cooper_delete_suppression without needing to open 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?

"Use this when an address or domain should leave an allow or block list" gives an explicit trigger condition, and the closing note that the per-inbox task allowlist is unchanged draws a scope boundary. It stops short of naming a sibling tool (e.g. cooper_list_list_entries to verify an entry exists first), so it is slightly under-routed versus 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 annotations (destructiveHint, idempotentHint, readOnlyHint), the description discloses the cascade deletion of auto-reply cooldown rows, the required auth scope (message_update), and the exact failure modes: 404 rule_not_found for an unknown rule and 404 inbox_not_found for another account's inbox. These are concrete behavioral facts an agent needs before a destructive call.

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

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

Purpose is front-loaded in the first clause, followed by prerequisites, inputs, return value, and error codes in that order. Every sentence carries decision-relevant information; the brief restatement of required inputs is the only mild redundancy.

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

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

For a destructive two-parameter mutation with an output schema, the description covers the cascade effect, auth scope, success shape, and both 404 cases. Nothing an agent needs in order to call it safely and interpret failure is missing.

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

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

Schema description coverage is 100% and both parameters carry their own descriptions, so the baseline is 3. The description only restates that both inputs are required, adding no format, ownership, or resolution detail beyond the schema.

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

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

States a specific verb and resource ('remove one inbox rule') plus the scope of the cascade ('and its auto-reply cooldown rows'), which an agent could not infer from the tool name alone. It is cleanly distinguishable from sibling mutations like cooper_delete_inbox or cooper_update_rule by resource name.

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 this to remove one inbox rule' gives clear context for when to invoke it, and the cascade note signals a side effect that matters when deciding to delete vs. update. It stops short of naming alternatives (cooper_update_rule to disable, cooper_list_rules to resolve a rule_id), so no explicit when-not guidance is offered.

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, which only give destructive/idempotent/readOnly flags. The description adds the removal scope (one account-wide row), the auth requirement, the exact success shape, concrete failure codes (400 invalid_address, 404 suppression_not_found, 403 permission_denied), and the downstream consequence that mail to a still-suppressed address is refused with 403 recipient_suppressed. That last sentence is about sending, not deleting, but it supplies useful behavioral context.

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 dense and front-loaded: usage trigger, prerequisites, scope, inputs, return shape, and failure modes arrive in a logical order. The final sentence about sending to a still-suppressed address is tangential to this tool and slightly dilutes focus, but it is short and informative.

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

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

The definition is complete for a single-input destructive tool: it covers when to call it, what is removed, what the caller needs, the success response, and every documented error path. An output schema exists, so the return-value sentence is a bonus, not a 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?

This is a single-parameter tool, and the schema already documents it at 100% coverage, so the baseline is 3. The description only adds that the address is an email and is required, which is already in the schema, so no extra meaning is contributed.

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: deleting one address from the account-wide suppression list. It also names the conditions that put an address on that list (bounce, complaint, manual add), so an agent can tell it apart from cooper_list_suppressions and the delete_* siblings 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?

Opens with an explicit trigger condition: use this when an address should receive mail again. It also states the auth prerequisite. It does not name a sibling alternative (e.g., cooper_list_suppressions for inspection), so routing is slightly inferential, but the when-to-use case is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real value beyond them: auth requirement, the exact set of related records destroyed, what is deliberately left intact (owner tasks and updates), irreversibility, and the specific error outcomes (thread_not_found, inbox_not_found) with their HTTP mapping.

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 decision criterion, then consequences, then the explicit 'Inputs:' and 'Returns:' blocks. Every sentence carries information — destruction scope, irreversibility, alternative, errors — with no filler.

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

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

For a two-parameter destructive tool, the definition covers safety, side effects, alternatives, error cases, and the return shape ({id, deleted:true, messages_deleted}). An output schema exists and annotations cover read-only/destructive semantics, so nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description's inline restatement of inbox_id (id, username, or email) largely duplicates the schema text. Its only added semantic is tying parameter misuse to concrete failures — an unknown thread yields 404 thread_not_found and another account's inbox yields inbox_not_found.

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

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

States a specific verb and resource (permanently remove an entire conversation) and immediately enumerates what that entails: all messages, attachment bytes, search rows, the assignment, and the folder row. It distinguishes itself from sibling mutations by naming cooper_update_thread and cooper_move_threads as the non-destructive alternatives.

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

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

Gives an explicit trigger ('when a whole conversation should be removed permanently') and an explicit exclusion with the alternative tools ('To keep the thread for 30 days, move it to trash with cooper_update_thread or cooper_move_threads instead'). The decision between permanent deletion and trashing is fully routed.

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 adds genuinely extra context: auth is required, the response shape is {id, deleted:true}, and the specific failure mode is 404 webhook_not_found for a missing or foreign 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?

Five short sentences, front-loaded with the usage condition and answerable in a glance. The sentence 'This removes the hook.' is largely redundant with the opening clause, a small amount of waste in an otherwise tight definition.

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, the description covers when to call it, the auth requirement, the success return, and the specific error case, while annotations carry the safety and idempotency hints. Nothing an agent needs in order to invoke it correctly appears to be missing.

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

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

Schema coverage is 100% on the single parameter, so the schema already documents webhook_id and its wh_ prefix format. The description repeats 'webhook_id (required)' and adds only the account-scoping nuance that an id belonging to another account yields 404, which is marginal added meaning over the schema.

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

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

States a specific verb and resource: 'a webhook should stop receiving events and be removed', naming the exact object acted on. It is clear against register_webhook/update_webhook/list_webhooks by name, but it does not distinguish itself from the closely related cooper_delete_event_consumer and cooper_delete_event_subscription siblings.

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

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

Gives an explicit usage condition - use it when a webhook should stop receiving events and be removed - which tells the agent the intended moment to call it. It stops short of naming alternatives (e.g. update_webhook to merely disable, or deleting an event subscription instead) or stating when not to use it.

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

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

Annotations already declare destructive and non-read-only, but the description goes well beyond: it enumerates the full deletion cascade (messages, attachments, owners, tasks, keys, tokens, webhooks, domains), the two 409 paths that delete nothing, and post-conditions (child key returns 401, parent usage no longer counts the sub-account). That is exactly the behavioral context an agent needs before an irreversible call.

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

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

Front-loaded with the trigger, then inputs, then outcomes and error codes in a predictable order; nearly every sentence carries a distinct failure or side-effect. Minor waste in the trailing run-on and the repeated '403 permission_denied' for two different key types.

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

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

For a destructive cascade delete, the description covers trigger, inputs, return shape reference, every error branch, and post-conditions; an output schema exists so return values need no further expansion. Nothing needed to call it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema only summarizes: omitting delete_inboxes on a non-empty workspace yields 409 workspace_not_empty with no deletion, and true can still 409 owner_required in approval mode. It does not restate workspace_id format, which the schema covers.

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 ('remove a sub-account') plus the cascade scope ('its API key, and its mail'), which distinguishes it from cooper_delete_inbox and cooper_update_workspace without needing 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 frames the trigger ('Use this when a parent should remove a sub-account') and the conditions under which it refuses (inboxes present without delete_inboxes, approval-mode owner, wrong-parent 404, sub-account/inbox-scoped key 403). No sibling alternative is named, 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?

Goes far beyond the annotations (idempotent, openWorld, non-destructive): it discloses secret-revealed-once vs redacted behavior, HTTP 201/200 status codes, that a second call updates the same hook, that localhost/private addresses are rejected, which events the hook registers for, and the exact delivery/body semantics. That is unusually rich behavioral detail for a mutation tool.

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

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

Purpose and the key alternative are front-loaded, which is good, but the body becomes a dense run-on block covering return shapes that the output schema already conveys. The information is mostly valuable, yet it would read far better as short bullet points than as a multi-clause paragraph.

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 nested header objects, one-of-required logic, delete semantics, and side effects on multiple event types, the description covers calling context, edge cases (private addresses rejected), and update/delete semantics. Nothing an agent needs in order to invoke it safely is missing.

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

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

Schema coverage is 100%, so the schema already documents url, enabled, headers, and inbox_id in nearly the same words (including header retention, empty-object clearing, and 'required unless enabled is false'). The description largely restates these rather than adding new 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?

Names a specific verb+resource ('enable instant replies' / wake webhook) and states its effect precisely: an owner message wakes the agent within seconds. It is clearly distinguishable from siblings like cooper_register_webhook, cooper_update_webhook, and cooper_delete_webhook.

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 alternative ('events/subscribe for message.received is cheaper and needs no URL') and the condition that selects it ('if this client can receive a callback'). It also clarifies coexistence with POST /api/v1/webhooks, so an agent knows when this tool is and isn't the right choice.

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 (which already declare destructive, open-world, non-idempotent), it discloses that real email is sent, auth is required, the signature is placed above the forwarded block, attachment size caps, and that retries with the same client_id do not resend. It enumerates failure codes and pause-recovery behavior, though it does not describe the returned payload's fields in detail.

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 front-loaded and useful, but it is delivered as one very long paragraph mixing purpose, parameters, return value, and a dozen error codes; the error-code enumeration in particular is low-density for the space it consumes.

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 an 11-parameter, destructive, open-world send operation, the description covers triggering conditions, defaults, side effects, idempotency, error recovery, and the return value (stored message with a new thread_id); an output schema exists so return details need not be spelled out further.

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

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

Schema coverage is 100%, so baseline would be 3; the description earns extra credit by adding meaning not in the schema, such as where the signature sits relative to the forwarded original and the aggregate cap logic for copied attachments.

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 plus resource ('forward a stored message to someone else') and adds the key scoping detail 'on a new thread', which distinguishes it from reply/send siblings without needing to name them.

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

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

'Use this when you need to forward a stored message' gives clear triggering context and the 'new thread' phrasing implicitly separates it from replying in-thread, but no alternative tool is named explicitly for cases where a reply or fresh send is actually wanted.

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 read-only and idempotent annotations, it discloses authentication, supported extraction types, fallback behavior, truncation and size limits, timeouts, cached failures, authorization errors, held-message behavior, and the untrusted nature of extracted text. These details materially support error handling, retry decisions, and safe use of the result.

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 and logically ordered, but it becomes an excessively long paragraph that repeats both input and output structured fields. Low-level archive-validation details such as the 'lying central directory' check and legacy spreadsheet declarations, along with the exhaustive error catalog, make it substantially over-specified for tool selection and invocation.

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

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

For a four-parameter read operation with nontrivial extraction behavior, the description covers authentication, format selection, supported types, output distinctions, limits, errors, caching, authorization, and content-safety considerations. Together with the fully documented input schema and output schema, it leaves no material gap needed to invoke the tool correctly, although much of it could be condensed.

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

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

The schema already documents all four parameters, and the 'Inputs' sentence largely repeats it, including the format default already present in the schema. It nevertheless adds useful format-dependent semantics, including supported extraction types, different size and failure behavior for text versus base64, and inbox-scope error handling.

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 precisely identifies the operation, resource, and scope: retrieving the text or base64 bytes of one attachment. This clearly distinguishes it from cooper_get_message and the list/search siblings, even without explicitly naming an alternative.

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

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

The phrase 'Use this when you need the text of one attachment, or its bytes as base64' provides an explicit selection condition, and the fallback behavior helps guide format selection. It lacks an explicit when-not case or sibling alternative, such as using cooper_get_message for message-level information.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds real value beyond them: required auth, the message_read scope, and precise failure semantics (404 inbox_not_found for another account's inbox or a mismatched inbox-scoped key, 404 draft_not_found for an unknown draft). That cross-account/authorization behavior is exactly what an agent needs and is not derivable from 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?

Front-loaded with the use case, then auth, inputs, return, and error cases in tight sequence with no filler. The 'Inputs: inbox_id (required), draft_id (required)' clause lightly duplicates the schema and could be dropped.

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

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

An output schema exists, so return shape needn't be explained, and the description still surfaces the salient fields plus the full error surface. For a two-parameter read tool, an agent has everything needed to invoke it correctly and interpret failures.

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

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

Schema description coverage is 100%, so both parameters are already fully documented including the dft_/inb_ id formats. The description only restates that both are required, adding no new meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('get one draft') and enumerates what the payload contains (labels, attachments, send_at, send_status, approval_status), which clearly separates it from list_drafts and create/update_draft. It stops short of explicitly naming a sibling as the alternative, but the singular-resource framing is unambiguous.

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

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

'Use this when you need one draft' gives a clear retrieval trigger and implicitly contrasts with list_drafts. No exclusion cases or named alternatives are given, which keeps it at 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?

Goes well beyond the annotations (readOnlyHint, idempotentHint, openWorldHint=false) by disclosing the auth/scope requirement ('requires auth and message_read'), the specific error path ('HTTP 404 idempotency_key_not_found' for a missing key), and the scoping subtlety that 'an inbox-scoped key only sees a row for its inbox.' It also explains the semantically ambiguous 'unknown' state, which the annotations cannot express.

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 purpose, then inputs, then return shape, then states, then error and scoping edge cases — a well-ordered spec-style layout. Slight redundancy: the three states are listed in the opening sentence and then re-enumerated in 'state is in_progress, done, or unknown,' which duplicates rather than adds.

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

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

For a single-parameter read tool with an output schema, the description is complete: purpose, required scope, return fields (though the output schema carries those), error semantics, and the inbox-scoping caveat that could otherwise cause an agent to misinterpret a 404 or a missing row. Nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100%, so the single parameter's format (1-256 chars, allowed character set) is already fully documented in the schema. The description only restates 'key (required; the Idempotency-Key value)' and adds the mild extra that keys can be inbox-scoped, which affects which row is visible; that is a marginal gain over the schema baseline.

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

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

States a specific verb and resource ('see whether an Idempotency-Key is in progress, done, or unknown') and enumerates the exact states it returns, so an agent knows precisely what question this tool answers. It is distinguishable from the mutating siblings cooper_resolve_idempotency_key and cooper_release_idempotency_key by being framed purely as a status read.

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?

Clear context for use is given: checking whether an earlier send is in flight, completed, or of unknown delivery status, plus the caveat that 'unknown means an earlier send may or may not have been delivered.' What's missing is explicit routing to alternatives (resolve/release) or a when-not-to-use condition, so the agent must infer that this tool only reads and never mutates the key.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds context the annotations cannot: it requires auth and that another account's inbox surfaces as HTTP 404 inbox_not_found. It does not cover rate limits or pagination, but none apply to a single-resource get.

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 use condition, then auth/behavior, then inputs, then return shape and error semantics — a clean scan order with no filler sentences. The enumerated return fields are dense but each carries information an agent may need to decide whether this call answers its question.

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

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

For a single-parameter read tool with a full output schema, the definition covers auth, the lookup key variants, error semantics for cross-account access, and the meaning of ambiguous fields (send_mode values, nullable signature). The return-field list partly duplicates the output schema, so it is thorough rather than perfectly lean, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already says inbox_id accepts an 'inb_…' id, username, or full email address; the description's 'Inputs: inbox_id (required; inbox id, username, or email)' largely restates it. The extra detail about send_mode values and signature shape describes outputs, not input meaning, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('one inbox') and enumerates exactly which fields it exists to retrieve (address, display name, metadata, status, client_id, screening, send_mode). The 'one inbox' scoping plus the id/username/email lookup key clearly separates it from cooper_list_inboxes and cooper_update_inbox for an agent scanning siblings.

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 this when you need one inbox's ... and you already have its id, username, or email' gives a clear use condition plus the invocation precondition (you must already have an identifier, so this is not a discovery tool). It does not name an explicit alternative (e.g. list_inboxes for when you lack an id) or state when not to use it, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' largely repeats structured data. The description does add genuine value with the auth requirement and the enumerated failure modes (400 invalid_list, 400 invalid_entry, 404 list_entry_not_found / inbox_not_found), but says nothing about matching behavior or how an absent entry differs from an error.

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, then behavior, then inputs, then return shape and errors — a sensible ordering with no filler prose. It is dense, and the inputs clause partially duplicates the schema, which keeps it from being maximally efficient.

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

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

For a simple read-one tool, the description covers purpose, auth, parameters, return fields, and error codes. Because an output schema exists, the inline return shape is redundant rather than required, so there is minor over-coverage but no meaningful gap.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including enum values and the 'omit for the account-wide list' note. The description's inputs sentence restates the same information without adding syntax, format, or resolution 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 gives a specific verb+resource ('need one address or domain on an allow or block list') and the singular 'one' implicitly separates it from the sibling cooper_list_list_entries. It stops short of naming that sibling outright, so an agent must infer the pairing.

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 this when you need one address or domain' sets a clear selection context, and the presence of cooper_create_list_entry / cooper_list_list_entries / cooper_delete_list_entry in the sibling set makes the read-one role obvious. It offers no explicit when-not or prerequisite conditions, keeping it below 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 read-only and idempotent, yet the description adds substantial non-structured context: auth is required, the body is untrusted sender data, held messages return empty text/html/extracted_text/attachments until cooper_release_message, and screening is a heuristic rather than a guarantee. It also enumerates the failure modes (404 inbox_not_found, 404 message_not_found).

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 use case, then structured inputs, returns, and edge cases. It is dense and long, but nearly every sentence carries operational information (safety field semantics, release_message gating). Minor deduction for the compressed multi-clause sentences that make the safety explanation harder 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?

Even though an output schema exists, the description supplies the interpretive layer the schema cannot: score range, verdict threshold at 40, mode values, reason codes for unscored bodies, and when safety is null (outbound or pre-screening). For a read tool whose payload can be empty or untrusted, nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by noting inbox_id may be an id, username, or email and that message_id typically comes from cooper_list_messages or cooper_search. It does not add format/precedence rules beyond the schema, so it stops short of a 5.

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

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

States a specific verb and resource ('full content of one message') and immediately distinguishes scope from siblings by naming cooper_list_messages and cooper_search as the producers of the id. An agent can tell this fetches a single message rather than listing or searching.

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

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

Gives an explicit trigger ('when you need the full content of one message'), routes the agent to the right upstream tools for obtaining message_id, and names cooper_release_message as the required follow-up for held messages. That covers both when to use it and what to do when its output is suppressed.

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 read-only, idempotent, and nondestructive annotations, it discloses authentication and message_read requirements, UTC buckets, zero-rate behavior, account and key scoping, held-body exclusion, and specific 400, 403, and 404 failure modes. Its statement that the tool is read-only is consistent with 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 description front-loads selection criteria and then proceeds logically through inputs, outputs, errors, and visibility rules. Its dense single paragraph and repetition of schema defaults and output shapes reduce scanability, although nearly all of the detail is operationally useful.

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

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

For a three-mode, six-parameter tool, it covers mode selection, defaults, account scope, output meanings, bucket and date behavior, authorization, and error handling. Additional details about storage calculation, event labels, zero rates, and sub-account visibility leave no material invocation 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 already 100%, and much of the Inputs section repeats enums, optionality, and defaults. It still adds valuable cross-parameter semantics, including kind-specific applicability, timestamp and range validation with error codes, unknown-value handling, and inbox/key scope interactions.

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 identifies three concrete jobs: mail counts over time, current usage, and bounce/complaint rates for this account. This clearly distinguishes the tool from message and thread retrieval, search, and raw event-listing siblings.

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 this when" provides explicit selection context, and the kind-specific details clarify when to choose events, usage, or rates. It does not provide when-not guidance or name alternatives such as cooper_list_events or cooper_search_messages for different needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real context beyond them: auth is required, the optional-parameter combination changes the result ('both together return that owner's effective style'), and the note field is explicitly framed as a preference rather than an instruction to act on. That last point is important prompt-safety guidance an agent would otherwise lack.

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 when-to-use clause and then the mechanics, with no filler sentences. The inline enumeration of the return object is somewhat redundant given an output schema exists, though the style/source/note glosses carry meaning the schema may not.

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

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

For a two-optional-parameter read tool, the description covers purpose, prerequisites, parameter combination behavior, and the meaning of the returned style, source, and note values. Nothing an agent needs in order to call and interpret it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: passing inbox_id and owner_id together yields that owner's effective style, and owner_id is optional. It doesn't explain what happens with inbox_id alone, leaving one combination unexplained.

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

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

The description states a specific verb and resource: read how a given owner wants Cooper email written, and frames it as the read-side counterpart to cooper_notify_owner and implicitly to cooper_set_owner_preferences. An agent can tell exactly what it retrieves (style, note, source) 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?

It gives explicit when-to-use guidance ('Use this before writing to a human owner') and names the sibling that follows it (cooper_notify_owner). It does not state when not to call it, nor explicitly route to cooper_set_owner_preferences for changing a style, so it stops short of full alternative coverage.

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