openagentemail

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result includes all identities and that they are addresses on this server, but it does not disclose details like ordering, pagination, or authentication requirements. This is acceptable for a simple list tool but adds only modest behavioral context 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?

The description is a single, front-loaded sentence with no wasted words. It conveys the action, resource, and scope efficiently.

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

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

Given the tool's low complexity, zero parameters, explicit annotations, and the presence of an output schema, the description fully covers what an agent needs to select and invoke it correctly. Nothing important 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?

The tool has zero parameters and the schema is empty, so there is nothing for the description to clarify. Per the baseline for parameterless tools, this is sufficient without additional explanation.

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 ('List') and resource ('email identities') and clarifies that these are addresses on the server. This clearly distinguishes it from siblings like mail_list_messages, which lists messages rather than identities.

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

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

The description makes the tool's context obvious: call it to see all email identities on the server. It does not explicitly state when not to use it or name alternatives, but the resource type is distinct enough that an agent can infer the appropriate use case.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral traits: newest-first ordering, the security classification of source=internal versus untrusted external data, and the UNTRUSTED EXTERNAL EMAIL fencing applied to non-internal content. This is rich, non-obvious behavior that materially affects how an agent handles 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?

Three sentences, each earning its place: the first delivers the core purpose and output fields, the second establishes the security boundary, and the third specifies fencing behavior. Front-loaded and free of fluff 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?

With a full output schema present, the description covers everything needed to invoke correctly: address parameter, optional limit, field list, ordering, and critical security handling. Nothing essential is missing for a read-only 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 100%, with clear descriptions for both address and limit. The tool description adds no additional parameter-level semantics beyond what the schema already provides; it only references 'identity address' in passing, which mirrors the schema.

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

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

The description opens with a specific verb and resource: 'List messages received by an identity address', followed by the exact fields returned (id/from/to/subject/date/seen/snippet/hasOtp/source). This clearly distinguishes it from siblings like mail_read_message (single message) and mail_list_identities (list identities).

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

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

The description makes the core use case clear (listing messages for an identity) and implies metadata/snippet retrieval by enumerating fields. However, it does not explicitly state when to use this tool instead of mail_read_message (e.g., 'for full body use mail_read_message') or any exclusions, leaving some inference to the agent.

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 indicate this is a mutating, idempotent, non-destructive operation. The description adds meaningful context beyond those hints: the seen flag is shared across all mailbox consumers, and merely reading a message never updates this flag. This clarifies cross-tool side effects and helps agents reason about shared state.

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

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

The description is three tight sentences. The core operation is front-loaded, the cross-tool caveat is placed second, and the read behavior clarification is last. Every sentence earns its place, and there is no redundant 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 simple state-flip tool with a fully documented input schema, an output schema, and annotations covering idempotence and mutation, the description is complete. It covers the operation, the shared-state consequence, and the appropriate alternative for new-mail detection, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description itself repeats the seen=true/false semantics but does not add additional parameter-level meaning beyond the schema. It does not explain address or id in more depth, though the schema already handles that adequately.

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

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

The description opens with a precise, specific statement: 'Mark a message as read (seen=true) or unread (seen=false).' This identifies the exact verb, resource, and state transition. It also distinguishes the tool from new-mail detection flows by pointing to sibling alternatives, so an agent can tell what this tool is for and what it is not for.

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 explicit routing guidance: 'agents that only need new-mail detection should prefer GET /v1/messages?since= or mail_wait_for.' It also warns that reading a message does not change the seen flag, which prevents a likely misuse. This is strong when-to-use vs. when-not-to-use guidance.

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

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

Beyond the annotations, the description reveals important behavioral traits: parentIdentity is set server-side, child scopes default based on the parent, child scopes must be a subset, identities:create cannot be granted, and omitting scopes for admins means legacy full permissions. It also states the return contains the full address and one-time API 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?

The description is dense but front-loaded: it states the core action first, then covers permission rules, parameter behavior, and return value. Every sentence adds necessary information without 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?

Given the auth complexity, optional parameters, and output schema, the description covers the full calling contract: admin vs non-admin behavior, scope constraints, localpart semantics, and return value. The output schema can carry return details, and the description fills in the server-side logic.

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?

While schema coverage is 100%, the description adds meaningful semantics: localpart gives a custom address like qa-bot@domain or a random one when omitted, and scopes have default/fallback behavior depending on role. This goes far beyond the schema's field descriptions.

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

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

