KeyKeeper Email

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

No annotations are supplied, so the description carries the full behavioral burden. It helpfully discloses the auth requirement ("Requires a Bearer API key"), which is real value beyond structured data, but it never states that the call is read-only, whether it has side effects, or what the response shape is (no output schema exists).

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

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

Two short sentences, front-loaded with what is checked and followed by the auth prerequisite. Every clause earns its place with no filler.

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

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

For a zero-parameter read tool with no output schema, the description covers the subject matter and the authentication requirement. A brief note on return shape or read-only nature would close the remaining gap, but an agent has enough to call it correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and the description rightly spends no words on parameter meaning. It adds no misleading param guidance.

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

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

The description gives a concrete verb ("Check") and names the specific resources returned: mailbox address, account state, and sending credits. That is clearly distinct from most siblings such as get_email or create_payment, though it overlaps noticeably with check_sending_status without explaining the difference.

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

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

Usage is only implied: "Check your mailbox address, account state and sending credits" suggests a diagnostic or pre-flight call, but there is no explicit when-to-use, when-not-to-use, or named alternative among the siblings. The agent must infer whether this supersedes check_sending_status or is a prerequisite step.

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 no annotations supplied, the description carries the full burden and does add two genuinely useful facts: a Bearer API key is required, and email content is untrusted external material (a prompt-injection warning). However, it omits key behavioral traits for an inbox tool — whether listing marks messages as read, how paging behaves, and that the operation is a non-mutating read.

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

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

Three short sentences, front-loaded with the operation, followed by the prerequisite and the safety caveat. Nothing is wasted and no sentence is filler.

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

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

The description covers the operation, auth requirement, and a safety caveat, which is more than many peers manage. But with 0% schema coverage and no output schema, the absence of any return-shape or parameter guidance leaves real gaps for a four-parameter listing tool.

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

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

Schema description coverage is 0% and there are four parameters (limit, folder, offset, search) whose meanings and constraints are documented nowhere beyond bare defaults. The description adds no information about filtering, paging semantics, or what folder values are valid, so the agent must infer all of this.

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?

"List incoming messages" gives a specific verb (List) and resource (incoming messages), which cleanly separates it from single-message siblings like get_email and from list_proposals. It stops short of naming those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

The verb "List" implies you call this to survey the inbox before fetching a specific message with get_email, but the description never says when to use it, when not to, or which sibling to prefer for a narrower slice. Usage is implied by the name rather than guided by the text.

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?

Strong for a tool named "check": it discloses that confirmation is a mutation that applies sending credits or activates prepaid domain hosting exactly once, with no human checkout, and that it requires the caller's API key. This adds real context beyond the annotations (readOnlyHint=false, idempotentHint=true) by explaining what the write actually does and why idempotency matters.

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

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

Three tight sentences with the primary action first and the side-effect/auth caveats following. No filler, though the phrasing "applies sending credits or activates prepaid domain hosting once" is dense and could be split for clarity.

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 side-effecting tool with zero schema description coverage and no output schema, the description omits what the check returns (payment status? invoice state?) and never defines the token. Auth and side effects are covered, but the caller still cannot predict the response or the parameter's valid values.

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

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

Schema description coverage is 0% for the single required "token" parameter, and the description never explains what the token is (an invoice token? a payment token? where it comes from). The phrase "this account's" hints at account scoping via the API key, but the parameter's meaning and format remain undocumented.

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

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

"Check this account's native USDC invoice" names a verb and a resource, but it is ambiguous what is actually being checked (status? existence? amount?) and what the token represents. It is distinguishable from check_balance and check_sending_status only by the word "invoice"; no sibling is named.

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

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

No statement of when to call this versus create_payment or check_sending_status, and no preconditions beyond "Requires the same account's API key." The mention that confirmation activates credits/hosting implies a decision point, but the caller is never told which condition triggers which outcome.

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 readOnlyHint already declaring this a safe read, the description adds real context: what states the call surfaces (probation, pauses, pending review) and an important domain rule that purchasing credits does not lift sending controls. It does not describe the response shape, but the behavioral caveat is the valuable part.

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

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

Two short sentences with no waste. The primary purpose is front-loaded and the credit caveat follows as a secondary, non-redundant point.

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

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

