openagentemail

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds only the 'on this server' scope, which sits somewhat oddly against openWorldHint but does not contradict it; it discloses nothing further about result size, pagination, or empty results.

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 the verb and resource first and no filler. Nothing is wasted and nothing essential is buried.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. For a zero-parameter list tool the description is essentially complete, though it could note the server/identity scope relationship more explicitly given openWorldHint.

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

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

The tool takes zero parameters, so per the baseline a 4 applies. There is nothing in the schema that the description needs to expand, and it correctly implies no input is required.

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 (List) and resource (email identities/addresses) with scope (on this server), which is distinguishable from the sibling mail_new_identity. It is clear but offers no further differentiation from other list-style siblings beyond the resource noun.

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 — an agent can infer it should call this to discover available sender addresses — but there is no explicit when-to-use statement, prerequisite, or reference to an alternative such as mail_new_identity.

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 only the read-only/idempotent safety profile. The description adds a real behavioral model: only source=internal is trusted mail, everything else must be treated as untrusted DATA, and non-internal text/html/snippet values are wrapped in a per-call-nonce UNTRUSTED EXTERNAL EMAIL fence. That is substantial context the agent cannot get from 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?

Dense and front-loaded, leading with the action, scope and returned fields before the security rules. It repeats the fencing rule for snippets and full bodies in two sentences, which is mild redundancy but tolerable given the security stakes.

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

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

An output schema exists, so the field list need not be re-explained, and the annotations carry the safety profile. The one thing structured data cannot express — how to treat message content — is fully covered, leaving nothing an agent needs 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% (address, limit with bounds and server default are fully documented). The description adds no syntax or semantic detail about how address or limit behave, so the baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('List messages received by an identity address') plus ordering ('newest first') and the exact fields returned. An agent can distinguish it from mail_read_message (single message) and mail_list_identities 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?

Usage is implied by the purpose (fetch a mailbox listing for one address), but there is no explicit when-to-use statement and no sibling named as an alternative, e.g. routing to mail_read_message for a single message. The trust-handling guidance is about interpreting results, not about choosing 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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description adds genuinely new behavioral context: the seen flag is shared across all consumers of the mailbox, so toggling it has side effects beyond the caller. It stops short of describing auth requirements or rate limits, so a 4 rather than 5.

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

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

Three tight sentences, front-loaded with the operation and its two states, followed by the cross-consumer caveat and the distinction from reading. 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?

An output schema exists, so return values need no explanation. For a 3-param mutation tool the description covers the state semantics, the shared-flag side effect, and the alternative tools, which is everything an agent needs 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% and the schema already documents id, seen and address with a default for seen. The description's restatement of seen=true/false adds only marginal value beyond the schema, so the baseline of 3 applies.

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

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

Specific verb+resource+state: mark a message as read (seen=true) or unread (seen=false). It also distinguishes itself from mail_read_message by stating that reading never changes the flag, which lets an agent tell the two apart 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?

Explicitly names when not to use it and the alternatives: agents that only need new-mail detection should prefer GET /v1/messages?since= or mail_wait_for. That is a concrete routing instruction, not an implied one.

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 only the safety profile; the description adds the real behavioral load: permission requirements, server-side parentIdentity assignment, scope inheritance rules (child ⊆ parent, cannot grant identities:create), default scopes, and a one-time API token return. This is rich disclosure beyond 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 purpose then permission/scoping details in a compact sequence. It is dense and slightly repeats the scope-default rules already in the schema, but every sentence carries useful information.

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

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

For a high-complexity, multi-tenant scoping operation, the description covers auth model, scope constraints, defaults, and output (address + one-time token). Nothing an agent needs to invoke 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 five parameters. The description restates the scopes defaulting rule (already in the schema) and adds a localpart example, but adds little net meaning beyond the structured fields.

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') and resource ('email identity (mailbox address)') plus the server context, which cleanly separates it from sibling readers like mail_list_identities. An agent knows exactly what the tool produces.

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

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