The first sentence names a specific verb and resource: "Create a new email identity (mailbox address) on this openagent.email server." This is unambiguous and distinguishes it from siblings like mail_list_identities and mail_send.

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

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

The description gives clear usage context: admin keys create top-level identities, non-admin tokens need identities:create to mint child identities, and it explains default scoping behavior. It does not explicitly name when not to use it, but the context is strong enough to route an agent correctly.

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

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

Beyond annotations, the description discloses a critical behavioral contract: only source=internal may be trusted, external content must be treated as untrusted data, and non-internal values are wrapped in a per-call nonce fence. It also promises extraction of OTP codes and links, which annotations cannot convey. No contradiction with 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?

Three sentences with every sentence earning its place: purpose, trust boundary, and fencing behavior. The most important invocation-relevant info is front-loaded and the security caveat is succinctly stated.

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

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

Given readOnly/idempotent annotations and the presence of an output schema, the description covers the remaining critical context—content returned and trust/fencing behavior. An agent can select and invoke the tool correctly without missing information.

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 fully documents id and address. The description itself adds no parameter-level meaning, so the baseline 3 applies.

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

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

The description opens with a specific verb and object ('Read a full message') and enumerates the delivered content (text, html, extracted OTP codes, links). This clearly distinguishes it from list/wait/mark-seen 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 context that it reads full message content is implied, but the description never explicitly addresses when to choose this over siblings like mail_wait_for or mail_list_messages, nor does it state prerequisites such as obtaining an id from those tools (that is left to the schema). It provides no exclusions or alternative routing.

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

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

Annotations already communicate that this is a mutating, non-idempotent action (readOnlyHint=false, idempotentHint=false), and the description aligns with that. It adds the useful provenance constraint that the sender must come from mail_new_identity, which is behavioral guidance beyond the annotation flags.

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 convey the operation and the key precondition with no filler. Every sentence earns its place, and the most important constraint is front-loaded.

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

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

Given the 100% schema coverage, an output schema, and annotations that establish side effects, the description supplies the essential missing context: the sender must already exist as an identity from mail_new_identity. It does not discuss delivery semantics or errors, but that is not strictly necessary for selection and invocation of a well-schemaed send tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning to the 'from' parameter by specifying it must be an identity created with mail_new_identity, going slightly beyond the schema's own wording. Other parameters are already well described in the schema.

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

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

The description uses a specific verb and resource ('Send an email') and adds a critical precondition ('from must be an identity created with mail_new_identity'). This clearly distinguishes it from identity-creation and message-reading siblings in the tool list.

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

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

The description gives clear context: this tool sends mail only from an existing identity, and it names mail_new_identity as the required creation step. It does not explicitly state when not to use it relative to all mail sibling tools, but the prerequisite and verb make the intended usage unambiguous.

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

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

Beyond annotations (readOnly, openWorld), the description discloses detailed behavior: it skips already-seen matches, waits until timeout or new unread match, returns the full message with OTP codes/links or a timeout error, and provides critical security handling (only source=internal trusted, others fenced with nonce). This is rich behavioral context that goes far beyond what annotations provide, and there is no contradiction.

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

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

The description is dense but well-structured: it front-loads the core waiting behavior, then return type, then security. Each sentence provides essential information without fluff, though it is slightly long. The structure helps an agent parse quickly.

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

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

Given the tool's complexity (waiting, filtering, timeout, security) and that an output schema exists, the description covers all necessary aspects: what it waits for, how it handles seen matches, what it returns, and security constraints. An agent can invoke it correctly without missing information.

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 input schema has 100% description coverage for all four parameters, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already states (e.g., it mentions 'optional from/subject filters' but does not detail syntax or edge cases). The schema carries the heavy lifting.

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

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

The description states a specific verb ('wait for') and resource ('incoming message') with optional filters, and clearly distinguishes this from siblings like mail_list_messages and mail_read_message by focusing on the waiting action. 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?

The description explains when to use this tool: to wait for a new unread match, skipping already-seen ones in the newest-20 window. It implies usage for scenarios where polling or blocking is needed, but does not explicitly name alternatives or exclusion conditions. Still, the context is clear enough for an agent to select it appropriately.

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 non-read-only, so the mutation is known; the description adds value with the signing secret return behavior and the OAuth deny-by-default constraint. It does not describe all side effects, but openWorldHint and schema cover much of the remaining context.

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

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

