Cooper Email

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

Far beyond the annotations: it discloses idempotent re-call behavior, the exact returned record set, status transitions (pending until DNS matches), per-record status/hint semantics, automatic vs manual dns.mode, the webhook event to subscribe to, and cleanup semantics with cleanup_failed/deleted. This is the kind of behavioral detail that would otherwise be invisible.

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

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

The description is a dense wall of text with real redundancy: 'Cooper does not register a domain or create a zone' and the dns.mode automatic-only condition each appear twice, and the DNS record enumeration is repeated. The critical routing facts are buried mid-paragraph rather than front-loaded, hurting scanability.

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 no output schema and non-trivial side effects, the description is unusually complete: it documents the return shape, error codes, plan limits, DNS record publication, verification gating, and teardown behavior. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description restates domain (required hostname) and client_id (optional idempotency key) but adds no syntax or constraint detail beyond the schema. Baseline 3 is correct 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 opening states a specific trigger (user wants mail on their own hostname) and names the plan gating (Starter or Pro), which pins down the resource precisely. It also names siblings cooper_list_domains and cooper_verify_domain, so the agent can separate this create/attach operation from listing and verification.

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 when-to-use ('user wants mail on their own hostname and the account is on Starter or Pro'), plus explicit exclusions and error routing (Free returns HTTP 402 plan_limit_exceeded, 409 domain_exists, 400 invalid_domain). It also names the alternatives to reach for (cooper_list_domains, cooper_verify_domain) and the follow-up flow (POST /api/v1/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?

Adds substantial context beyond the annotations: auth is required, exactly one confirmation email is sent and nothing else until confirmation, the returned status lifecycle is spelled out, and idempotency is stated in plain language ('Calling again for the same email is safe'), aligning with idempotentHint=true and openWorldHint=true. It does not address why destructiveHint=true is set (what state is created/affected), leaving one annotation unexplained.

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

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

Front-loaded with the usage condition, then side effects, then inputs, then return shape — a sensible information order with no filler sentences. It is dense, but every clause (auth, single email, no further mail, idempotency) carries a decision-relevant fact.

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?

Despite there being no output schema, the description documents the return object and its status values, covers required auth, describes the email side effect and the pending-until-confirmed lifecycle, and confirms safe repeat calls. An agent has everything needed to call this correctly and to set expectations for the user.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds usable semantics: it labels which inputs are required vs optional and restates the digest default ('immediate (default)'), which helps an agent decide whether to supply digest at all. It does not add format or validation 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 ('Register a human owner') plus the observable effect (the human receives progress updates by email and can reply). It is clearly distinguishable from siblings like cooper_confirm_owner (which completes the flow) and cooper_notify_owner (which pushes an update).

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 when-to-use condition ('Use this when a human should receive the agent's progress updates by email and be able to reply with instructions'), which tells the agent the scenario that selects this tool. It does not name an alternative or an exclusion (e.g., 'use cooper_confirm_owner once they click the link'), so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' is partly redundant, but the description adds genuinely new context: auth is required, there are no inputs, and it enumerates the returned shape. It does not cover rate limits or error semantics beyond the 402 case.

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 this when' trigger followed by the return shape. The brace-delimited return enumeration is dense with an ellipsis, but since there is no output schema it earns its space.

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 no-arg read tool with no output schema, the description supplies the usage trigger, auth requirement, and the return fields, leaving nothing an agent needs to call it correctly unstated.

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

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

Zero parameters, so the baseline is 4; the description reinforces this with 'no inputs', which is the only parameter-relevant statement needed for a no-arg tool.

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

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

States a specific resource and what it reports: the account's plan, monthly quota usage, and the reason a send or inbox create returned 402. That is far more than a restatement of the title, though it never names a sibling (e.g. cooper_upgrade_link) to sharpen the boundary.

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

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

Opens with an explicit trigger — 'Use this when you need to know the account's plan... or why a send or inbox create returned 402' — which tells the agent exactly when to reach for it. No 'when not' clause or alternative tool is given, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds substantial context beyond them: 'Requires auth', the idempotency behavior in plain language ('A verified owner is returned again'), and the full failure surface (400 confirm_invalid/expired/locked, 404 owner_not_found/inbox_not_found). This is unusually rich 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?

Front-loaded with the usage trigger, then inputs, return shape, and errors in a logical order. Every sentence carries information, though the 'Inputs:' sentence duplicates the schema and could be trimmed for a five.

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

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

For a 3-param mutation tool with no output schema, the description covers everything an agent needs: precondition, auth requirement, return field list, idempotency semantics, and enumerated error codes. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including that inbox_id accepts an id, username, or email. The description's 'Inputs:' sentence largely restates the schema rather than adding syntax or format detail beyond it, 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 (mark verified), resource (owner), and mechanism (6-digit confirmation code), and clarifies the downstream effect ('so they can receive updates and open tasks'). This distinguishes it from sibling cooper_add_owner (which registers) and cooper_wait_for_code (which polls).

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 condition: 'Use this when a human received the 6-digit confirmation code.' That is a clear when-to-use. It does not, however, name an explicit alternative for the pre-code state (e.g., cooper_wait_for_code), so it falls short of full routing guidance.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true) by disclosing required auth/scopes, HTTP 409 outcomes (message_held, owner_required with 'stores nothing'), reply/forward body-merging rules, and the approval-mode emailing behavior of send_at. The client_id idempotency nuance is consistent with idempotentHint=false since idempotency is conditional.

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

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

Front-loads the purpose before diving into inputs, and every clause carries operational detail. However, the 'Inputs: ...' enumeration largely restates schema fields already documented at 100% coverage, making the paragraph longer than strictly necessary.

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 16-parameter mutation tool with no output schema, it covers auth, error codes, idempotency, reply/forward derivation, scheduling semantics, and notes the return (the draft). 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 coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: 'omit to on a reply' because recipients derive from the source, send_at sets the scheduled label, and a forward merges the original body/attachments. It also encodes the in_reply_to vs forward_of exclusivity and reply_all dependency.

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 (create draft) and resource, and immediately scopes it against the send path: 'prepare a message without sending it yet.' An agent can tell this apart from cooper_send_draft, cooper_send_message, and cooper_reply_message without opening a schema.

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

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

Gives a clear when-to-use condition (prepare without sending) plus conditional constraints (reply_all only with in_reply_to, include_attachments forward-only, send_at schedules). It does not name alternative tools like cooper_send_message or cooper_reply_message explicitly, so it stops just short of a full when/when-not/alternative statement.

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 past the annotations: it documents the returned object shape, idempotency-key behavior (same client_id returns the original inbox with idempotent true/HTTP 200), the full error surface (409 inbox_exists, 400 invalid_metadata, 404 domain_not_found, 409 domain_not_verified, 409 domain_receiving_not_ready, 402 with upgrade_url), rate limits (30/min per IP with rate_limited / username_check_unavailable / rate_limit_unavailable outcomes), plan-limit notices, and optional webhook registration semantics. This is exceptional disclosure 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?

Front-loaded with the triggering condition, but the body is a single dense block that restates many schema-level constraints (metadata limits, notify_url rules, check_username details) rather than keeping them in the schema. Each fact is useful, yet the structure could be tightened considerably.

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

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

For a zero-required-parameter creation tool with no output schema, the description supplies everything needed: required auth, input semantics, return shape, idempotency, error codes, rate limits, and webhook side effects. Nothing material 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 cross-parameter meaning: the address form depends jointly on username and whether custom-domain mail is on, the username generator ('box' plus 8 hex characters when omitted), and the domain verification/receiving preconditions. It largely mirrors the schema but integrates the parameters into address-formation rules.

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

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

States a specific verb+resource (create an additional inbox/email address) with concrete use cases (per agent, project, or customer). It never names the closely related batch sibling cooper_create_inboxes, though the singular/plural split makes the distinction inferable.

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

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

Gives a clear triggering condition ('when the signed-in account needs an additional email address') and explains the alternate check_username mode where no inbox is created. It does not point the agent to cooper_create_inboxes or cooper_onboard as alternatives for adjacent 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?

Adds substantial context beyond the annotations (which already flag destructive/write/open-world): temporary inboxes count toward the plan limit until the cron deletes them, the daily cron behavior, auth requirement, and specific error surfaces (400 batch_count_exceeded, 400 invalid_metadata, 402 with upgrade_url). This tells the agent exactly what side effects and failure modes to expect.

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 usage condition and auth requirement, then parameters, then return shape and errors. It is dense and reads as a long block, but essentially every sentence carries operational information an agent needs.

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

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

With no output schema, the description supplies the return shape ({object, data:[...]}) and the field list, plus plan-limit semantics and error codes. For a mutating batch tool with nested metadata constraints, this is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: the fallback address pattern box<random>@cooperemail.com when prefix is omitted, and the cross-field constraint to pass at most one of ttl_hours and expires_at. These are not obvious from the schema alone.

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

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

States a specific verb and resource with batch scope ('several email addresses at once'), which cleanly distinguishes it from the singular sibling cooper_create_inbox. The use-case framing (one inbox per signup, trial, or job) makes the tool's intent immediately legible without opening the schema.

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

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

Gives a clear when-to-use condition: when multiple addresses are needed at once or when addresses should expire after a deadline. It does not explicitly name cooper_create_inbox as the alternative for single-inbox creation, nor state when-not to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations: explains HTTP 201 vs 200 (confirming the idempotentHint), the recipient_blocked 403 behavior with no send/store/count, inbound block non-storage and the message.blocked event, the 1000-entry cap, and specific error codes. This is exactly the side-effect disclosure a destructive mutation 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?

Front-loads purpose and auth requirement before the input recap and behavioral consequences, which is good structure. It is dense and a few clauses (e.g. the progress-email exemption, the task allowlist note) sit at the tail, but each carries real behavioral information rather than filler.

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

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

For a mutation tool with no output schema, the description covers return shape ('Returns the list entry'), status codes, precedence of per-inbox vs account-wide lists, downstream effects, and failure modes. An agent has everything needed to call it correctly and anticipate consequences.

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 five parameters, including the enum semantics for direction and the account-wide-list meaning of inbox_id. The description restates those meanings ('send, receive, or reply', 'omit for the account-wide list') without adding new syntax or format detail, 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+resource ('Add an allow or block entry') and immediately frames intent ('when an agent should only mail approved recipients, or should ignore unwanted senders'). This distinguishes it from siblings like cooper_add_domain and cooper_delete_list_entry 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?

The opening sentence gives a clear when-to-use scenario (restrict to approved recipients vs. ignore unwanted senders). It does not explicitly name the alternative tools (e.g. cooper_delete_list_entry to remove, cooper_add_domain for domain management), so it stops short of full routing guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds substantial value beyond them: auth is required, api_key is returned only once, the key is scoped to that sub-account, usage counts against parent plan limits, and plan prices are unchanged. The idempotency behavior of client_id (same key returns the original workspace with api_key null) is also disclosed.

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 usage condition is front-loaded, followed by inputs, return shape, and behavioral caveats in compact sentences. Every sentence carries distinct information (auth, quota, idempotency, return fields, quota accounting, nesting limit) with no filler.

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

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

There is no output schema, but the description enumerates the return object ({id, name, inbox_quota, account_id, api_key, api_key_prefix, inboxes_used, created_at}) and flags the one-time api_key. Combined with the auth, idempotency, and billing caveats, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: inbox_quota is explained as the cap on inboxes the sub-account may hold, and client_id's reuse behavior is clarified with the extra detail that api_key is null on a replay. That goes beyond the schema 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?

The description states a specific verb and resource ('the signed-in parent account should give a project or another agent its own API key and a fixed inbox quota'), which clearly identifies it as a workspace/sub-account creation tool. This distinguishes it from siblings like cooper_create_inbox or cooper_list_workspaces, which operate on different resources.

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 the parent account should provision a project or agent) and a hard constraint ('A sub-account cannot create another workspace'). It does not explicitly name alternatives such as cooper_create_inbox, but the resource boundary makes the scope 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, idempotentHint=true and readOnlyHint=false, and the description goes well beyond them: required auth scopes (message_delete/message_send/draft_write), the cascading attachment deletion, and the HTTP 409 draft_sending failure case. That is exactly the extra behavioral context the structured fields 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?