Explains the admin-key vs non-admin-token paths, the required identities:create permission, and when to pass 'localpart' versus omit it. It gives clear context but does not name alternative siblings or state exclusions, 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 (readOnly, idempotent, non-destructive), and the description adds high-value behavioral context the schema cannot: the internal-vs-external trust model and the per-call nonce UNTRUSTED EXTERNAL EMAIL fence. This directly warns an agent not to follow in-message directives, which is exactly the kind of behavior beyond 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?

Two dense sentences, front-loaded with what is returned before the trust rule. It is compact and every clause carries information, though the trust sentence is unavoidably wordy. 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?

Output schema exists, so return values need not be explained, and the description focuses on the trust boundary. It is complete enough for a read tool, though it could note whether reads are idempotent with respect to seen-state or require the caller to have access to the identity.

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 (id, address) are already documented, including the pattern constraints. The description does not add 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 (Read) and resource (a full message), and enumerates the returned artifacts (text, html, OTP codes, links). The sibling mail_list_messages only lists headers/ids, so the 'full message' framing cleanly distinguishes it.

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

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

The address/id requirements imply use after mail_list_messages or mail_wait_for, and the trust guidance shapes how to interpret the result. There is no explicit 'when not to use' or pointer to siblings for listing vs reading, so it falls one step 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 the safety profile (readOnly=false, openWorld=true, idempotent=false, destructive=false), so the agent knows this is a non-idempotent, side-effecting, open-world write. The description adds the identity precondition, but the schema's 'from' field already says '(must be an existing identity)', so the added behavioral value is largely duplicative; nothing about failure modes or rate limits is given.

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

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

Two short sentences, zero filler, with the send action and its key constraint front-loaded. Nothing to trim.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description plus structured fields give an agent enough to call the tool correctly, though it could note the html/text body relationship.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description only reasserts the 'from' identity constraint, adding no new meaning (e.g., html vs text precedence, subject/body size behavior) 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?

Specific verb+resource ('Send an email') with an explicit scoping detail ('from an existing identity address') that separates it from siblings like mail_read_message or mail_list_messages. An agent knows immediately this is the outbound-send tool.

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

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

It states a clear precondition for use — 'from' must be an identity created with mail_new_identity — and points at that sibling tool by name. It does not state when NOT to use this tool or contrast it with notify_user/notify_agent alternatives for outbound messaging.

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 readOnly/destructive annotations: discloses the newest-20 de-duplication window, true-timeout vs new-unread termination, full-message return including OTP codes, and a security model for untrusted content with a per-call nonce fence. This is exactly the 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?

Front-loaded with the core action and filters, then behavior, then the security caveat. Dense but every clause carries distinct information; the only mild cost is the packed final security sentence.

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?

Though an output schema exists (so return shape need not be spelled out), the description usefully notes the OTP/links payload and timeout error, plus the untrusted-data handling. For a blocking tool with openWorld hint, all decision-relevant context is present.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds meaning by framing fromContains/subjectContains as 'optional filters' and clarifying that timeout results from a 'true timeout,' reinforcing that partial timeout behavior is expected. It adds nuance but not syntax beyond the schema.

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

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

States a specific verb (wait for) and resource (incoming message) with scope (optional from/subject filters), which cleanly separates it from sibling reads like mail_read_message and mail_list_messages. An agent can identify this as the blocking/polling 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?

Explains when the tool applies and its waiting semantics ('skips already-seen matches in the newest-20 window and keeps waiting until a true timeout or a new unread match'), which tells the agent this is a blocking wait rather than a one-shot fetch. It does not explicitly name a non-blocking alternative (e.g. mail_list_messages), 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 the write, non-idempotent, non-destructive profile, so the bar is lower; the description still adds real value by disclosing that the signing secret (whs_...) is returned and only displayed, and that OAuth tokens are denied by default. That is a security-relevant, non-obvious trait the schema does not carry. It does not mention rate limits or duplicate-URL behavior.

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

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

Three short sentences, front-loaded with the action, then the return payload, then the auth caveat. No filler and every clause carries information.

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

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