Two tight sentences: the first states the core purpose, the second discloses output and access behavior. 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?

The schema and output schema cover parameters and returns, while the description adds the auth caveat and signing secret. It is sufficiently complete for an agent to invoke the tool correctly, though it could briefly note the admin-only preview restriction.

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 parameters are already fully documented. The description adds no parameter-level detail beyond that, which is acceptable given the baseline for full schema coverage.

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

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

States a specific action ('Create an outbound webhook subscription') with the resource type and unique return value (subscription metadata + signing secret). This clearly distinguishes it from sibling webhook tools like mail_webhook_list, mail_webhook_delete, and mail_webhook_test.

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 'Create' plus the tool name make the intended use obvious among the siblings. It also gives an important exclusion ('Deny-by-default for OAuth tokens'), though it does not explicitly name alternatives or contrast with other notification approaches.

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

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

Beyond the annotations (destructive=true, non-idempotent), the description discloses the cancellation of pending retries and the permanent nature of the action. This adds useful behavioral context not captured by the structured fields, while aligning with the destructiveHint.

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

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

The description is a single, front-loaded sentence that states the primary action first and then the additional effect. It contains no redundant words and conveys all essential information efficiently.

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 single-parameter destructive operation, the description covers the action, its permanence, and the associated effect on retries. Combined with the annotations and output schema, the agent has enough context to invoke the tool correctly.

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

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

The input schema fully documents the 'id' parameter with a clear description ('Webhook subscription ID (whk_...)'). The tool description adds no new parameter-level insights, so a baseline score of 3 is appropriate given the 100% schema coverage.

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

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

The description uses a specific verb ('delete') and resource ('outbound webhook subscription'), and adds distinctive consequences ('cancel any pending retries'). It clearly differentiates from sibling tools like mail_webhook_disable and mail_webhook_test by emphasizing permanence.

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 implies when to use the tool (when permanent deletion is needed) but does not explicitly contrast with alternatives such as disabling a webhook. There is no direct when-not-to-use guidance, but the 'permanently' wording provides an implied boundary against reversible disable operations.

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

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

The description aligns with the annotations: readOnlyHint=false confirms mutation, destructiveHint=false confirms this is not deletion, and idempotentHint=false is consistent with an 'active' precondition. It adds the specific state transition of marking the subscription disabled, which is useful context 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?

The description is a single sentence that front-loads the action and object, with no filler or redundant information. Every word contributes to understanding the tool's purpose.

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 one-parameter tool with an output schema and informative annotations, the description is mostly complete: it states the target, the action, and the state change. It does not mention how to re-enable the subscription or explicitly compare with deletion, but these are minor gaps given the sibling tool names and schema coverage.

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

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

The schema already covers the single parameter with 100% coverage, including the required id and the 'whk_...' format. The description does not add parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb, 'Pause', with a clear resource, 'active webhook subscription', and explains the mechanism, 'by marking it disabled.' This distinguishes it from the sibling tools mail_webhook_delete, mail_webhook_test, and mail_webhook_create.

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 implies the tool is for pausing an active webhook subscription, but it gives no explicit guidance on when to choose this over alternatives like mail_webhook_delete or how to resume the subscription. There are no exclusions or alternative recommendations, leaving usage context to inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds valuable behavioral context by explaining that identity callers only see their own subscriptions while admin callers can see all or filter by address, which is not captured in annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core action and then provides the most important scoping information, making it easy for an agent to parse quickly.

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 simple list operation with one optional parameter, a fully covered schema, an output schema for return values, and annotations covering side-effect behavior. The description fills in the important caller-scoping detail, leaving no critical gap for correct invocation.

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

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

The single optional address parameter is fully documented in the schema, including its admin-only nature. The description reinforces the filtering behavior but does not add new semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List outbound webhook subscriptions,' which clearly distinguishes this from sibling tools like mail_webhook_create, mail_webhook_delete, and mail_webhook_test. It also communicates the main scoping behavior, making the tool's purpose immediately understandable.

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 clearly indicates when the tool is appropriate: to list outbound webhook subscriptions, with context on identity versus admin caller behavior. It does not explicitly name alternatives or state when not to use it, but the sibling webhook tools are all different operations, so the usage context 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 already show this is non-read-only, non-idempotent, and non-destructive. The description adds that it is an immediate probe ping, which clarifies it triggers an active test rather than a read, but it does not detail external side effects or failure 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, making it easy to parse quickly.

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 operation with an output schema and safety-relevant annotations, the description is largely complete. The only missing context is explicit guidance on when to run a probe versus managing or inspecting subscriptions, which was already penalized in usage_guidelines.

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

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