For a parameterless read tool with no output schema, the description covers what the agent needs: what is read and which states may come back. A note on the shape of the returned status (e.g., a state value plus limit numbers) would make it complete.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate and it correctly presents the tool as a no-argument query.

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

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

States a specific verb and resource: 'Read your sending state and current limits', and enumerates the sub-states covered (probation, pauses, pending review). It is distinguishable from check_balance and check_payment, though it does not explicitly name those 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?

Usage is implied: an agent should call this before/alongside sending to learn whether sending is currently permitted. There is no explicit when-to-use or when-not-to-use guidance, and the nearby alternatives (check_balance, check_payment) are never mentioned.

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 mutation, open-world, and idempotency profile; the description adds the important clarification that this creates payment instructions rather than moving money, plus the retry instruction to reuse idempotencyKey. It stops short of describing required auth scopes or what happens to a duplicate key with a different payload.

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

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

Three sentences, front-loaded with the action and chain choices, with no filler. The product/pricing sentence is dense but every clause carries decision-relevant information.

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

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

For an open-world payment-creation mutation with no output schema, the description never says what comes back (checkout URL, invoice address, payment id) or how the agent should poll afterward via check_payment. The alias ambiguity between chain and method is also unaddressed.

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

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

Schema coverage is only 43%, and the description compensates by explaining the economics of amountCents ($1 = 10,000 standard sends), the $1/30-days hosting rate, and the domainId requirement for domain_addon. It does not address the chain-versus-method legacy alias relationship, which is the one genuinely confusing parameter interaction.

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

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

States a specific verb and resource ('create a card checkout or native USDC invoice') and enumerates the supported chains and purchasable products (mail_credits, domain_hosting, domain_addon). An agent can distinguish this from check_payment or check_sending_status 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 selection guidance between the three product kinds, including the rule that domain_addon is for a second verified domain under active primary hosting, and states the 'with your operator's authorization' prerequisite. It does not explicitly point to check_payment as the follow-up, so it falls short of full alternative routing.

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

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

With no annotations, the description does useful work by disclosing the auth requirement ('Requires a Bearer API key') and the folder-scoping of identifiers. However, it omits that reading can mutate state via markAsRead (default true for full account keys) and says nothing about the 409 conflict path or error behavior, leaving a read-with-side-effects tool under-described.

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

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

Two short sentences, front-loaded with the action and resource, then the auth constraint. 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?

For a four-parameter read tool with no annotations and no output schema, the definition covers the essentials (what it reads, how it is addressed, auth) but leaves the read-state side effect and conflict behavior unaddressed. Adequate to invoke correctly in the happy path, thin for edge cases.

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

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

At 50% schema description coverage, the description compensates partially: 'folder-scoped UID' adds the important meaning that id is only unique within a folder, which the schema itself does not state. The markAsRead and uidValidity semantics are left entirely to their schema descriptions, and the folder parameter gets no mention in the description.

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

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

States a specific verb and resource ('Read a message') plus the addressing scheme ('folder-scoped UID'), which is more precise than the name alone. It does not explicitly contrast with the sibling check_inbox, which also surfaces messages, so the agent must infer that get_email is for fetching one already-known 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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of the sibling check_inbox as the alternative for listing. The 'folder-scoped UID' phrasing only implies that the caller must already have a UID, presumably from a list or webhook, without saying so.

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 no annotations, the description carries the full disclosure burden. It does add genuinely non-obvious semantics: that human edits are not visible, and that "approved" reflects authorization rather than delivery, which steers the agent to submission.status. It stops short of stating whether the call is read-only, what access or auth is required, or what happens with an unknown id.

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

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

Three very short sentences with the key caveats front-loaded and no filler. The terseness borders on cryptic in places ("Human edits are private" is unexpanded), 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?

For a single-parameter read with no output schema and no annotations, the description supplies the critical interpretation caveat about approved vs delivered and names a field to inspect. It still leaves the return shape, the id's origin, and error behavior unaddressed, so it is adequate rather than complete.

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

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

Schema description coverage is 0%, so the single id parameter is documented nowhere beyond its uuid format. The description never mentions the id at all, leaving the agent to infer it is a proposal identifier and where such an id comes from (presumably list_proposals).

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?