For a creation tool with an output schema (which removes the need to explain return values further), the description covers the essential context: what is created, what is returned, and the auth default. It omits what happens on duplicate URLs or whether the whs_ secret can be retrieved later, minor gaps for this tool type.

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

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

Schema description coverage is 100%, so all five parameters (url, events, address, description, contentScope) are documented in the schema with constraints and enums. The description adds no additional parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('Create an outbound webhook subscription') that is unambiguous against the mail_webhook_list/delete/test/disable siblings. It does not explicitly name those siblings or contrast itself with them, 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?

No when-to-use or when-not-to-use guidance, and no routing to alternatives such as mail_webhook_test or mail_webhook_list. 'Deny-by-default for OAuth tokens' is a permission note rather than usage guidance, so the agent gets no help deciding when this tool is the right one.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding the non-obvious side effect that pending retries are cancelled and that removal is permanent. It does not say what happens on a missing/already-deleted ID, which matters given idempotentHint=false.

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

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

A single front-loaded sentence with no filler; the permanence and retry-cancellation facts are both stated without wasted words.

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

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

An output schema exists and annotations carry the safety profile, so the description need not explain returns. Combined with one fully-documented parameter, the permanence and retry-cancellation details make it nearly complete, missing only error behavior for a non-idempotent delete.

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 required 'id' parameter is fully documented in the schema (including the whk_... format), so the description adds nothing beyond the baseline.

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

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

States a specific verb (delete), resource (outbound webhook subscription), and effect (cancel pending retries). The adverb 'permanently' implicitly contrasts with mail_webhook_disable, but no sibling is named explicitly.

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

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

Usage is only implied: 'permanently' hints this is the hard-removal path versus mail_webhook_disable, but the description never states when to choose one over the other or any prerequisite.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety and repeatability are covered by structured data. The description usefully adds that this is a pause/mark-disabled rather than a destructive removal, but it does not mention that a second call on an already-disabled hook may fail (non-idempotent) or what happens to pending deliveries.

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 the action, resource and mechanism; there is no filler or repetition.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description is nearly complete for a simple state-toggle; only the non-idempotent retry behavior is left 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?

Only one parameter, and the schema already documents it at 100% coverage including the 'whk_...' ID format. The description adds no syntax or format detail beyond what the schema 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 (pause/disable) and resource (webhook subscription), and the phrase 'marking it disabled' distinguishes it from a hard delete. It does not explicitly name the sibling mail_webhook_delete, but the reversible-pause framing 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?

The word 'Pause' and 'active webhook subscription' imply this is for temporarily stopping delivery on a currently-enabled hook, and the non-destructive framing hints at when to prefer it over delete. However, no alternative (mail_webhook_delete, mail_webhook_test) is named and no preconditions are 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 this a safe, idempotent, read-only, open-world operation. The description adds meaningful context beyond them: the access-control model (self-scoped for identity callers, broad for admins). It stops short of describing pagination or result limits, so not a 5.

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

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

Two short sentences, purpose front-loaded, with the access-control nuance following. Zero wasted words.

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

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

An output schema exists, so return values need not be explained, and access-control behavior is covered. For a simple filtered-list tool this is nearly complete; only result-set behavior (ordering, limits) is 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?

Schema coverage is 100% and the single 'address' parameter is fully documented there. The description restates the address filter and its admin-only restriction, adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: 'List outbound webhook subscriptions.' This cleanly separates it from the sibling mutation tools (mail_webhook_create/delete/test/disable). It does not name those siblings explicitly, so it falls short of a 5.

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

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

The description explains visibility semantics (identity callers see only their own, admin callers see all or filter by address), which implies when the tool is useful. However, it gives no explicit when-to-use vs. alternative guidance and no exclusions.

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

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

Annotations already declare openWorldHint=true, readOnlyHint=false and non-destructive/idempotent false, so the side-effecting, outward-facing nature is covered. The description adds only that the probe is 'immediate' — it does not say whether the call blocks on delivery, whether it mutates delivery state, or if it counts against 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?

A single front-loaded sentence with no filler; the action and object lead the reader immediately.

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

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