The schema has 100% parameter description coverage: the single required 'id' parameter is documented with type, minLength, and the whk_... format. The description adds no parameter-specific meaning, so the baseline 3 applies.

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

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

The description uses a specific verb ('Send') and resource ('probe ping' for webhook connectivity), making the action clear. It is distinct from the CRUD-like sibling webhook tools even though it does not explicitly call out an alternative.

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

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

There is no explicit guidance about when to use this tool versus mail_webhook_list/create/delete/disable. The description only implies the tool is for verifying connectivity, leaving the selection condition 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 indicate a non-read-only, non-idempotent, non-destructive action. The description adds that 'The server owns topics and credentials,' hinting at authentication/ownership but not detailing side effects, failure modes, or rate limits. With annotations already covering the safety profile, the description provides minimal extra behavioral context.

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

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

The description is concise with three sentences, front-loading the core action and then adding address-format guidance. It is efficient with no redundant phrases. Slightly more detail on expected outcomes would not hurt, but the current length is appropriate for the tool's complexity.

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 tool has an output schema, so return value details are not required. However, the description does not mention potential errors, retry behavior, or what happens when the agent is not found. Given the five parameters and the non-trivial address semantics, a bit more context on usage conditions would improve completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the name parameter's dual format (full address vs bare localpart), but this is already documented in the schema's parameter description. No additional parameter semantics are added beyond what the schema provides.

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

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

The description clearly states a specific action ('Wake a named agent') and the resource (agent) via a server-side route. It is distinct from sibling tools like notify_user and notify_check, though it doesn't explicitly name alternatives. The verb 'wake' conveys a specific behavioral nuance.

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

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

The description provides guidance on address format (full identity vs bare localpart) and notes legacy compatibility, which is useful context. However, it does not explicitly state when to prefer this tool over notify_user or notify_check, leaving the agent to infer the differentiation based on the target type. No exclusions or alternatives are named.

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 operation as read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds valuable context about the server mapping the token to its own topic, which explains why no topic name or ntfy credential is exposed. This goes beyond the structured annotations and clarifies security-relevant 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?

The description is a single focused sentence that front-loads the core action and scope, then adds one crucial behavioral detail. Every word earns its place, with no redundancy or vague 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 simple read-only tool with one optional parameter, rich annotations, and an output schema available, this description is fully sufficient. It explains the identity scoping and the token-to-topic mapping, which are the only non-obvious aspects an agent would need to know to call the tool correctly.

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

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

The input schema has 100% coverage for its single optional parameter, including a description of 'since' as an optional ntfy duration or timestamp filter. The tool description itself adds no parameter-specific meaning, but the schema already carries the burden, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Read'), a clear resource ('recent notifications for this identity only'), and explicitly distinguishes itself from sibling notification tools by emphasizing the identity-scoped, token-mapped behavior. This makes the tool's purpose immediately 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 clearly implies this is for retrieving the current identity's notifications, but it does not explicitly state when to use this tool versus alternatives like notify_user, notify_agent, or notify_verify. There is no direct when-to-use/when-not-to-use guidance, though the identity-only scope provides some contextual direction.

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 indicate this is not read-only, not idempotent, and not destructive. The description adds useful context beyond annotations: the server-side grant requirement and the fact that no topic or ntfy credential is needed. It stops short of describing delivery guarantees or failure behavior, but the added context is meaningful given the annotation coverage.

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 concise sentences with no waste. The core action is front-loaded, and the only additional context is the auth grant and credential simplification. 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 relatively simple tool with 100% schema coverage and an output schema present, the description covers the essential action, prerequisite, and a clarifying simplification about credentials. It could explicitly mention the relationship to notify_agent or the behavior when the grant is missing, but the calling context 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?