Front-loaded with the usage trigger, then permissions, inputs, side effects, error case and return shape — nearly every sentence earns its place. The 'Inputs: inbox_id (required), draft_id (required)' clause is the one redundant piece since the schema already marks both required.

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 2-param tool with no output schema, the description covers auth, cascade behavior, failure mode, and even the return payload, so an agent has everything needed to call it correctly and handle errors.

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

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

Schema coverage is 100% and both parameters are fully documented there (draft_id as dft_…, inbox_id as inb_…/username/email). The description only restates that both are required, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (delete a draft) and immediately scopes it with 'including a scheduled send you want to cancel', which cleanly separates it from siblings like cooper_send_draft and cooper_update_draft. An agent can pick this tool without opening the schema.

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

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

Gives clear when-to-use guidance ('when a draft should be discarded, including a scheduled send you want to cancel'), which implicitly routes away from send_draft. It stops short of naming explicit alternatives or when-not-to-use conditions, so it is clear context rather than full routing.

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

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

Goes well beyond the annotations: describes the approval-inbox 202 flow, the verified-owner confirmation requirement, the sticky approval mode on recreation, cross-account inbox_not_found behavior, and the API-key limitation. These are exactly the edge cases an agent needs before calling a destructive 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?

Front-loaded with the 'use this when' trigger, then effects, then the approval-mode caveat. Dense and information-rich, though several clauses about the confirm token and mail flow could be tightened 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 destructive, open-world, non-idempotent-looking tool with no output schema, the description covers auth, side effects, the 202 approval path, error semantics, and return shape. An agent has everything needed to invoke correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates that inbox_id accepts id, username, or email, matching the schema but reinforcing it inline. Marginal added value, but accurate and consistent with 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?

Clear verb+resource (delete an inbox) with the secondary effect (frees slot on plan and workspace quota) stated up front. Distinguishes from siblings like cooper_delete_workspace and cooper_delete_thread by naming the specific resource and its side effects.

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

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

States the trigger condition (inbox should be removed, freeing quota) and starts with 'Use this when,' which is explicit usage guidance. It doesn't name alternative tools or compare against cooper_update_inbox, but the condition is clear enough to select this 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 annotations (destructive, idempotent, not read-only), the description discloses that auth is required, what the response contains ('the list entry with deleted true'), the specific failure modes and codes (400 invalid_list, 400 invalid_entry, 404 list_entry_not_found, inbox_not_found), and a non-obvious side-effect boundary regarding the per-inbox task allowlist.

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 usage condition is front-loaded, then deletion semantics, inputs, return, and errors in a tight sequence. No filler sentences; every clause carries operational information.

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

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

With no output schema, the description compensates by stating the return shape ('deleted true') and the error surface. For a one-entity destructive delete, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including enums. The description restates the same required/optional split and the 'omit for the account-wide list' nuance the schema already carries, adding no meaning beyond it. 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 ('Deletes that one entry') and resource (allow or block list entry), and the leading sentence frames the exact situation that triggers it. It is clearly separable from siblings cooper_create_list_entry, cooper_get_list_entry, and cooper_list_list_entries.

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 opening clause gives an explicit when-to-use condition ('when an address or domain should leave an allow or block list'), and the closing note scopes the effect ('The per-inbox task allowlist is unchanged'). It does not, however, name the sibling alternative for adding an entry, so routing is implied rather than stated.

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

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

With annotations already declaring destructiveHint=true and idempotentHint=true, the description still adds substantial context: auth requirement, that only one account-wide row is removed, the success payload ('deleted true'), the failure taxonomy (400 invalid_address, 404 suppression_not_found, 403 permission_denied for inbox-scoped keys), and an unusual inbox-scoped-key limitation. Nothing here contradicts the annotations.

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

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

Front-loaded with the usage trigger, then inputs, then return, then errors — a sensible ordering with little waste. The closing sentence about sending to a still-suppressed address describes a sibling tool's behavior and is mildly tangential, keeping it from a 5.

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

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

There is no output schema, so the description carries the return contract itself ('returns the suppression with deleted true') and the complete error surface, which is exactly what an agent needs to call and interpret this destructive tool correctly. No meaningful gap remains.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema as an email address to remove. The description's 'Inputs: address (required; email)' merely restates that, adding no format, normalization, or casing detail — 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 ('Deletes that one account-wide row' of the suppression list) plus the scenario that motivates it (an address should receive mail again). An agent can distinguish this from cooper_list_suppressions and from the send/reply tools without opening a schema, and the account-wide scope is called out 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?

Explicitly gives the trigger condition — use it when a previously suppressed address should receive mail again — and even enumerates the suppression causes (bounce, complaint, manual add). It lacks a when-not / alternative clause (e.g. pointing at cooper_list_suppressions to inspect before deleting), so it stops short of a 5.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds substantial context beyond them: exactly what is destroyed (all messages, attachment bytes, search rows), what is preserved (owner tasks and updates), that auth is required, and the specific 404 error codes returned. This is exactly the kind of side-effect disclosure 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?

Front-loads the use case, then what gets deleted, then the inputs, return shape, and errors in a tight sequence. The 'Inputs:' sentence largely repeats the schema so a small amount of space is not strictly earned, but the overall density 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?

With no output schema, the description supplies the return shape ({id, deleted:true, messages_deleted}) and the failure modes (thread_not_found, inbox_not_found), so an agent has everything needed to invoke and interpret the call. Complete for a two-parameter destructive tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates them, including the accepted inbox_id formats, adding only marginal value over the structured data; 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 ('Deletes every message in the thread') and precisely scopes the operation as removing a whole conversation. It is clearly distinguishable from siblings like cooper_delete_inbox, cooper_delete_draft, and cooper_delete_list_entry.

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 whole conversation should be removed' gives a clear triggering condition and implicitly frames the granularity (whole thread vs. individual items). It does not name an alternative tool or state when NOT to use it, and no sibling delete-message tool exists to route to, so this is clear context without 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?