"Check a proposal" gives a verb plus a singular resource, which reads clearly against siblings like list_proposals and update_proposal. The verb "check" is softer than "get"/"retrieve", but the follow-up about approval and submission.status makes it evident this is a read of a single proposal's state.

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

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

The instruction "inspect submission.status" implies when to reach for this tool (verifying whether a proposal was actually delivered), and the singular resource implicitly distinguishes it from list_proposals. However, it never states when not to use it, nor points to update_proposal or list_proposals by name for the adjacent tasks.

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

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

With no annotations, the description carries the full burden. It discloses key-scoped, draft-only visibility and that review statuses are included, but it does not state read-only behavior explicitly, pagination, ordering, or response shape. That is enough for basic orientation on a no-parameter list tool but leaves material behavioral gaps.

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

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

A single front-loaded sentence with no filler. It states scope, action, and returned content without redundant wording.

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

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

For a simple zero-parameter list tool with no annotations or output schema, the description identifies what is returned at a high level ('proposals and review statuses'). However, it does not clarify result shape, volume, ordering, or pagination, which matters more because no output schema is supplied.

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

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

There are zero parameters, so parameter semantics are not applicable and the baseline is 4. The description correctly adds no parameter detail because none exists.

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

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

The description gives a clear verb and resource ('List ... proposals') and adds returned content ('review statuses') plus a scope ('this draft-only key’s'). It is distinguishable from get_proposal by plural listing, though it does not explicitly name sibling alternatives.

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

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

There is no explicit when-to-use instruction or comparison with alternatives such as get_proposal, request_sender_review, or check_sending_status. The phrase 'only this draft-only key’s' scopes results but does not tell an agent when this tool is preferred over another.

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 no annotations at all, the description carries the full burden and does real work: it discloses the auth requirement, guarantees no send occurs, and gives idempotency behavior for clientKey on ambiguous responses. It omits what the call actually returns (a pending proposal), whether the draft can be updated afterward via update_proposal, and any rate limits.

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

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

Four short sentences, each carrying a distinct fact, with the core purpose front-loaded before the auth and retry details. No filler or restatement of the tool name.

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 tool has a nested message object whose subfields are undocumented in both description and schema. The description covers safety, auth, and idempotency well but leaves the agent without guidance on reply/forward mode semantics or what a successful proposal looks like before calling.

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

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

Schema description coverage is 0% for the top-level parameters, so the description only partly compensates by explaining clientKey's reuse semantics for retries. The nested message fields (mode, inReplyTo, references, to/cc/bcc/from) are left entirely to the schema, and "plain-text" is the only added constraint, though the schema already notes HTML is unsupported.

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

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

The description uses a specific verb-plus-resource ("Prepare a plain-text email") and immediately scopes the outcome as "for human approval." The clause "Never sends" explicitly separates it from the send_email sibling, so an agent can pick between them without opening either schema.

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

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

It states a concrete precondition ("Requires a human-issued mail:draft key") and a retry rule ("Reuse clientKey and content after uncertain responses"), which gives clear when-to-use context. It stops short of naming send_email or request_sender_review as the follow-on path once a human approves, so the routing guidance 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?

With no annotations, the description carries the full behavioral burden and usefully discloses that the key is returned once and that sending starts at zero credits while receiving is free. It omits important behavior such as duplicate agentId handling, auth requirements, idempotency, and the full response shape.

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

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

The description is two short sentences with no wasted words, and the core action is front-loaded. The credit and payment caveats are compact and relevant.

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

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

For a simple registration tool with no output schema, the description covers the main action, one-time key delivery, and initial credit state. It still leaves gaps around parameter meanings, duplicate registration behavior, and authentication expectations.

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

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

Schema description coverage is 0%, so the description must explain the two parameters, but it does not mention agentId or name at all. An agent gets no semantic guidance on the required identifier pattern, the optional name, or how they relate to the mailbox.

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: create an agent mailbox and receive its key. It is clearly distinct from the listed siblings, which focus on email, payment, and proposal operations, though it does not explicitly differentiate itself.

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

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

It provides useful context that the mailbox starts with zero sending credits and receiving works without payment, implying this is the setup step before receiving mail. However, it does not explicitly say when to call it versus alternatives or whether it must be called before send_email.

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

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