The input schema has 100% description coverage for all four parameters, so the schema already explains title, message, tags, and level. The description adds no parameter-specific semantics beyond the overall notification action, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Send a human-alert notification.' The 'human-alert' qualifier distinguishes it from the sibling notify_agent, and the title/name align with the stated purpose. This is clear and non-tautological.

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 states an explicit prerequisite ('Identity tokens need the server-side can_notify_user grant') and an exclusion ('never needs a topic or ntfy credential'), which helps an agent understand when and how to use this tool. However, it does not explicitly name alternatives like notify_agent or state when to prefer this over them.

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 indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds useful behavioral context beyond this: the operation is harmless, runs server-side, and involves sending then polling back. It also discloses a permission requirement, which helps the agent anticipate invocation failures.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the permission caveat is placed in the second sentence. Every phrase 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?

Given zero parameters, an output schema, and annotations, the description covers enough to call the tool at a basic level. However, it leaves out practical guidance about how the check/poll behavior works in detail, what the output represents, and most importantly how this tool relates to notify_check. This is an adequate but not rich description.

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 input schema has zero parameters and the schema description coverage is 100%, so there is nothing for the description to add about parameter meaning. The description appropriately focuses on behavior rather than inventing parameter details.

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 action ('Send a harmless server-side notification check and poll it back') tied to the tool's name and title, so the core purpose is clear. However, it does not explicitly differentiate this from the sibling notify_check or notify_user, so it loses a point on sibling distinction.

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 only usage guidance is the permission prerequisite ('Requires the same human-alert permission as notify_user'), which is a constraint, not a selection rule. It does not say when to use this tool instead of notify_check, when not to use it, or what conditions warrant verification.

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

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

With annotations present (readOnlyHint=false, idempotentHint=false), the description still adds meaningful behavioral detail: the 24-hour per-generation cap, the seven-day no-claim/renew boundary, and the receipt requirement for reclaim. It does not contradict the annotations, and it provides more lifecycle context than the structured fields alone.

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

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

The description is front-loaded with the primary purpose and packs the constraints into two sentences without filler. It loses a point because the second sentence is dense and uses undefined terms like 'generation' and 'lease receipt', which reduces readability even though 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 two-parameter tool with a full input schema and an output schema, the description covers the core behavior, the lease window, and the reclaim precondition. It is slightly incomplete about what happens when a claim fails (e.g., already held lease) or how the authenticated receipt is supplied to the API, but the essentials are present.

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

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

Schema description coverage is 100% and both id and leaseSec already have descriptive text, so the baseline applies. The description's lease/reclaim context loosely reinforces the meaning of leaseSec but does not add parameter-level detail beyond the schema.

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

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

The first sentence uses a concrete verb ('Claim') and a resource ('a submitted task') plus the bounded-lease framing, which makes the core action identifiable and separates it from lifecycle siblings like task_renew and task_release. It is not a 5 because the domain terms 'managed recipient' and 'generation' are left undefined, and no sibling is explicitly named for contrast.

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

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

The description gives clear usage constraints: leases are bounded, capped at 24 hours, and barred after seven days from first claim, and it states the precondition that a working task may be reclaimed only with an authenticated expired or released lease receipt. It does not explicitly say when to prefer task_renew or task_release instead, so it falls short of explicit when/when-not guidance.

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

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

The description goes well beyond annotations: it discloses side effects (creating a stamped email thread, waking the agent route), strict validation limits (65,536 bytes, depth 10, 30-day expiry), stable client error names, and wait semantics. None of this contradicts the annotations; it meaningfully enriches them.

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

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

The description is front-loaded with the core purpose, then progressively details constraints and wait behavior. Every sentence earns its place; there is no filler or repetition of schema content. Despite its density, the structure is logical and scannable.

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

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

Given the tool's complexity, the description covers the essential behavioral context: creation side effects, approval validation constraints, error conditions, and polling guidance. An output schema exists and carries the parameter-level details, so the description need not restate them. The only marginal omission is explicit guidance on parentTaskId, but the schema already documents that field.

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?

Even with 86% schema coverage, the description adds significant parameter-level meaning not present in the schema: the JSON-only approval constraints, byte/depth/expiry limits, stable error names for approval_action_too_large/too_deep/expiry_too_far, and the exact behavior of wait=true. This is substantial semantic value beyond the structured schema.

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

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

The description opens with a specific verb and resource: 'Assign a task to another managed identity.' It then clarifies the mechanics (stamped email thread, waking the agent route), which clearly distinguishes it from sibling task tools like task_get, task_update, and task_decide. An agent can immediately tell this is the creation operation.

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

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