Adds meaningful context beyond the annotations: auth requirement, the return shape {id, deleted:true}, and the 404 webhook_not_found failure mode including the cross-account ownership case. This enriches the destructive/idempotent hints the annotations already provide.

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 trigger, then packs auth, input, return, and error info efficiently. Mild redundancy between 'be removed' and 'This removes the hook,' but overall tight and well ordered.

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

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

With no output schema, the description supplies the return value, auth needs, and the key failure mode. Combined with annotations covering the safety profile, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, so the description's 'webhook_id (required)' is redundant. The id-format detail ('wh_…') lives in the schema, not the description, so no value is added over structured data.

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

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

States a specific verb (delete/remove) and resource (webhook) clearly: 'when a webhook should stop receiving events and be removed.' An agent can distinguish this destructive operation from register/update/rotate siblings, though it doesn't name those 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?

Gives a clear trigger condition ('when a webhook should stop receiving events and be removed'), which is enough context to select the tool. It does not state explicit when-not conditions or route to sibling tools like cooper_update_webhook or cooper_list_webhooks.

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

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

Goes well beyond the annotations: it enumerates the full destructive cascade (inboxes, messages, attachments, owners, tasks, then API keys, OAuth tokens, webhooks, domains, child account), states that the child key returns 401 afterwards, and documents error semantics (409 workspace_not_empty, 409 owner_required, 404 workspace_not_found, 403 permission_denied). This is exactly the extra context the 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?

Dense but well front-loaded: the trigger, auth, and destructiveness come first, then inputs, return shape, and error behavior. It is long for a delete tool and repeats the destructive/annotation-derived signal ('Destructive'), but nearly every sentence carries actionable information.

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

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

With no output schema, the description supplies the return shape ({id, deleted:true, inboxes_deleted}) and a comprehensive error matrix. For a cascading destructive operation, an agent has everything needed to call it correctly and interpret outcomes.

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 documented in the schema. The description restates them and adds the cross-parameter rule (delete_inboxes is effectively required on a non-empty workspace, otherwise 409), which is mildly useful but largely duplicates the schema. Baseline 3 is appropriate.

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

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

States a specific verb (remove/delete) and resource (sub-account, its API key and mail) with clear scope: a parent removing one of its sub-accounts. An agent can readily distinguish this from cooper_delete_inbox, cooper_delete_thread, or cooper_update_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?

Gives an explicit trigger condition ('when a parent should remove a sub-account') and the prerequisite context (parent-account ownership). It does not name alternative tools or explicit when-not-to-use cases, but the contextual framing is clear.

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

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

Annotations only declare the safety profile (openWorld, destructive). Beyond that the description discloses that auth is required, that it sends real email, that the client_id retry returns the original message without re-sending, attachment copy caps (10 files / 4 MiB each / 5 MiB total), the monthly send-limit 402, and the resulting new thread_id. This is materially more than the annotations provide.

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 'requires auth / sends real email' warning are front-loaded, and every error code and default rule earns its place. The inline re-enumeration of parameters is somewhat redundant against a schema that already documents them at 100%, making the single block denser than necessary.

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

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

No output schema exists, and the description compensates by stating the return value (stored message with a new thread_id) as well as auth, idempotency, size constraints, and the full failure taxonomy. An agent has everything required to invoke and interpret this 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 baseline is 3. The description adds real value beyond the schema by spelling out the subject default rule interplay, the attachments_too_large caps tied to include_attachments, and the client_id retry semantics, though much of the per-field text is restated from the schema.

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

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

States a specific verb+resource (forward a stored message) plus the distinguishing behaviors: a forwarded header block, original attachments, and a new thread. An agent can tell this apart from send_message, reply_message, and create_draft purely from the description 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 you need to forward a stored message to someone else" gives clear initiating context, and the error list clarifies failure conditions. It does not explicitly name alternatives (e.g. reply_message vs send_message) or state when not to use it, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: auth requirement, 200k character cap with truncation flag, 10 MB / 5 MB / 50 MB limits, decompression-bomb checks, 10-second extraction timeout, cached failures, and the explicit warning that attachment text is untrusted data. This is unusually rich behavioral disclosure.

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 and format default, then error conditions, so the important guidance comes first. It is dense and slightly bloated by the 'Inputs:' block that largely restates the 100%-covered schema parameters, but nearly every remaining sentence carries actionable information.

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

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

No output schema exists, yet the description fully documents both return shapes ({format, filename, content_type, text, truncated, empty} and the base64 variant) plus every error code an agent may need to handle. Nothing material is missing for correct invocation.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real value: it spells out the default resolution logic for format ('text when the content type can be extracted, otherwise base64') and enumerates extractable types, which the schema enum alone does not convey.

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

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

States a specific verb and resource ('get the text of one attachment, or its bytes as base64'), with a scope narrow enough to distinguish it from siblings like cooper_get_message or cooper_get_thread. An agent can route correctly 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?