An output schema exists so return values need not be explained, and the tool is low-complexity with one parameter. However, for a tool that fires an outbound request, the description omits prerequisites (existing/enabled subscription) and the meaning of a probe result, leaving the agent to infer them.

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

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

With a single parameter and 100% schema description coverage, the schema already documents the 'id' field and its whk_... format. The description adds no additional meaning about that identifier, 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 ('Send an immediate probe ping') and resource ('webhook connectivity'), which reads clearly against siblings like mail_webhook_create/delete/disable. It does not explicitly name those siblings or contrast the operation, 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?

The description gives no when-to-use guidance: it never says the subscription must already exist, whether it must be enabled, or what a result implies (e.g., whether failed delivery is retried). No alternative tool is referenced because none exists, but prerequisites are absent.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the mutation/network profile is covered structurally. The description adds real context with 'the server owns topics and credentials' (caller need not supply or manage those), but says nothing about wake side effects, delivery guarantees, or the consequences of the non-idempotent hint.

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

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

Three short sentences with no filler, and the wake action is front-loaded before the address and credential qualifications. Nothing is redundant enough to cut, though the credential notice is a slightly tangential trailing clause.

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

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

With an output schema present, return values need no explanation, and 100% parameter coverage means the schema carries the argument detail. The description sufficiently covers action, addressing, and credential ownership for a 5-parameter mutation tool, though a note on wake delivery behavior would fully close it.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the address-format preference and legacy localpart fallback. The description's address guidance duplicates the schema's own wording rather than adding format examples or edge-case rules, 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 ('Wake'), resource ('a named agent'), and mechanism ('server-side notification route'), so the agent knows exactly what happens. The agent-vs-user distinction from the sibling notify_user is left implicit rather than named, which keeps it short of a 5.

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

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

The description gives format guidance (prefer full identity address, bare localpart for legacy deployments) which is useful usage context. However it never states when to choose this tool over notify_user, or any conditions/exclusions, so the routing guidance remains implied.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful non-schema context: the server maps the token to its own topic and no ntfy credential is exposed, clarifying the auth/isolation model. It does not describe rate limits or payload shape, but that gap is small.

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

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

Two sentences, zero filler, with the read scope and the identity/topic mapping front-loaded. Every clause earns its place.

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

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

For a single-parameter read tool with an output schema and annotations covering safety, the description covers what an agent needs: what it reads, whose data, and that credentials are not exposed. Return values are handled by the output schema, so nothing critical is missing.

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

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

Schema coverage is 100% and the single 'since' parameter is fully documented in the schema as an ntfy duration or timestamp filter. The description adds no parameter-level detail, 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 (read recent notifications) and scopes it to 'this identity only', which distinguishes it from notify_user/notify_agent (which send) and from the mail_* readers. It does not name those siblings directly, so it falls short of a 5, but the purpose is unambiguous.

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

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

Usage is implied (read your own recent notifications rather than sending), but there is no explicit when-to-use/when-not guidance and no named alternative such as notify_verify or the notify_agent counterpart. The scoping phrase 'for this identity only' is the only routing hint.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive action. The description adds valuable behavioral context beyond annotations: identity tokens require the server-side can_notify_user grant, and no topic or ntfy credential is needed.

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

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

Two sentences, front-loaded with the core action and then the auth/credential constraint. There is no wasted 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 notification action with full schema coverage, annotations, and an output schema, the description covers purpose, audience, and auth requirements well. It could go slightly further by naming when to prefer notify_agent or notify_check, but it is largely complete.

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

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

Schema description coverage is 100%, so the schema fully documents title, message, level, and tags. The description adds only a credential-related note that does not map directly to the listed parameters, 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?

The description states a specific verb and resource: 'Send a human-alert notification.' It distinguishes this from sibling notify_agent by explicitly scoping the alert to a human rather than an agent.

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

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

It gives clear context for when this tool applies (human-alert notifications) and states an important prerequisite for identity tokens. It does not explicitly name alternatives like notify_agent or notify_check, but the human-vs-agent framing is clear enough.

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

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