The description makes the primary use case clear and gives concrete guidance for wait behavior: with wait=true it waits up to MCP_MAX_WAIT_SECONDS, and for longer work the agent should call task_get again. It does not explicitly name exclusions or contrast with task_update/task_decide, but the creation context is unmistakable and the polling fallback is a valuable 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?

The annotations already declare this is not read-only and not destructive, but the description adds an important behavioral boundary: 'it never executes the action' and records only the decision. It also clarifies that the decision is made 'as the identity bound to this MCP token', which is meaningful side-effect and authorization context beyond the structured annotations.

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

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

The description is two sentences, front-loads the verb and object, and uses a second sentence only for a crucial behavioral caveat. There is no redundant or filler content.

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

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

The tool is simple with two required parameters, an output schema, and annotations that cover mutability and destructiveness. The description provides the key additional context about identity and non-execution. It does not mention prerequisites like task ownership or claim state, but the low complexity and existing structured schema make this a minor 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 50%: the id parameter is described, and the decision parameter is represented by an enum with approved/rejected. The description's 'Approve or reject' maps naturally to the decision values, but it does not elaborate on the parameters themselves or add meaning beyond what the schema already exposes.

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 an explicit verb 'Approve or reject' with the resource 'approval task', so an agent knows the exact operation. It also distinguishes this from executing the action by saying 'records a decision only; it never executes the action', which makes the purpose unambiguous and distinct from execution-like 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?

The intended use case is implied: call this when an approval task needs an approve/reject decision as the token-bound identity. However, it does not explicitly state when not to use it or name alternative tools such as task_update or task_claim, so guidance on selection among siblings is indirect.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to restate that. It adds useful behavioral context by mentioning that the result includes server-stamped state history and by disclosing the edge case where a durable lease retained while leases are disabled surfaces as 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?

The description is two sentences with no filler. The primary purpose is front-loaded, and the second sentence adds a narrowly useful behavioral detail without bloating the definition.

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

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

For a simple read tool with only two parameters, both fully described in the schema, rich annotations, and an output schema, the description is sufficiently complete. It adds the state-history and lease-visible details that structured fields do not convey, and nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both id and wait having meaningful descriptions, so the description does not need to add parameter-level detail. The description contributes no extra parameter semantics, which aligns with the baseline score for fully documented schemas.

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

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

The description opens with the verb 'Read' and a specific resource: 'one task thread and its server-stamped state history.' This clearly distinguishes task_get from sibling list/creation/update tools such as task_list and task_update, even without naming 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?

The description clearly implies this tool is for retrieving a single task's current state and history, rather than listing tasks or mutating them. It does not explicitly name alternatives or state when not to use it, but the singular 'one task thread' plus the sibling context makes the appropriate use case clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds a valuable edge case: a durable lease retained while leases are disabled surfaces as leaseStatus=disabled. This goes beyond the structured annotations, though it does not detail pagination or ordering.

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 with no filler: the first states the core purpose and filter, and the second adds a focused lease-status edge case. It is compact and front-loaded.

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

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

With one optional parameter, full schema coverage, and an output schema, the description covers the essential call decision. The lease-status note adds completeness for a special case; sibling routing could be more explicit but is inferable.

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 state parameter is already described as 'Optional current state filter'. The description only repeats this concept, so it adds little beyond the schema, which is acceptable at 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?