Opens with an explicit trigger condition ('Use this when you need the text of one attachment, or its bytes as base64') and the format-omitted default clarifies selection between the two modes. It does not name the alternative sibling (e.g. get_message for the body), so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the required auth scope (message_read) and the two distinct 404 outcomes (inbox_not_found vs draft_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-loads the trigger condition and returned fields, then auth and error semantics. Every sentence carries information, though the explicit 'Inputs: ...(required)' restatement is mild redundancy against 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?

No output schema exists, so the description compensates by naming the fields a caller can expect (labels, attachments, send_at, send_status, approval_status). With auth, error codes and return shape all covered for a simple 2-param read, nothing material is missing.

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

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

Schema coverage is 100% and both parameters carry their own format hints (dft_…, inb_…/username/email), so the schema does the heavy lifting. The description adds only that both are required, which the schema already encodes via the required array.

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 the returned fields, which cleanly distinguishes it from cooper_list_drafts and cooper_get_message. An agent can select it without opening the schema.

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

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

Explicitly says when to reach for it ('when you need one draft'), establishing the single-item vs list context. It does not name cooper_list_drafts as the alternative, so the routing 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: authentication is required, and querying another account's inbox yields HTTP 404 inbox_not_found. It omits rate-limit or pagination behavior, but for a single-resource lookup that is minor.

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 and kept to a few dense sentences. The enumeration of return fields is long but earns its place because there is no output schema; overall efficient with little waste.

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

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

With no output schema, the description compensates by listing the returned inbox object's fields (including the direct/approval values of send_mode) and documents the auth requirement and 404 failure mode. Nothing needed 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 single parameter is already documented as accepting 'Inbox id (inb_…), username, or full email address owned by this key.' The description's restatement of the same accepted formats adds no meaning beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb (get) and resource (one inbox) and enumerates the fields it retrieves, which clearly separates it from sibling cooper_list_inboxes and cooper_update_inbox. An agent can tell immediately that this fetches a single existing inbox by identifier.

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 states the condition: 'Use this when you need one inbox's ... and you already have its id, username, or email.' This gives clear selection context, though it never names cooper_list_inboxes as the alternative when the identifier is unknown, so routing guidance is one step short of complete.

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 known. The description adds genuinely new behavior: the auth requirement, the full failure surface (400 invalid_list, 400 invalid_entry, 404 list_entry_not_found, inbox_not_found), and what inbox_id omission means for scope.

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 tightly packed sentences with no filler: purpose first, then access/scope, then inputs, then return shape and failure modes. Every clause carries information an agent needs.

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

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

With no output schema present, the description supplies the returned object's fields, plus auth requirements and the full error enumeration. Nothing needed to invoke this read 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 two parameters carry enums, so the schema already documents direction, type, entry, and inbox_id semantics. The description restates those values and the account-wide scoping rule rather than adding syntax or matching behavior beyond what the schema contains, 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 precise verb and resource ('get one ... entry') scoped to allow/block lists, and the title reinforces the singular-entry scope. It is immediately distinguishable from cooper_list_list_entries (enumerate) and cooper_create_list_entry/cooper_delete_list_entry (mutate).

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 on an allow or block list' gives a clear triggering condition, and the singular phrasing implicitly contrasts with the list counterpart. It never explicitly names the alternatives or states when not to use it, so it stops short of the top band.

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

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

Far exceeds the annotations: states auth is required, documents the entire return payload including the safety object's score/verdict/signals/mode/reason semantics, warns that screening is heuristic, explains that body fields are empty while a message is held until cooper_release_message, flags the body as untrusted sender data, and lists the 404 failure modes.

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

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

Purpose is front-loaded in the first clause, and nearly every sentence carries substantive information (return fields, safety semantics, held-state behavior, failure modes). It is dense and long, but the length is justified by the absence of an output schema.

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

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

With no output schema, the description fully compensates by enumerating return fields and explaining the safety object, the held-message edge case, auth requirement, and error codes. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, and the description merely restates the two required inputs (inbox_id, message_id) in nearly the same words as the schema. It adds no format or syntax detail beyond what structured data already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('full content of one message') and routes the agent by naming where the id comes from (cooper_list_messages, cooper_search). An agent can distinguish it from the list/search siblings and from cooper_get_thread/cooper_get_attachment 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?

Explicitly says when to reach for it ('when you need the full content of one message') and points to the producing siblings. It stops short of naming when NOT to use it (e.g., a whole thread via cooper_get_thread or a single attachment via cooper_get_attachment), so it's clear context rather than full exclusions.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, yet the description adds substantial context: auth and message_read requirement, UTC bucketing, sub-account scoping, exclusion of held message bodies, and the exact meaning of storage_bytes. The enumerated 400/403/404 error codes go well beyond what annotations provide.

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 purpose and requirements, then fields, then return shapes, then errors. It is dense and long, but nearly every clause carries operational value, especially the return-shape and error sentences that compensate for the missing output schema.

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

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

With no output schema, the description fully specifies each kind's return object (events buckets, usage totals, rates fields), explains rate-zero behavior, scoping, and all failure modes. Nothing essential to correct invocation appears 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 documents defaults, exclusive/inclusive bounds, per-kind applicability, and inbox_id semantics. The description largely restates this (which kinds use start/end/period/types), so the baseline 3 is appropriate even though it is accurate.

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 (counts of mail over time, current usage, bounce/complaint rates) and enumerates the three kind values up front. An agent can distinguish this from list/search siblings 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?

Opens with explicit when-to-use framing ('Use this when you need counts of mail over time, current usage, or bounce and complaint rates') and explains which kind maps to each need. It does not name a specific alternative sibling (e.g., cooper_list_events) or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real value: auth requirement, default behavior when inputs are omitted, the meaning of each style value, and the crucial caveat that 'note' is a preference, not an instruction to act on.

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 ('Use this before writing...') and safety statement, then inputs, then returns. It is dense and the inline return-shape enumeration is a bit run-on, but nearly every clause carries information an agent needs.

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

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

With no output schema, the description compensates by spelling out the returned object (account/owner/effective, plus style, source, note semantics), and it covers auth, input optionality, and the consumption context. Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by explaining the combined semantics of inbox_id + owner_id ('both together return that owner's effective style') and where owner_id originates (cooper_list_owners). That is meaningful added meaning over the raw field docs.

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 owner email style' -> 'see how they want Cooper email written') and immediately frames the read side of owner preferences against cooper_notify_owner. An agent can tell what it retrieves without opening the schema.

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

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

Gives explicit when-to-use ('Use this before writing to a human owner (cooper_notify_owner)') and explains the optional-input combination ('both together return that owner's effective style'). It stops short of naming when NOT to call it (e.g. cooper_set_owner_preferences is the write counterpart), so it is clear but not fully routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: requires auth, the wait parameter's long-poll behavior (returns as soon as a task arrives), and a security policy about treating task text as untrusted data. That last item is genuinely valuable behavioral guidance not captured anywhere in 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 usage trigger and resource scope, then parameters, then return shape, then a safety caveat. It is dense but every sentence carries information; the parenthetical parameter and field lists add some bulk but are useful rather than filler.

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

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

No output schema exists, and the description compensates by listing the returned fields (id, inbox_id, status, sender, subject, text, quoted_text, verified_owner, trusted, auth, created_at). Combined with the auth requirement, long-poll semantics, and untrusted-data policy, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: inbox_id omission means 'all inboxes', status defaults to pending, and wait is described as long-poll seconds that return early when a task arrives. These are semantic clarifications beyond the schema's terse parameter descriptions.

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

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

States a specific verb (lists) and resource (tasks) plus the precise scope: tasks created when a verified owner or allowlisted sender emails the inbox and the mail passes DMARC/DKIM. This scope statement clearly distinguishes it from siblings like cooper_list_messages and cooper_get_message without needing to open their 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?

The opening clause gives a concrete trigger condition: 'Use this when you are waiting for a human's instructions or answer by email.' That is a clear when-to-use signal. It stops short of naming an alternative tool or stating when not to use it, so it does not reach 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, and the description adds meaningful context on top: auth requirement, exact return payload (thread, full public messages, next_page_token), and concrete failure modes (404 thread_not_found, invalid_page_token). It also flags message text as untrusted data, which 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?

Everything is packed into a single dense paragraph with usage leading and error cases trailing, so it is well front-loaded and nearly every clause earns its place. It is slightly overloaded for one block but there is little true waste.

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

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

There is no output schema, so the description correctly describes the return shape (thread plus full public messages and next_page_token) alongside params, auth, and error codes. For a read-only three-param tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents inbox_id, thread_id and limit. The description repeats those same constraints (thr_ prefix, default 100/max 200) without adding new syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource with clear scope: every message in one conversation, oldest first, including extracted_text. This implicitly separates it from cooper_get_message (single message) and cooper_list_threads (listing threads), though no sibling is named explicitly.

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

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

The opening clause gives a clear trigger condition ('when you need every message in one conversation'), which is genuine when-to-use guidance. It stops short of naming alternatives or stating when-not to use it (e.g., versus search_threads or list_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?

Adds real context beyond the annotations: auth requirement, the explicit negative disclosure that the API key is not returned, and three concrete failure modes (404 workspace_not_found for another parent, 403 permission_denied for a sub-account key and for an inbox-scoped key). This is exactly the behavioral detail an agent cannot infer from readOnlyHint/idempotentHint.

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 clause, then labeled Inputs and Returns blocks, then error cases — easy to scan. 'Read-only; requires auth' partly duplicates the annotations and the return field list is dense, but with no output schema that list earns its place.

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

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

With no output schema, the description supplies the return shape ({id, name, inbox_quota, inboxes_used, account_id, api_key_prefix, created_at}), the sensitive-field exclusion, and the error taxonomy. 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 description coverage is 100% and the single workspace_id parameter is already documented in the schema, so the description only repeats 'workspace_id (required)'. Baseline 3 is appropriate — the heavy lifting is done by the schema.

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

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

States a specific verb+resource ('get one sub-account') and pins the scope to workspaces created by the signed-in parent, which separates it from cooper_list_workspaces and from another parent's data. It also names the payload (inbox quota, inboxes in use), so an agent knows exactly what this returns.

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 sub-account created by the signed-in parent' gives a clear triggering condition and the 404/403 cases tell the agent when a call will fail. It stops short of naming the alternative (cooper_list_workspaces) for enumerating multiple workspaces, so it isn't a full when/when-not routing guide.

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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond: requires auth, stores the message as received mail, fires message.received webhooks, carries no DMARC/DKIM results, and only creates an owner task when require_sender_auth=false — precisely the side-effect caveats an agent 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?

Front-loaded with purpose and the test-only constraint, then behavior, inputs, and return value. It is one dense paragraph but nearly every clause carries information; only the input enumeration lightly duplicates the schema.

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

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

For a 7-parameter mutation tool with no output schema, the description covers auth, side effects, webhook firing, the sender-auth caveat, the parameter list, and even the return value ('Returns the stored message'). Nothing needed 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 coverage is 100%, so the schema already documents all 7 parameters including client_id as an idempotency key and attachments as base64. The description mostly restates these ('from (required; sender address)', 'client_id (optional idempotency key)'), adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: simulate inbound email arriving in a Cooper inbox without sending real mail. It distinguishes itself from the normal path by noting 'real inbound mail arrives automatically,' so an agent can tell it apart from send/reply 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?

Explicit when-to-use ('only for testing... to try a webhook or task flow end to end') and when-not ('never use this to fake mail for a user'), with the real-inbound alternative named. Nothing is left to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely useful behavior: auth requirement, plan limits (Starter 15, Pro 200, Free 0 with HTTP 402 plan_limit_exceeded), status enumeration, and DNS auto vs manual mode. The value is undercut by a large block describing DELETE /api/v1/domains/:id cleanup semantics, which belongs to a different operation and can mislead about this tool's scope.

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, but the body is a run-on paragraph mixing return-shape spec, plan quotas, MX/SPF/DKIM/DMARC publishing instructions, receiving-latency notes, inbox creation, and full delete/cleanup semantics. Much of this does not earn its place in a read-only list tool's description.

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

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

With no output schema, the description does the necessary work of describing the returned object and its status/hint/warnings fields, and annotations carry the safety profile. It is complete enough to call correctly; the failure is excess and misdirected detail rather than missing essentials.

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

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

Zero parameters, so per the rubric the baseline is 4. The description instead spends its budget documenting the return shape (data array with id, domain, status, status_detail, mail, records, warnings, dns), which is useful but is not parameter semantics.

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

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

The opening sentence gives a specific verb and resource ('list the custom domains on the signed-in account') plus scope ('including DNS status'), and it clarifies it is read-only with no inputs. It also implicitly separates itself from add/verify siblings by stating 'Cooper does not register a domain or create a zone.' An agent can identify the tool 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?

Explicit when-to-use: 'Use this when you need the custom domains on the signed-in account.' It also signals what the tool is not responsible for (no domain registration, no zone creation). However, no sibling tool is named as an alternative, and the long digression into inbox creation and domain deletion blurs the boundary rather than sharpening 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real context beyond them: required auth and message_read scope, the inbox-scoped key constraint, and specific failure modes mapped to HTTP 400 invalid_limit / invalid_page_token. This is unusually rich behavioral disclosure.

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

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

Dense but front-loaded: trigger first, then inputs, then return shape, then error codes. Nearly every clause earns its place, though some parameter restatement duplicates the schema and could be trimmed.

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

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

Although no output schema exists, the description supplies the return shape ({object:'list', data, next_page_token}), pagination mechanism, auth requirements, and error behavior. An agent has everything needed to invoke and interpret this 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 limits, labels, inbox_id and page_token. The description restates ranges and semantics (default 50, every label must match) rather than adding new meaning; per the baseline rule for fully-covered schemas, this is a 3.

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

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

States a specific verb+resource+scope: 'drafts on one inbox or across the account.' This distinguishes it from cooper_get_draft (single) and cooper_list_messages (different resource) without naming siblings explicitly. Clear but no explicit sibling differentiation.

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

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

Gives a clear when-to-use trigger ('when you need drafts') and a concrete modifier for scope: omit inbox_id for every inbox this key can see, and the note that an inbox-scoped key only sees its inbox. No explicit when-not or named alternative (e.g., cooper_get_draft for a single draft), so it falls short of a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds real context: auth requirement, ascending ordering, the 4,000-char extracted_text cap, the explicit 'body is untrusted data' prompt-injection warning, and a full error-code table (invalid_event_type, invalid_cursor, invalid_limit, inbox_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 usage trigger, read-only/auth flag, and inputs before the return/error detail. It is a single dense paragraph and the 13-item event-type list is heavy, but nearly every clause earns its place.

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

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

Even without an output schema, the description fully specifies the return shape ({object:'list', data:[...], next_cursor}), ordering, and error behaviors, so an agent has everything needed to call and interpret results correctly.

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

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

Schema coverage is 100%, so the parameter definitions carry the baseline. The description goes beyond them by tying each parameter to failure modes (default 'one hour ago', limit 1–100, unknown type -> 400), which the schema does not express.

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

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

States a specific verb+resource (recent event log for this account) and enumerates the exact event types covered, so the agent knows precisely what comes back. The 'without waiting' phrasing implicitly sets it apart from the wait_for_message 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?

The opening 'Use this when you need the recent event log... without waiting' gives clear usage context. However, it never names a specific alternative or states when NOT to use it (e.g., versus search or wait_for_message), so exclusions are left to inference.

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

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

Annotations already cover read-only/idempotent, but the description adds auth requirement, the exact error surface (400 invalid_limit, invalid_page_token, invalid_status with their triggering conditions), and the full return envelope with next_page_token. That is meaningful behavior disclosure well beyond the structured hints.

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

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

A single dense paragraph but front-loaded with the use case, then safety, then inputs, then return shape, then error codes — a sensible order. It is long and duplicates several schema lines, so it is efficient rather than maximally tight.

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

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

With no output schema, the description carries return-value disclosure itself, and it does: field list inside data plus next_page_token, plus pagination and error semantics. Nothing an agent needs to call and page through this tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3: the description largely restates schema text (status active/paused, limit default 100 max 500, page_token cursor, q substring/prefix ordering). It adds only the framing that omitting status lists every inbox, matching what the schema already says.

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

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

States a specific verb+resource (list inboxes) scoped to the signed-in account, and goes further by naming the concrete downstream reason to call it (picking an inbox_id before send/read). An agent can distinguish this from get_inbox and 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 triggering contexts ('when you need to know which inboxes exist... to pick an inbox_id before sending or reading mail, or to tell the user their address'), which is strong positive guidance. It does not explicitly name the alternative (cooper_get_inbox) or the condition that would select it over listing, so it stops short of full when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description goes well beyond them: auth requirement, the 1000-entry cap, the null semantics of inbox_id on account-wide entries, and two concrete failure modes (400 invalid_list, inbox_not_found for another account's inbox). That is exactly the extra behavioral 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?

It is front-loaded with usage, then behavior, then inputs, then the return shape, then error cases — a logical order with no filler. It is dense, and the 'Inputs:' clause duplicates information already in the schema, which is the only thing keeping it from a 5.

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

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

There is no output schema, so the description must carry the return contract, and it does: the full data array shape, the next_page_token for pagination, and the entry_type/inbox_id null semantics. Combined with the documented error codes, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the enum meanings for direction and type. The description largely restates those same meanings in prose and adds no syntax or format detail the schema lacks, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'the addresses on an allow or block list.' It is immediately distinguishable from siblings like cooper_create_list_entry, cooper_get_list_entry, and cooper_delete_list_entry, which operate on single entries rather than listing the full list.

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

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

It states the triggering condition ('when you need the addresses on an allow or block list') and clarifies that the per-inbox task allowlist is a separate, unaffected concept. It does not, however, explicitly route the agent to cooper_get_list_entry for a single entry versus this bulk list call, so the alternative-selection guidance is contextual rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is largely covered. The description still adds real behavioral detail: server-side filtering before limit, the 0-55 second wait window with a five-concurrent-wait cap, the inbox_wait/timed_out return shape, page_token being a base64url composite, and an enumerated error set. That is useful, but much of it restates annotation-covered ground, keeping this at a solid 3 rather than higher.

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 error codes. Dense and almost entirely load-bearing, though the parameter enumeration in prose duplicates the schema and makes the block longer than a reader needs.

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

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

There is no output schema, so the description carries the return contract itself and does so fully: field list, ordering, pagination token semantics, and the special inbox_wait shape under wait_seconds. Error codes are enumerated. Nothing needed to invoke 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 schema already documents every parameter and the baseline is 3. The description goes modestly beyond it by clarifying that wait_seconds yields an object inbox_wait with timed_out, that page_token encodes created_at and id, and that before/after are exclusive. These are genuine additions absent from the 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?

States a specific verb+resource ('check an inbox for new or recent mail (sent and received)') and immediately contrasts with the sibling that reads message bodies ('Previews only, not full bodies: call cooper_get_message'). An agent can distinguish this from cooper_search_messages or cooper_get_thread 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?

Explicitly names the triggering scenario ('after sending a message and waiting for a reply') and routes to two alternatives with their conditions: cooper_get_message for full bodies and cooper_update_message to mark one read. It also flags required auth, which is a precondition rather than just context.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: no inputs, inclusion of expired access tokens while a refresh token remains usable, empty client_name when the client row is gone, hostnames-only redirect_hosts, explicit exclusion of token/refresh hashes and client secrets, sort order, and the exact 403 permission_denied and unauthorized failure modes. It is also consistent with the readOnly annotation.

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

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

Front-loads the trigger and scope, then compresses the return shape and failure modes into tight sentences with no filler. Given that no output schema exists, the return-shape sentence earns its length.

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

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

For a read-only list tool with no output schema and no parameters, the description covers purpose, usage trigger, full return shape, edge-case semantics, ordering, and both 403 failure modes — everything an agent needs to call it and interpret the result.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the description explicitly states 'No inputs,' which is the correct baseline for a 0-parameter tool.

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

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

States a specific verb and resource ('see which OAuth apps currently hold access to this account') and names the actual object type (oauth_grant) returned. It is easily distinguished from siblings such as cooper_list_workspaces or cooper_list_owners, and it ties itself to cooper_revoke_oauth_grant by noting the revoke use case.

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 trigger ('when you need to see which OAuth apps currently hold access') and a motivating scenario ('for example before revoking one'), which implicitly points to cooper_revoke_oauth_grant. It does not explicitly say when not to use it or name the alternative tool by name, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description still adds value with 'requires auth' and the negative guarantee 'Never returns confirmation codes', which no structured field conveys.

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

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

Dense and front-loaded, with trigger, auth note, inputs, and return shape in order. The return-field enumeration is somewhat long, but it earns its place because no output schema 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?

With no output schema, the description compensates by spelling out the returned object shape including the status enum, and it covers auth requirements and a negative guarantee. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already documents inbox_id fully (id prefixes, username, email). The description adds only 'inbox_id (required)', which is redundant. Baseline 3 for full schema coverage.

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

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

States a specific verb and resource ('check who the human owners of an inbox are and whether they have confirmed') and explicitly distinguishes itself from the sibling cooper_notify_owner, so an agent can route correctly without opening schemas.

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

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

Gives an explicit trigger ('when you need to check... before relying on cooper_notify_owner'), naming both the condition and the alternative tool. Nothing is left to inference.

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

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

Annotations already carry readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further with real operational detail: auth is required, inbox-scoped keys receive 403 permission_denied, and unauthorized failures are explicitly named. That is meaningful disclosure beyond the structured fields.

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

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

Front-loaded with the usage trigger, then auth, then return shape and error modes in a tight sequence with no filler. Dense but each sentence carries distinct information; the inline return-shape block is a little compact to parse but not wasteful.

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

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

With no output schema present, the description supplies the return envelope and field list, enumerates the reason values (bounce/complaint/manual), explains source_message_id including its null case, and covers auth failure modes. An agent has everything needed to call and interpret this correctly.

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

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

This tool takes zero parameters, which sets the baseline at 4, and the description confirms it with 'Inputs: none.' There is no parameter surface to elaborate on, so nothing more is expected or missing.

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 resource — the addresses the account will not email — and defines exactly what populates that list (permanent bounce, complaint, manual add). The read/list intent is unambiguous from the title and the 'addresses you need' framing, though it never explicitly routes against the sibling cooper_delete_suppression, so it stops short of a 5.

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

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

Opens with an explicit 'Use this when you need...' trigger tied to a concrete situation (reviewing addresses that won't be emailed). It adds auth-scope exclusions (inbox-scoped keys rejected) but names no alternative tool for adjacent needs, so it is clear context without the full when/when-not/alternatives treatment.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: auth requirement, default/max limit, ordering (updated_at descending), and two concrete error behaviors (HTTP 400 invalid_page_token, inbox_not_found). This is exactly the extra context an agent 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?

Front-loaded with the decision rule, then inputs, then return shape and errors in a logical order. The run-on enumeration of thread fields is dense but earns its place since there is no output schema; it could be trimmed slightly.

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

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

With no output schema, the description fully compensates by spelling out the return envelope (object/data/next_page_token), per-thread fields, ordering, and error cases. Nothing an agent needs to call and consume this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the inbox_id omission semantics and the page_token failure mode. The description largely restates these, adding only minor framing ('cursor from a previous page'), 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 resource (threads) with a clear scoping rule — 'whole conversations instead of individual messages' — which cleanly separates it from cooper_list_messages and cooper_search_messages in the sibling set. The enumerated thread fields confirm exactly what a 'thread' means here.

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 when-to-use with a concrete example ('see who is in a thread and when the last reply arrived') and contrasts it with message-level retrieval. It does not name the alternative tool by name (e.g. cooper_list_messages / cooper_search_threads), so the routing is implied rather than explicit.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial extra context: auth required, no inputs, secret and headers are redacted, previous_secret_active is true only for 24h post-rotation, previous secret is never returned, and specific failure codes (401/403).

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, then the return shape, then edge-case semantics and error codes. Sentences are dense but each earns its place. The inline return object is long, though justifiable given there is no output schema.

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

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

With no output schema and no input params, the description fully compensates by documenting the returned object fields, redaction behavior, rotation semantics, scoping behavior, and failure modes. Nothing an agent needs to invoke or interpret the result 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?

Zero parameters, so the schema carries nothing to clarify and the baseline is 4. The description correctly notes 'No inputs,' which is all that can be said here.

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

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

States a specific verb+resource ('list the webhooks on this account') plus the scope (account-level, inbox-scoped keys behave differently). It is clearly distinguishable from siblings like register_webhook, update_webhook, delete_webhook, and rotate_webhook_secret.

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 the webhooks on this account' gives clear context, and the inbox-scoped-key note tells the agent when results differ. However, it names no alternative or exclusion (e.g., point to register/update/rotate for mutations), so it stops short of the 5-level explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value beyond them: the auth requirement and the explicit caveat that API keys are NOT returned even though api_key_prefix appears in the payload. No rate-limit or pagination behavior is disclosed, which keeps it at a 4.

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 tight sentences: trigger, then safety/input constraints, then the exact return shape, then the one non-obvious exclusion. Nothing is repeated and the most decision-relevant information is front-loaded.

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

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

There is no output schema, so the description carries the return-shape burden and does so inline with the full field list and the API-key exclusion. For a zero-parameter, read-only list tool this is exactly the information an agent needs.

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

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

Zero parameters, so the baseline is 4. The description's 'no inputs' statement correctly confirms the empty schema and prevents an agent from inventing filter arguments.

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

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

States a specific verb (list) and resource (sub-accounts/workspaces) and pins down the scope as 'sub-accounts created by the signed-in parent'. That scoping phrase distinguishes it from sibling list tools like cooper_list_owners and cooper_list_inboxes without needing to inspect their 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?

Opens with an explicit when-to-use trigger ('Use this when you need the sub-accounts created by the signed-in parent'). It gives clear context but names no alternatives or exclusions, so an agent must infer that this is the right call over other list_* 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 annotations it discloses auth requirements ('Requires auth'), fan-out behavior ('every verified owner of the inbox', with daily-digest owners deferred to the next digest), the no-op failure mode when no owner is verified, and the prohibition on internal ids (dpl_, commit shas, inbox ids). That is substantial behavioral context the annotations do not carry.

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

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

It is front-loaded with the usage condition and every sentence carries information (constraints, fallbacks, return shape), with no filler. It is a single dense paragraph mixing usage, behavior, params, and return values, which slightly hurts scannability, so not a 5.

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

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

There is no output schema, yet the description spells out the return object ({id, kind, task_id, text, created_at, deliveries:[...]}) including per-delivery status values. Combined with full parameter coverage and the auth/fan-out notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the title format (5-8 plain words with examples), the fallback when title is omitted ('Cooper uses the first sentence of text, cut at a clause, never with an ellipsis'), and task_id's role in threading updates into one email. These are behaviors the schema descriptions alone do not state.

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

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

The description names a specific verb and resource ('tell its human owner(s)... by email') and enumerates the trigger cases (progress, completion, blocker, question). This distinguishes it from the messaging siblings like cooper_send_message or cooper_reply_message without the agent needing to open 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?

It gives clear when-to-use context ('Use this when the agent should tell its human owner(s) about progress, completion, a blocker, or a question') and routes the failure case explicitly ('If no owner is verified yet, nothing is sent: check cooper_list_owners'). It stops short of explicitly excluding the general-purpose send tools, so a 4 rather than 5.

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

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

With annotations limited to readOnly/destructive/idempotent/openWorld flags, the description carries substantial extra context: no auth required, the api_key is returned only once and must be reused as the Bearer token for every other Cooper tool, failure codes (409 inbox_exists), and precise rate-limit behavior (30 req/min per IP, HTTP 429 rate_limited, 503 username_check_unavailable, 503 rate_limit_unavailable). This is well beyond what the annotations disclose.

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-loading is good — the trigger condition leads — but the body is a dense block that repeats the rate-limit and error-code text already present in the check_username schema description, and the raw '{account_id, api_key, ...}' return dump is unstructured. Much of it earns its place given there is no output schema, but the duplication costs it.

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

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

There is no output schema, so the description must document returns, and it does: the full create response shape, next_steps/recommended semantics, the conditional owner object, and the check_username response shape. For a tool with two modes, auth nuances, and rate limits, 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 coverage is 100% so the baseline is 3, but the description adds value the schema lacks — the username character rules (1–32 chars: letters, digits, . _ -) and the fact that check_username suppresses account creation entirely. It reinforces owner_email's 'recommended, not required' framing rather than just restating it.

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 multi-part resource: 'Creates a Cooper account, one inbox <username>@cooperemail.com, and an API key.' It also distinguishes itself from the closest sibling by name — 'If already signed in, this adds the inbox to the current account ... (prefer cooper_create_inbox)' — so an agent can route between the two 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?

Opens with an explicit trigger condition ('when the user wants the agent to have its own email address and this connection is not signed in yet (no OAuth token or API key)') and names the alternative to use when that condition fails. It also defines the alternate check-only mode via check_username, so both use cases are covered.

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=false, openWorldHint=true): it discloses auth requirements, URL validation rules (localhost/private rejected), cross-field scoping constraints, opt-in idempotency via client_id with HTTP 200 + redacted secret, header encryption/redaction, HMAC signature headers on delivery, and three specific error codes. This is exactly the behavioral depth a mutation 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?

Front-loads the decision ('use this when...instead of polling') before the detailed input/output/error inventory. It is a single dense block rather than scannable sections, and a few clauses restate schema-level facts, but no sentence is wasted.

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

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

With no output schema and no structured annotations covering behavior, the description still describes the return shape ({id, url, events, enabled, secret, ...}), the signature headers, and failure modes. An agent has everything needed to call this correctly.

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

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

Although schema coverage is 100%, the description adds cross-parameter semantics the schema does not spell out: inbox_id vs inbox_ids are mutually exclusive, inbox_ids is capped at 10, omitting both targets every inbox, and client_id acts as an idempotency key returning the original hook with a redacted secret. It also documents header naming rules and default event behavior.

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 (register a webhook) and immediately frames the purpose as push notification via HTTP POST when mail arrives. It explicitly distinguishes itself from the polling sibling cooper_list_messages, so an agent can route between the two 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 a clear when-to-use condition (notify immediately instead of polling) and names the polling alternative cooper_list_messages. It does not differentiate from cooper_update_webhook or cooper_test_webhook, nor state explicit exclusions, so it falls just short of full when/when-not coverage.

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

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

Goes well beyond the annotations: it discloses the label removal, the message.received webhook firing, task creation gated on verified-owner/allowlist sender-auth, that the suspicious label persists, that a repeat call returns 409 message_not_held without re-firing side effects, and the exact 404 cases. The auth requirement and the heuristic-not-guarantee caveat are also called out, which 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?

It is fairly long for a two-parameter tool, but the trigger condition is front-loaded and the remaining sentences convey genuinely distinct facts (side effects, error codes, safety caveats) rather than padding. A slightly tighter grouping of the error cases would improve it, but nothing is wasted.

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

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

With no output schema, the description fills the gap by describing the return payload (message with labels and safety), all relevant error outcomes (409 message_not_held, 404 inbox_not_found, 404 message_not_found), the side effects, and the trust caveat on the body. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema. The description restates inbox_id as 'inbox id, username, or email' and message_id as required, adding no syntax or constraint beyond the structured field descriptions; 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 (release), resource (a message held by inbound screening), and the precise condition that triggers it (screening held the message and a person decided it should be delivered). An agent can distinguish this from generic siblings like update_message or inject_inbound 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?

The opening sentence gives explicit when-to-use context tied to the 'held' label and a human decision, which is the correct selection signal. It does not name an alternative tool or state a when-not condition, but there is no obvious competing sibling for releasing a held message, so the context is sufficient without exclusions.

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

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

Goes well beyond the annotations: discloses that auth is required, that it sends real email, where the copy is stored, threading/subject mutation ('gains Re: unless it already starts with re:'), recipient resolution (Reply-To/From vs original To), the 402 monthly send limit, and a full enumeration of failure codes. The client_id note clarifies conditional idempotency even though idempotentHint is false, which is useful nuance rather than a contradiction.

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 when-to-use clause and then packs inputs, threading rules, return, and errors into one dense paragraph with no filler sentences. It is longer than ideal and the trailing error-code list reads as a run-on, but nearly every clause carries operational information.

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

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

With no output schema, the description still covers the return value ('Returns the stored message'), auth, side effects, recipient resolution, subject behavior, rate limiting, and error outcomes. For a 10-parameter mutation tool, nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: reply_all's exact semantics (include other To/Cc, merge cc, drop this inbox, dedupe), subject-line rewriting, and the constraint that text and/or html is required — a constraint the schema itself does not enforce via oneOf. Fails to explain attachments/labels beyond what the schema already says.

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 ('answer a message already in a Cooper inbox') and adds the distinguishing trait that recipients and threading are auto-filled, which separates it from cooper_send_message and cooper_create_draft. An agent can tell what this does 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?

'Use this when you need to answer a message already in a Cooper inbox' gives clear selection context for replying rather than composing fresh mail. It stops short of explicitly naming the alternatives (send_message, create_draft, forward_message) or stating when not to use it, so it is clear but not fully 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?

Adds substantial behavior beyond the annotations: requires auth, sends a real email to the sender, describes the default non-idempotent behavior ('calling twice sends two emails'), the 24-hour idempotency replay semantics with 'idempotent true', the return shape, and a full list of failure codes. This is rich, actionable context 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?

Front-loaded with the when-to-use clause, then grouped logically into auth, side effects, inputs, return, and errors. Dense but every sentence carries information; slightly long as a single paragraph but not wasteful.

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, open-world mutation tool with no output schema, the description fully accounts for auth, side effects, idempotency, return value, and error handling. 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%, so the baseline is 3. The description goes further, explaining what status means operationally ('set done when the task is finished') and restating idempotency_key's constraints and 24-hour behavior, adding usage meaning over the raw 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 (reply) and resource (an owner task) scoped to the same email thread, and names the sibling source 'cooper_get_tasks'. Distinguishes itself from the more generic cooper_reply_message/cooper_send_message by targeting owner tasks.

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 tells the agent when to use it ('when you have an answer or result for a task from cooper_get_tasks') and gives status guidance ('set done when the task is finished'). It does not, however, name alternative tools or state when NOT to use it, so a full 5 is not warranted.

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 substantial detail beyond them: tokens and unused authorization codes are deleted in one transaction, the registration remains, and the return payload includes tokens_revoked. It also discloses downstream effects (401s, refresh failures at /oauth/token) and that other apps/keys are unaffected.

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 inputs, behavior, return shape, and error cases in a logical order. It is dense and slightly long, and 'Destructive' duplicates the annotation, but nearly every sentence carries actionable information.

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

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

With no output schema, the description fully carries the burden: it specifies the response object fields (oauth_grant, id, revoked, tokens_revoked) and the failure modes (404 oauth_grant_not_found, 403 permission_denied for inbox-scoped or key_write-less keys). Nothing needed 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 single client_id parameter is fully documented in the schema, including its source and that it is the grant id. The description repeats that source hint, adding little beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb+resource ('an OAuth app should lose access to this account') and the title 'Revoke a connected app' confirms it. It clearly distinguishes itself from the sibling cooper_list_oauth_grants, which is cited only as the source of the client_id.

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

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

Gives an explicit trigger ('when an OAuth app should lose access to this account') and names the sibling used to obtain the required client_id. It also clarifies the boundary of the action by noting the client registration survives, so an agent knows this is scoped to tokens/codes, not app deletion.

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

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

The description adds rich behavioral context beyond the annotations: it explains the 24-hour dual-secret window, the exact signature header formats, how receivers should verify them, that the previous secret value is never returned, and the concrete error codes for missing webhook and permission failures. This is exceptionally complete 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?

The description is front-loaded with the trigger condition, then proceeds logically through inputs, secret behavior, return shape, signature verification, permission requirements, and failure modes. Every clause carries actionable information for correct invocation or handling, so the length is justified.

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 mutation tool with no output schema, the description supplies everything an agent needs: when to use it, what it returns, how the grace period works, how to interpret the signature headers, required permissions, and possible errors. No critical gap remains.

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 webhook_id fully. The description only repeats that webhook_id is required and adds no format, source, or constraint details beyond the schema, making this the expected baseline score.

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—minting a new webhook signing secret while keeping the old one valid—and distinguishes this from merely updating a webhook. An agent can identify the exact operation 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?

It clearly says when to use the tool: when a webhook secret should change without breaking receivers that still check the old secret. It also notes the required permission and that rotating again resets the grace window. However, it does not name explicit alternatives or when-not-to-use conditions, so it falls short of the top score.

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

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

The annotations already declare readOnlyHint, idempotentHint, and no destruction, so the safety profile is covered. The description goes well beyond that by stating auth requirements, exact error behaviors (400 missing_query, 400 invalid_date, 404 inbox_not_found), the response envelope shape, sort order, highlight formatting, and that message text is untrusted data. This is rich behavioral context that materially helps an agent invoke and interpret the 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?

The description is front-loaded with the use case and then systematically covers inputs, outputs, and errors. It is dense but well structured, and every part earns its place. The only minor inefficiency is that the parameter enumeration largely duplicates what is already 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?

Given the lack of an output schema, the description fully compensates by describing the return object shape, ordering, and highlight behavior. It also covers auth, error cases, and data trust concerns, leaving nothing essential for correct invocation or interpretation missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description restates the same parameter semantics (q matching rules, limit default/max, ISO-8601 exclusive bounds, inbox_id accepted forms) without adding new meaning. Baseline 3 is appropriate when 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 description states a specific verb and resource: find mail by keyword, sender, recipient, or subject, across the account or one inbox. It distinguishes itself from cooper_get_message by noting that tool is for full bodies. However, it does not differentiate itself from the near-identical sibling tools cooper_search_messages and cooper_search_threads, leaving some ambiguity about which search tool to choose.

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

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

The description gives clear context for when to use the tool ('when you need to find mail...') and names one alternative for full message bodies. It does not explain when to prefer this tool over cooper_search_messages or cooper_search_threads, which is a notable gap given how similar the sibling names are. Usage is implied but not fully disambiguated.

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

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

Annotations already declare the safe-read profile, and the description adds substantially on top: auth requirement, the untrusted-data warning about message text, result ordering ('newest first'), the highlight encoding (** with ~80 chars of context), and three concrete failure modes (400 missing_query, 400 invalid_date, 404 inbox_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 when-to-use clause, then read-only/auth, inputs, return shape, and errors in a tight sequence with no filler. Some parameter text duplicates the schema verbatim, which is the only 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?

There is no output schema, and the description compensates by spelling out the return object shape (including extracted_text and highlights), ordering, and error surface. An agent has everything needed to invoke and interpret this 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 every parameter is already documented. The description largely restates those semantics (q matching rules, limit default/max, exclusive ISO-8601 bounds) and mainly adds value by tying before/after and q to their error codes, so the baseline of 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 ('find mail inside one inbox') plus the searchable facets (keyword, sender, recipient, subject). The 'inside one inbox' scoping cleanly separates it from the account-wide cooper_search and from cooper_search_threads.

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 ('Use this when you need to find mail inside one inbox ... and you want the matching words highlighted'), which tells the agent the exact situation this tool fits. It stops short of naming alternatives such as cooper_search or cooper_search_threads for cross-inbox or thread-level search, so the exclusions are 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 already declare readOnlyHint/idempotentHint/destructiveHint=false, so those claims in the description are redundant. Beyond that, the description adds real value: auth requirement, ordering by 'best matching message', and concrete failure semantics (empty q -> HTTP 400 missing_query, unknown inbox -> inbox_not_found), which 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?

Well structured with a when-to-use lead followed by Inputs/Returns/Errors blocks, and no wasted sentences. Minor redundancy in restating 'Read-only' and the parameter docs that already exist 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?

With no output schema, the description carries the return contract itself ({object:'list', inbox_id, q, data:[thread]}), the ordering rule, parameter defaults, and two named error outcomes. That is everything an agent needs to call and interpret this tool.

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

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

Schema description coverage is 100%, so q, limit, and inbox_id semantics are already documented in the schema; the description largely restates them (inbox id/username/email, every word matches, default 20 max 50). It adds only the error conditions attached to bad inputs, 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 (search) and resource (threads), and immediately contrasts the granularity with the sibling concept of per-message results: 'the conversations that contain a keyword, sender, recipient, or subject, instead of each matching message.' An agent can distinguish this from cooper_search_messages without opening either schema.

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

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

Gives an explicit selection condition ('when you need the conversations ... instead of each matching message'), which functions as both when-to-use and when-not-to-use. The gap is that the alternative tool is described only functionally and never named, so the agent must infer that cooper_search_messages is the counterpart.

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 specifying the concrete consequence ('Sending deletes the draft and returns the message'), approval-mode behavior (HTTP 202 pending owner approval), conflict handling (409 draft_sending), paused-inbox behavior (403 inbox_paused), and that allow/block/suppression lists are checked. This is exactly the kind of operational detail the destructiveHint annotation cannot convey.

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

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

Front-loads the core trigger ('Use this when a draft should be sent now') before the detail, and every clause carries operational weight. The dense run-on of error codes is information-rich but slightly over-packed; a 4 rather than a 5.

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

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

With no output schema, the description carries the return-value burden and does so ('returns the message'), while also covering permissions, approval flow, idempotency, list checks, and failure codes. An agent has everything needed to call it correctly and interpret outcomes.

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 each parameter already carries a description, so the schema does the heavy lifting. The description largely restates the input list (required vs optional) without adding syntax or format meaning beyond what the schema provides. Baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Use this when a draft should be sent now.' It is unambiguous that this operates on an existing draft. It does not, however, explicitly distinguish itself from the sibling cooper_send_message, leaving the draft-vs-message distinction to be inferred.

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

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

Provides a clear when-to-use condition ('when a draft should be sent now') plus explicit prerequisites: requires auth and message_send or draft_send scope, and 'draft_write alone cannot send.' No explicit alternative or when-not is named, but the precondition guidance is strong.

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 with real-world consequences: mail is actually delivered and a copy stored, plus the full failure taxonomy (402 limit reached with upgrade_url, 403 inbox_paused, 403 recipient_suppressed with nothing sent/stored/counted, 400/409 idempotency errors) and the 80%-of-limit notice. The idempotentHint=false annotation is not contradicted — client_id/idempotency_key are explicit opt-in and their precedence is documented.

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 trigger and the real-world effect, then walks inputs and errors in a predictable order with no filler sentences. The inputs/error enumeration is dense and long, but each clause carries distinct operational information for a 14-parameter tool.

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

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

With no output schema, the description still supplies the return shape ({id, thread_id, status, from, to, subject, ..., delivery_events}), the replay marker (idempotent true), and the notice structure. Combined with the error codes and auth requirement, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is already 100%, but the description adds semantics the schema lacks: msg_ ids thread via Message-ID/thread_id while other values are copied verbatim to In-Reply-To, content_id enables inline images, client_id is checked before idempotency_key, and the idempotency key charset/replay window are restated usefully. Not fully additive for every field (cc/bcc/labels only echoed), so short of the top score.

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

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

States a specific verb and resource ('send an email from its Cooper address') plus the substantive consequence ('delivers real email on the public Internet and stores a copy'). This cleanly separates it from the draft-oriented siblings (cooper_create_draft, cooper_send_draft) and cooper_reply_message.

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 user asks the agent to send an email from its Cooper address' gives a clear triggering condition. It does not explicitly contrast with alternatives like cooper_send_draft or cooper_reply_message, so the agent must infer the boundary from purpose alone.

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

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

Annotations cover safety (non-destructive, idempotent), and the description adds substantial context beyond them: auth requirement, unscoped-key/owner_manage scoping, the 409 owner_style_locked failure mode, and the guarantee that the note is never surfaced in emails. This is exactly the extra behavioral detail the dimension rewards.

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 usage trigger and scoping decision, then error and behavior notes; every sentence carries information. It is dense and long, but there is little wasted wording beyond minor repetition of the null semantics.

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

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

With no output schema, the description covers the return contract by noting it mirrors cooper_get_owner_preferences, and it supplies auth, scoping, error, and downstream-effect details. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds the pairing rule that inbox_id and owner_id must be supplied together to target one owner and that omitting owner_id sets the account default. Style null-inherits and note null-clears mostly restate the schema, so this is above baseline but not fully additive.

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 precise verb and resource ('Sets the account default... or one owner's style') and cleanly separates the two scopes an agent must choose between. It also positions itself as the setter counterpart to cooper_get_owner_preferences, which is the obvious sibling.

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

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

It names the trigger ('when the human asks for shorter, longer, or friendlier email'), the two operating modes with the exact parameters that select them, and an explicit exclusion ('A style the owner chose from the Change email style link... cannot be changed here: 409'). No inference is required.

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=false, destructiveHint=false, openWorldHint=true), the description discloses that auth is required, that a signed POST is sent and the tool waits for the response, that a disabled hook returns 409 webhook_disabled and sends nothing, and that it fails with 404 webhook_not_found. This is exactly the additional behavioral 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?

The usage condition is front-loaded, followed by auth requirement, inputs, payload shape, return shape, and error codes in a compact sequence. Every sentence earns its place; nothing is padded or redundant.

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

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

With no output schema, the description carries the return contract (delivery object with id, status, response_status, attempts, event_id; status delivered/failed) plus the failure modes (409, 404). For a single-parameter side-effecting test tool, 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 there is only one parameter, so the schema already documents webhook_id as the wh_… identifier. The description repeats 'webhook_id (required)' and shows it embedded in the payload, which adds framing but no meaning beyond the structured data. 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 — confirm a webhook URL accepts a signed POST right now — which is unambiguous and distinguishable from siblings like register_webhook, update_webhook, or rotate_webhook_secret. An agent knows exactly what this tool does 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 an explicit trigger condition: 'Use this when you need to confirm a webhook URL accepts a signed POST right now.' That is clear context for when to invoke it. It does not name alternative tools or state when not to use it (e.g., versus register_webhook), so it stops short of a 5.

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

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

Annotations declare destructive/idempotent/openWorld but say nothing about auth or semantics; the description fills that gap with required scope (message_send or draft_write), the omit-vs-null clearing rules, the send_at unschedule behavior, the immutable reply/forward fields, the reserved scheduled label, and the 409 draft_sending error. That is unusually rich behavioral disclosure beyond the structured fields.

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

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

Usage and the key non-sending constraint are front-loaded, and the enumeration of inputs is dense but each clause carries distinct information (immutability, reserved label, error code). It is a single long paragraph rather than cleanly chunked, which keeps it just short of a 5.

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

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

For a 14-parameter mutation tool with no output schema, the description covers prerequisites, mutation semantics, immutability limits, the reserved label, the conflict error, and the return value ('Returns the updated draft'). 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, but the description adds meaning the schema does not: 'Omit a field to leave it unchanged,' the general null/empty-list clearing rule, and that send_at null removes both the schedule and the scheduled label. The only reason it is not a 5 is that several per-field clear semantics are already in the schema descriptions.

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

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

The opening sentence gives a specific verb+resource ('a draft should change before it sends') and immediately distinguishes the tool from its send sibling with 'This call does not send the draft.' An agent can tell this apart from cooper_create_draft, cooper_get_draft, cooper_delete_draft and cooper_send_draft 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?

The first sentence states exactly when to use it ('when a draft should change before it sends') and the exclusion ('does not send the draft') routes the agent away from a wrong choice. It stops short of explicitly naming cooper_send_draft as the alternative for actually sending, so it is clear context rather than a full when/when-not/alternative map.

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