Annotations declare non-read-only, non-idempotent, open-world, non-destructive; the description adds that the check is harmless, server-side, and polled back, plus a permission prerequisite. That is meaningful context beyond the annotations, though it doesn't explain what the poll returns or how long it waits.

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, followed by the prerequisite. No filler or redundancy.

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

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

An output schema exists so return values need not be described, and the permission requirement is covered. The one gap is the missing contrast with the sibling notify_check, which leaves a plausible selection ambiguity.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless schema 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 pair (send a check, poll it back) and the resource (server-side notification check), so the mechanism is clear. However, it does not distinguish itself from the sibling notify_check, which an agent could easily confuse it with.

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?

Implies the use case (verifying notification delivery) and names a prerequisite (same human-alert permission as notify_user), which is real guidance. It gives no explicit when-not condition and does not say how it differs from notify_check or notify_user.

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 mark this as a non-idempotent, non-destructive, open-world mutation, so the baseline burden is lower. The description still adds substantial behavioral context the annotations lack: the 24-hour generation cap, the 7-day hard ceiling, and the lease-receipt reclaim rule. It reads like genuine lifecycle documentation rather than restating 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?

Two sentences, front-loaded with the core action before the caps and reclaim conditions. Dense but every clause carries distinct lifecycle information; the trailing lease-receipt clause is the only mildly heavy phrasing.

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

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

An output schema exists, so return values need no explanation here, and the description covers the tricky lease/reclaim/expiry semantics an agent needs to call this correctly. It stops just short of naming sibling tools for renew/release, which is the remaining gap.

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

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

Schema coverage is 100% (both id and leaseSec carry descriptions including range and default), so the schema already does the heavy lifting and baseline 3 applies. The description adds the concept of a 'bounded lease' but no syntax or unit detail for leaseSec beyond what the schema states.

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

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

States a specific verb and resource ('Claim a submitted task as its managed recipient for a bounded lease'), making the operation clear. It hints at the task_renew sibling ('cannot claim or renew') but never explicitly names the alternatives, so sibling differentiation is only partial.

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 real when-conditions (24h per-generation cap, 7-day first-claim ceiling, reclaim allowed with an expired or released lease receipt), which is more than implied usage. However, it never routes the agent to task_renew, task_release, or task_decide for the adjacent operations, leaving alternative selection to inference.

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

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