The description states a specific action (List), a specific resource (this identity's email-backed tasks), and an optional filter (current state). This clearly distinguishes it from sibling task_list_children and task_get.

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

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

It clearly establishes that the tool applies to the current identity's email-backed tasks and notes the optional state filter. However, it does not explicitly contrast with sibling tools like task_get or task_list_children, leaving the routing decision partly implicit.

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

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

Beyond annotations, the description reveals important behaviors: results are viewer-filtered before paging, and the response contains no totals or descendants. It also establishes a readability precondition for the parent. This adds meaningful context beyond the readOnly/idempotent hints.

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

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

The description is two short sentences with no filler. It front-loads the core purpose and packs essential behavioral boundaries into the second sentence. Every word 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?

Given the annotations, output schema, and simple parameter list, the description adequately covers the operation's safety profile and listing behavior. A small gap is the lack of explicit sorting or cursor-termination semantics, but overall the tool is sufficiently specified for correct invocation.

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

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

Schema description coverage is only 33%, and the description does little to clarify limit or cursor semantics. It only reinforces that the parent must be readable. The pagination behavior is hinted at ('before paging') but not explained in terms of cursor usage or limit effects.

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

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

The description clearly states the specific action: listing only direct readable children of a readable parent. It also distinguishes this tool from broader task listing by emphasizing 'only direct' and 'no descendants', so an agent can tell it apart from related task 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?

The description gives clear context: use this when you need direct children of a readable parent, not a full descendant tree, and when viewer-filtered results are acceptable. It does not explicitly name alternative tools like task_list or task_get, but the scope is clear enough to infer appropriate use.

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 indicate a non-read-only, non-idempotent mutation, so the description only needs to add context. It adds that a current active token is required, but does not disclose effects such as token invalidation or the lease becoming available to other agents. This is acceptable but not rich.

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 tightly worded sentence; the core action and key precondition are front-loaded. There is no filler, repetition, or unnecessary schema restatement.

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 three-parameter tool with a full input schema and output schema present, the description is nearly sufficient for correct invocation. It lacks explicit when-to-use guidance versus claim/renew, but the tool name and sibling set make the intended context reasonably clear.

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 id, reason, and leaseToken are already documented. The description's mention of 'current active opaque lease token' mostly restates the leaseToken schema rather than adding new semantic detail beyond the precondition.

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 ('release') and resource ('task lease'), and adds the token requirement. It is clearly distinct from sibling operations like task_claim, task_renew, and task_update without needing to open 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?

The description gives a precondition ('only with its current active opaque lease token') but does not say when to use this tool versus alternatives. There is no guidance such as 'use after you are done with a claimed lease' or 'use task_renew to extend a lease instead.'

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

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

The description adds behavioral context beyond the annotations by disclosing that renewal never resets the generation's 24-hour cap or the task's first-claim seven-day cap, and that equality is rejected. This is useful side-effect information not available from readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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 focused sentences. The first sentence states purpose and precondition, and the second captures important behavioral constraints. There is no filler or redundant restatement of schema fields.

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

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

Given the annotations, full schema coverage, and presence of an output schema, the description provides sufficient context for an agent to call the tool correctly. It explains the core precondition and the behavioral invariants. A minor gap is that domain terms like 'generation' and 'equality is rejected' could be more explicit, but the overall meaning is recoverable.

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 input schema already provides 100% description coverage for all parameters, including leaseToken as an opaque current lease token and leaseSec with range and default. The description adds no new parameter-level detail beyond reinforcing that the token must be current and active.

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

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

The description clearly identifies a specific operation: renewing a task lease, and states the key precondition (current active opaque lease token). It distinguishes the tool from related lease operations like task_claim or task_release by focusing on renewal semantics, but it does not explicitly name or contrast 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?

The description implies when to use the tool: only when you already have the current active opaque lease token and want to renew without resetting caps. However, it does not explicitly state when not to use it or mention alternatives such as task_claim for a new lease or task_release to end the lease.

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

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

The description goes well beyond the readOnlyHint and idempotentHint annotations: it discloses that the API stamps the state header, that completed and failed are terminal, and how lease-token omission or mismatch changes the result. It also explains where the server places result data. No contradiction with 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?

Three information-dense sentences with no filler and the core action front-loaded. The lease-token sentence is compact but slightly hard to parse, keeping it from a perfect structure score.

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 stateful update tool, the description covers the state machine's terminal behavior, lease-token consequences, and result placement, and an output schema exists for return details. It stops short of defining 'active recipient lease' or permitted state transitions, but the sibling lease tools and schema cover most of the surrounding context.

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

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

Even though the schema describes all parameters, the description adds meaningful runtime semantics: result is written as a JSON block, state has terminal values, and leaseToken has specific error behavior. This is exactly the kind of value the schema alone cannot provide.

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

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

The opening phrase 'Advance a task as one of its two participants' gives a specific verb and resource and indicates the tool's role is progression, not creation or lease management. It is clear, though it does not explicitly name sibling tools like task_decide or task_claim to differentiate from 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?

The participant framing and lease-token guidance imply when this tool is appropriate, but there is no explicit 'use when' or 'use X instead' guidance. An agent must infer the boundary between task_update and sibling tools such as task_decide or task_claim.

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