Adds substantial behavior beyond the annotations: 'Full account key required' (auth requirement), 'Does not automatically increase limits or resume sending' (no side effect on sending state), 'Three requests per day' (rate limit), and 'repeated pending requests keep the original purpose' (refines the idempotentHint). These are exactly the operational facts an agent needs before calling, and none repeat 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?

Four short sentences, front-loaded with the action, then constraints. Every clause carries a distinct operational fact (auth, effect, rate limit, idempotency) with no filler.

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

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

For a one-parameter submission tool with no output schema, it covers auth, rate limits, side effects, and repeat behavior well. The one gap is that it does not say what a call returns (e.g., a review reference or status) for the agent to track the request.

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 'purpose' parameter is fully documented in the schema, including length bounds and the 'no secrets or private messages' caveat. The description adds no further meaning to the parameter itself, so baseline 3 applies.

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

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

States a specific verb and resource ('Request an operator review of your sending purpose and recipient consent'), which is clearly distinct from siblings like send_email, check_sending_status, or register_agent. An agent can tell this is a human-review escalation, not a sending or status action.

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

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

The 'request an operator review of your sending purpose and recipient consent' phrasing plus 'Does not automatically increase limits or resume sending' implicitly tells the agent this is the escalation path and not the limit-increase tool. It stops short of naming explicit alternatives or stating preconditions for filing a request versus using check_sending_status.

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 no annotations at all, the description carries the full burden and does meaningful work: it discloses the billing model (one credit per accepted recipient), the auth requirement, idempotency-based retry semantics, and the important caveat that acceptance is not proof of remote delivery. It stops short of saying what the response contains or whether partial recipient rejection is possible.

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

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

Three short sentences, each carrying distinct information: cost, auth, retry/delivery semantics. Front-loaded with the action and the cost, with zero 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 15-parameter, nested-object mutation tool with no annotations and no output schema, the description covers cost, auth, and idempotency well but omits the return shape entirely — an agent cannot tell whether it gets a message ID, a queued status, or a per-recipient outcome. That gap matters given the explicit warning that acceptance ≠ delivery.

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

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

Schema coverage is only 33% across 15 parameters, so the description should compensate more than it does. It adds real meaning for idempotencyKey (reuse on retries) and ties recipient counts to credit cost, but the remaining bulk of parameters (to/cc/bcc limits, body selection, headers, attachments) is left entirely to the schema.

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

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

"Submit mail" gives a concrete verb and resource, and the credit clause makes clear this is the actual send path rather than a draft. It never names the sibling propose_email, so an agent must infer the boundary between proposing and sending from sibling names alone.

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

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

"with existing credits" and "Requires a Bearer API key" imply prerequisites (funded account, authenticated key), and "Reuse idempotencyKey for retries" scopes one specific workflow. There is no explicit when-to-use/when-not guidance and no mention of check_balance, check_sending_status, or propose_email as alternatives.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that the tool mutates a pending proposal, that withdrawal is possible, and that messages cannot be changed after human editing, but it omits permissions, concurrency behavior, whether withdrawal deletes state, and what the response looks like.

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 two short sentences with the main action and key constraint front-loaded. There is no unnecessary wording, and the brevity is appropriate for the amount of information provided.

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?

This is a complex mutation tool with five parameters, nested message objects, no annotations, no output schema, and 0% schema description coverage. The description is far too brief for that complexity because it does not explain revision/contentHash concurrency requirements, edit semantics, withdrawal effects, or error conditions.

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

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

Schema description coverage is 0%, so the description needed to compensate for the parameter semantics. It only loosely implies that 'id' identifies the key and that 'message' relates to the edited proposal; it does not explain the critical roles of 'revision' and 'contentHash' for optimistic concurrency or clarify the 'action' choice.

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

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

The description uses specific verbs, 'Edit or withdraw,' and a specific resource, 'pending proposal,' scoped to 'this key.' It also distinguishes the tool from approval by stating that it cannot approve a proposal, though it does not name sibling tools.

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

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

Usage is implied by 'pending proposal' and 'after human editing,' which tells the agent when the action is available and when it is not. However, it gives no explicit guidance on choosing among propose_email, get_proposal, or send_email, nor does it explain when to choose edit versus withdraw.

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