Annotations only declare the mutation/open-world profile; the description goes well beyond them, disclosing that a stamped email thread is created, that the recipient agent route is woken, exact limits (65,536 canonical UTF-8 bytes, depth 10, 30-day expiry), named stable client error codes, and the wait-versus-poll tradeoff. This is rich behavioral context an agent cannot get from 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 purpose and side effects, then constraints, then the wait/follow-up behavior. Dense but nearly every clause is informative; the constraint list is somewhat packed 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 an output schema present, return values need not be explained, and the description covers the risky part (nested approval object limits, errors, wait behavior). It leaves minor details like parentTaskId semantics and recipient format to the schema, which is acceptable.

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 86% and already documents most params, so the baseline is 3. The description adds semantics the schema does not: that approval actions are JSON-only with byte/depth/expiry constraints and the resulting error identifiers, plus the wait semantics keyed to MCP_MAX_WAIT_SECONDS.

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 ('Assign a task to another managed identity') and immediately describes the concrete side effects ('creates a stamped email thread and wakes that identity's agent route'), distinguishing it from a plain mail or notify tool. It also names task_get as the path for longer work, so it is separable from its 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?

It gives clear operating context for wait=true and explicitly routes the agent to task_get for longer-running work, which is actionable. It does not state when to prefer task_create over notify_agent or mail_send, so exclusions/alternatives are only partially 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?

Annotations declare non-readOnly, non-idempotent, non-destructive, open-world. The description adds genuine context beyond that: the decision is attributed to the token-bound identity (an auth concern), and it explicitly scopes side effects by saying the action is never executed. It stops short of covering repeats (idempotency behavior on an already-decided task), which is the main remaining gap.

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

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

Two short sentences, no filler, with the action and the scoping caveat front-loaded. Every clause carries information.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers the two things an agent most needs to know (who the decision is attributed to, and that nothing executes). Only edge-case behavior such as re-deciding an already-decided task is left 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?

The description never mentions either parameter. With schema description coverage at 50%, only 'id' is documented in the schema; the description does not compensate for the undocumented 'decision' field or explain the approve/reject semantics. What the schema does provide (a UUID-constrained id and a two-value enum) is self-evident, so the description adds nothing 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 pair (approve/reject) on a specific resource (approval task) and scopes the acting identity to the MCP token. This is clearly distinguishable from siblings like task_update, task_claim, and task_release.

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 clause 'This records a decision only; it never executes the action' usefully frames the effect and implicitly marks this as the decision-recording step distinct from task_update or task_claim. However, it never states when to choose this over those siblings or what prerequisites (e.g., task must be pending, must be assigned to the token's identity) apply.

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/destructive=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: it returns server-stamped state history and surfaces the edge case where a durable lease retained while leases are disabled appears with leaseStatus=disabled. That is non-obvious operational detail not derivable from the schema.

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

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

Two tight sentences with the read action front-loaded and the lease edge case trailing. No filler, though the second sentence is somewhat cryptic without domain context and slightly compresses what could be clearer.

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 rich annotations, full parameter coverage, and an output schema covering return values, the description only needs to add nuance — which it does via the state-history and leaseStatus=disabled notes. The missing piece is when-to-use routing against list/decide siblings.

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% for both parameters (id formats and the wait semantics including MCP_MAX_WAIT_SECONDS are documented in the schema), so the baseline is 3. The description adds nothing about id or wait, but nothing is needed given the rich 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 ('Read one task thread and its server-stamped state history'), which is clearly distinct from list-style siblings like task_list and task_list_children. It stops short of naming any sibling to route against, but the singular 'one task thread' framing makes the scope unambiguous.

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

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

The description says what the tool reads but never states when to prefer it over task_list or task_list_children, nor any prerequisite such as needing an id from task_create/task_list (that detail lives only in the schema). Usage is implied by 'one task thread' but not articulated.

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, openWorld, and non-destructive behavior. The description adds a non-obvious behavioral detail: a durable lease retained while leases are disabled is visible with leaseStatus=disabled.

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

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

Two compact sentences, with the core list action front-loaded. The lease sentence is useful but somewhat cryptic and may not be needed for invocation, though it does not create significant 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?

For a simple list tool with one optional enum, rich annotations, and an output schema, the description covers scope and a useful lease edge case. It omits routing guidance relative to task_get and task_list_children, but otherwise is complete enough.

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 optional state enum is fully described in the schema itself. The description only restates that tasks can be filtered by current state, adding no syntax or semantics 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 'List' and resource 'email-backed tasks' scoped to this identity, with optional state filtering. It distinguishes itself from generic task tools via 'email-backed', but does not explicitly differentiate from siblings such as task_get or task_list_children.

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 only says what can be listed and that state filtering is optional; it gives no guidance about when to choose this tool over task_get, task_list_children, or other task tools. No exclusions or selection context are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that the description adds genuinely non-obvious behavior: results are viewer-filtered before paging and contain no totals or descendants, which tells the agent what it will and will not receive.

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

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

Two compact sentences with zero filler, and the defining scope constraint ('only direct readable children') is front-loaded. Every clause carries information.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description usefully covers filtering and paging behavior. The only real gap is the unaddressed limit/cursor parameters, which leaves pagination semantics slightly under-specified for an agent that must page.

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% (just parentTaskId), and the description does not compensate: it never explains the enum-limited 'limit' values (20/50/100) or the 'cursor' pagination token. The one documented parameter's meaning is already in the schema, so the description adds nothing for the two undocumented ones.

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 ('List only direct readable children of a readable parent') and the 'direct' qualifier implicitly excludes descendants. It is clear on its own, but it never names or contrasts with the obvious sibling task_list, so an agent must infer the boundary between them.

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

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

Usage is only implied: the description conveys that this is for direct-children retrieval as opposed to a full task listing, but there is no explicit when-to-use/when-not or alternative routing (e.g. 'use task_list for all tasks'). The agent gets the gist without firm 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 this is a non-read-only, non-idempotent mutation, so the safety profile is covered. The description usefully adds the requirement that the token must be the current *active* one, implying stale tokens fail, but it does not say whether release revokes the lease for other holders, whether it can be retried, or what a failure looks like for a non-idempotent call.

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

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

One front-loaded sentence with no filler or repetition of the title. It is efficient, though the extreme brevity leaves the reader wishing for one more clause about behavior, so it is terse rather than optimally structured.

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?

Because an output schema exists and schema coverage is 100%, return values and parameter formats need not be explained here. Still, for a non-idempotent mutation with no exclusions stated, the description omits what releasing actually does and how stale-token failures behave, leaving a meaningful behavioral gap.

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

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

Schema description coverage is 100%, so both required parameters (id, leaseToken) and the optional reason are already documented in the schema. The description's 'current active opaque lease token' roughly restates the schema's own wording, adding no syntax, format, or retrieval guidance (e.g., where the token comes from) beyond 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?

The description names a specific verb ('Release') and resource ('a task lease'), which is enough to distinguish it from task_claim and task_renew at a glance. It stops short of stating the effect of the release (freeing the task for other claimants), so an agent knows the operation but not its consequence.

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

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

The phrase 'only with its current active opaque lease token' states a precondition for calling the tool, which is useful implied usage guidance. However, it never says when to release versus renew (task_renew) or what to do when the lease has already expired, so alternatives 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 only give the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds real behavioral rules beyond that: renewal does not reset the generation's 24-hour cap or the first-claim seven-day cap, and token equality is rejected. That is meaningful extra context about limits and failure modes, though it doesn't cover auth requirements or what happens on an expired token.

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 dense sentences, front-loaded with the core action and its prerequisite, then the cap/equality rules. No filler whatsoever.

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

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

An output schema exists, so return values need no explanation, and the description covers the operation's key behavioral limits. It is nearly complete for this tool; only failure handling detail (expired/invalid token, what happens at cap) is 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?

Schema description coverage is 100%, so the schema already documents id, leaseSec (30..3600, default 300) and leaseToken. The description reinforces that the token must be the current active one, adding marginal semantic value over the schema but not new format or default information.

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 ('Renew') and resource ('task lease'), and adds the key constraint that renewal requires the current active opaque lease token. It does not explicitly differentiate itself from close siblings like task_claim or task_release, so it falls short of a 5.

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

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

Usage is implied rather than stated: 'only with its current active opaque lease token' tells the agent a precondition exists (you must already hold the lease), but there is no explicit when-to-use versus task_claim/task_release, nor a stated condition for choosing renewal over re-claiming.

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 (non-read-only, non-destructive, non-idempotent), and the description adds genuinely useful behavior: the server stamps the state header, completed/failed are terminal, and result is written as a JSON result block in the reply body. It does not cover auth requirements or what the error returns imply for retry, keeping it below 5.

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

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

Three dense but purposeful sentences, with the core action front-loaded. No filler or restated name/title, though the lease-token sentence is compact enough to require careful reading.

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

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

An output schema exists so return values need not be explained; the description instead covers the non-obvious concerns for this mutation: terminal states, lease-token outcomes, and where result lands. Missing only permission/authorization context and explicit sibling routing.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds meaning beyond the schema for two parameters: leaseToken's retention/error semantics and result's server-side write behavior. It does not elaborate on body or state transitions per value, so not a 5.

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

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

States a specific verb and resource ('Advance a task') and constrains the actor to 'one of its two participants'. It is clear on its own, but does not distinguish itself from siblings like task_decide, task_claim, task_renew, or task_release, so an agent cannot route between them from this text 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?

Gives real conditional guidance about leaseToken: omitting it with an active lease retains task_already_terminal, while a wrong/expired token returns task_lease_required. However, it never states when to prefer this tool over task_decide/task_claim/task_release, so selection between task siblings remains implied.

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