PingRoom

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

The annotations already mark this as non-read-only, non-idempotent, and destructive; the description adds meaningful behavior beyond that, such as the activation_completed true success signal, the stop-polling-on-terminal-result rule, and the one-retry policy. It does not contradict the annotations, though it leaves the concrete destructive effect unnamed.

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

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

Five dense sentences front-load the purpose and then flow through the wait, success, retry, and stamp-precondition steps. The phrasing is economical, though 'stamp' and 'one numbered retry' are jargon that cost some clarity.

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

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

For a zero-parameter orchestration tool, the description covers the core invocation and error-handling loop, and an output schema supplies return-value detail. The main gaps are the unexplained 'stamp' prerequisite and the unspecified 'bounded local deadline', but the agent still has enough to proceed with the retry and wait_for_handoff flow.

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 zero parameters and 100% schema coverage, there is no schema burden, so the description is the only source of input semantics. It tells the agent to read question.id from prior context, which is the relevant input source despite the empty 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?

Opens with the specific action 'Start or resume the onboarding Question' in the private room chosen during authorization, making the verb, resource, and context explicit. It also positions itself relative to wait_for_handoff by instructing when to delegate to that sibling, which helps disambiguate it from nearby question/handoff 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?

Explicitly sequences usage: read question.id, call wait_for_handoff only while state is pending and before a bounded local deadline. It also defines the retry path—calling activate_agent_inbox again for one numbered retry—so the agent knows exactly when and how to reuse the 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 communicate mutating/destructive and non-idempotent behavior, so the description carries a lower burden. It adds useful behavioral detail: delivery as a push answerable from lock screen/in-app, first-valid-answer-wins semantics, rate limiting, and the expectation of blocking. Minor ambiguity remains over whether ask_question itself blocks or only when paired with wait_for_answer, but there is no contradiction with the annotations.

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

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

Three sentences, front-loaded with the core action, and no filler. Each sentence contributes distinct value: the pairing flow, the delivery UX and answer rule, and the rate-limit warning.

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 complex 11-parameter schema and the presence of an output schema, the description adequately covers integration context: pairing, push delivery, answer resolution, and rate limiting. It does not mention ttl expiration or the default Approve/Deny option behavior, but those are discoverable from the schema and are low-risk omissions.

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% with every parameter already described, so the baseline is 3. The description only restates the options bounds ('2-4 tappable options') and does not add new meaning for parameters like prompt, invite_code, or text_input; the schema remains the primary source of parameter semantics.

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

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

The description opens with a specific verb and resource ('Ask a person a question'), immediately distinguishing this from related sibling tools like request_approval or broadcast. Mentioning '2-4 tappable options' and pairing with wait_for_answer makes the tool's unique role unmistakable.

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 explicit instruction 'pair with wait_for_answer' gives clear usage context and tells the agent this is the initiating half of a paired flow. It does not list exclusions or when-not-to-use alternatives, but the paired-flow framing is enough for correct selection.

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 establish that this is not read-only, is not idempotent, and has side effects. The description adds two useful behavioral constraints beyond annotations: it is rate-limited, and it is unavailable in personal rooms. It does not fully narrate consequences of the side effect, but the schema and 'Send' make the basic effect clear.

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 short sentences with no filler. It front-loads the core purpose, then adds the two most operationally relevant constraints: rate limiting and the personal-room exclusion. Every sentence 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 large schema (12 parameters, nested objects, full descriptions), an output schema, and annotations covering read/write/idempotency/destructive traits, the description covers the selection-level context an agent needs. It provides the critical personal-room limitation and alternative. It could say slightly more about what a ping visibly does to recipients, but this is not essential.

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 parameter descriptions are rich, so the schema carries the parameter-meaning burden. The tool description does not add parameter semantics of its own, which is acceptable at the baseline of 3. No gap in parameter understanding remains.

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 ('Send'), a specific resource ('a custom ping to a room the account belongs to'), and a clear scope. It also differentiates from the sibling trigger_quick_action by explicitly noting it does not apply to personal rooms. This gives an agent enough to know exactly what the tool does.

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 explicitly says when the tool is not usable ('Not available in personal rooms') and names the alternative to use there ('use trigger_quick_action there'). It also flags that it is rate-limited, which is important operational guidance. This is exemplary routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful context beyond the annotations by specifying the operation is limited to 'still-pending' questions and only ones 'you asked.' No contradiction exists.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds meaning, and the key constraint ('still-pending'), actor ('you'), and action ('withdraw') are immediately visible.

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 required parameter, rich annotations, and an output schema present, the description is sufficient for an agent to correctly understand and invoke the tool. No critical operational context is missing.

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

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

Schema description coverage is 100% and there is a single UUID parameter. The description adds no new parameter-specific guidance, but the schema already carries the necessary meaning, 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 ('withdraw') with a clear resource ('still-pending question') and a scope ('you asked'). This clearly distinguishes the tool from siblings like ask_question, get_question, and wait_for_answer.

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 conveys that the tool applies only to pending questions the caller asked. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion 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 discloses a meaningful precondition: 'The server verifies that one of the recipient's current devices supports the complete Handoff action before creating anything,' which also implies no partial creation. It does not detail auth requirements or failure modes, but with readOnlyHint and destructiveHint already present, the added device-support guarantee earns credit.

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, no filler; the core purpose is front-loaded and the behavioral caveat is appended in the second sentence. Every phrase contributes.

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

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

For a 10-parameter tool with nested objects and an output schema, the description is lean but adequate: it states scope, kinds, and a key server-side check, while optional fields and return values are covered by the rich schema and output schema. It could be more complete by addressing when to prefer a sibling tool, but that gap was already captured under 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?

With schema description coverage at 90%, the schema already documents most parameters, so the baseline is 3. The description adds no parameter-specific semantics beyond the ack/question distinction that mirrors the kind enum.

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

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

The opening sentence names a concrete action and scope: 'Hand work to exactly one human as either an acknowledgement or a tappable question.' This distinguishes it from broadcast-style tools and specifies the two handoff kinds, but it never names the closely related sibling ask_question, so differentiation is implicit rather than explicit.

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 delegating a single acknowledgement/decision to one human, which is usable context. It gives no when-to-use or when-not-to-use guidance and cites no alternative tools, so an agent must infer selection from the sibling list.

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 convey mutation and non-idempotence, and the description adds a meaningful side effect: counting toward the free-plan five-room cap. It also reinforces the uniqueness requirement for the @handle, adding value beyond the annotation 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?

Two tight sentences with no filler. The core purpose is front-loaded and the quota caveat is stated second, making it easy to scan.

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

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

Given full schema coverage, an output schema, and annotations, this description is sufficient for selecting and invoking the tool. The main missing element is any alternative/fallback guidance, but that is already covered under 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?

Schema description coverage is 100%, so the baseline applies. The description mentions the unique @handle, aligning with the handle parameter, but provides no additional 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 description uses a specific verb ('Create') and resource ('publicly discoverable room') and adds the unique @handle criterion. This clearly differentiates it from the sibling create_room by emphasizing public discoverability.

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 guidance about when to prefer this tool over create_room or other room-related siblings. The only contextual note is the free-plan cap, which is a constraint rather than a usage directive.

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 indicate a mutating, non-idempotent operation. The description adds meaningful behavioral context beyond that: ownership by the authenticated account, the five-room limit for free accounts, and the delivery-room side effect. These are important consequences an agent should know before calling the tool.

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

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

The description is compact and well-structured: first the core action, then the quota constraint, then the special delivery-room side effect. Each sentence earns its place and no filler or repetition exists.

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

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

The description covers the essential operational context: ownership, quota, and the delivery-room side effect. It does not state what happens when the five-room limit is reached or explicitly compare with create_public_room, but the output schema exists and the parameters are fully documented, so the definition is largely complete 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 100%, and all three parameters (name, icon, color) are already documented in the schema. The description does not add additional parameter-level guidance, 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 opens with a specific verb and resource: 'Create a new private room owned by the authenticated account.' It clearly differentiates from the sibling create_public_room by specifying 'private', and it states the ownership model, so an agent can understand exactly what this tool does.

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 useful context about when the tool is relevant, such as free-account room limits and the delivery-room behavior, but it does not explicitly state when to prefer create_public_room or when not to use this tool. The 'private' qualifier implies the distinction, but the guidance is not made explicit.

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

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

Beyond the annotations, the description discloses that the response returns a secret trigger URL and instructs the agent to treat it as a credential. It also states the Pro-account prerequisite and ownership constraint. This adds meaningful behavioral context even though idempotency and destructive effects are already covered by 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 focused sentences front-load the action and scope, then add the key prerequisite and the security-relevant return value. Every sentence earns its place with 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?

Given the rich schema (100% parameter coverage) and existing output schema, the description supplies exactly the missing external context: room ownership, the Pro requirement, and the credential-like nature of the returned URL. Nothing an agent needs to invoke this correctly is omitted.

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 input schema already fully documents all 10 parameters. The description itself adds no parameter-level detail, which matches the baseline for fully covered 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 uses a specific verb and resource: 'Create an incoming webhook for a room the account owns.' It clearly distinguishes this from sibling tools like update_webhook, delete_webhook, and list_webhooks by stating exactly what creation entails. The mention of returning a secret trigger URL further reinforces the specific purpose.

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

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

The description gives clear context for when to use the tool: creating a webhook for an owned room, and only when the bound account is Pro. It does not explicitly name alternatives such as update_webhook for modifying existing webhooks, but the ownership and Pro prerequisites provide sufficient usage boundaries.

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 convey destructiveness and non-read-only behavior. The description goes beyond them by adding an ownership requirement and a lifecycle condition ('not yet claimed by a ping'), which clarifies when deletion is valid. This is useful context that is not present in 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 a single sentence, front-loads the action ('Delete an attachment'), and then states the two necessary constraints. There is no filler or redundant restating of the title.

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 destructive operation with a well-documented schema, an output schema, and informative annotations, the description fully covers the relevant invocation context. Nothing an agent needs to decide whether to call this tool is missing.

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

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

The schema already fully documents attachment_id as a UUID returned by upload_attachment, so schema coverage is 100%. The description adds no additional parameter-level meaning beyond what the schema provides, which matches 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 names a specific action ('Delete') and a resource ('attachment'), and adds two precise scope constraints: it must be an attachment this agent uploaded and one not yet claimed by a ping. This clearly differentiates it from siblings like upload_attachment and get_attachment.

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 conditions for use: only delete attachments the agent uploaded and that are not yet claimed by a ping. It does not explicitly name alternatives or say when not to use the tool, but the constraints strongly imply the appropriate invocation context.

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

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

Annotations already mark this as destructive and idempotent; the description adds the ownership requirement and clarifies the target ('incoming webhook, by id'). It does not contradict the annotations and provides context beyond 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?

One compact sentence with all essential information front-loaded. 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?

For a two-parameter delete operation with rich annotations and an output schema, the description covers the object, ownership condition, and identifier. Nothing essential to invoking 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 parameters are already documented. The description reinforces webhook_id as the identifier and invite_code as the room, but adds no format or syntax detail beyond the schema.

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

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

States a specific action (delete), resource (incoming webhook), identifier mechanism (by id), and scope constraint (room the account owns). This distinguishes it from sibling create_webhook, update_webhook, and list_webhooks.

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 basic use case clear—deleting a webhook by id—and adds an ownership condition. It does not explicitly mention alternatives or when not to use it, leaving the usage guidance 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the non-blocking behavior, which is useful, but no additional side-effect or error context is provided.

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 sentence that front-loads the action, resource, and key behavioral nuance with 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?

For a single-parameter read-only fetch with an output schema and strong annotations, the description is nearly complete. The only minor gap is not explicitly routing to wait_for_approval when blocking 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?

The input schema already documents approval_id as a required UUID with the description 'Approval request id.' With 100% schema coverage, the tool description 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?

States a specific action (fetch), a specific resource (approval request), and a scoping detail (current status) plus the non-blocking behavior. This clearly distinguishes it from sibling wait_for_approval.

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 'without blocking' gives clear context for choosing this over a blocking wait variant, and siblings include request_approval and wait_for_approval to make the contrast. It does not explicitly name alternatives or exclusions, but the context is enough for a simple read tool.

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

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

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description adds meaningful behavioral context: the visibility restriction, the base64 encoding of content, and the specific error/fallback behavior for oversized results. No contradiction with annotations exists.

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

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

Two concise sentences with no filler. The action and key output detail are front-loaded, and the error/fallback guidance is placed second. 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 simple one-parameter, read-only tool with a full output schema and comprehensive annotations, the description covers the essential behavioral details: scope, output encoding, error condition, and fallback path. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the single attachment_id parameter is already fully documented in the schema, including its UUID format and source (upload_attachment). The description doesn't need to 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 states a specific verb ('Fetch') and resource ('an attachment visible to this agent'), and clarifies the output format ('base64 content plus metadata'). This clearly distinguishes it from sibling tools like upload_attachment and delete_attachment by focusing on the retrieval 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 explicitly provides a when-not-to-use condition: results over the connector size limit return attachment_too_large and should instead be fetched via the agent REST API. This gives the agent a clear routing decision without ambiguity.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: the operation is non-blocking and returns the authoritative current state, which are useful behavioral traits for tool selection.

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 or redundant content. Every word contributes meaning.

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

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

The tool is simple: one required parameter, rich annotations, and an output schema. The description clearly states that it fetches one handoff's state without blocking, which is sufficient 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 100% and the single parameter handoff_id is documented as 'Handoff id.' The description does not add additional parameter detail, so it neither helps nor harms 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?

Description uses specific verb 'Fetch' and resource 'one Handoff', and clarifies it returns the authoritative current state. This distinguishes it from siblings like list_handoffs (plural), wait_for_handoff (blocking), and create_handoff (creation).

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 'without blocking' and 'authoritative current state' clearly position this as the synchronous read tool, contrasting with wait_for_handoff. It does not explicitly name alternatives, but the context is strong enough for an agent 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 mark it readOnly and idempotent, and the description adds valuable details beyond that: it returns specific fields, mentions that unset fields come back as null (not omitted), and explains why that matters for resuming content. This fully discloses the behavior and is consistent with the annotations.

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

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

The description is somewhat long due to the necessary enumeration of return fields, but it is front-loaded with purpose and then structured logically. The detail is warranted for the complex output; it could be tightened but is not bloated.

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

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

For a read-only reconciliation tool, the description covers all essential context: the triggering use case, the temporal/credential scope, the exact return shape (even though an output schema exists), and the null-handling behavior. An agent knows exactly what to expect and how to use it.

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

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

Schema coverage is 100% for both parameters (invite_code and correlation_id), each with a brief description. The tool description does not add any additional semantics beyond what the schema provides — it only repeats 'stream key' for correlation_id. Thus 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 uses a specific verb ('Read back'), a specific resource ('current state of a live stream you created'), and explains the purpose ('so a restarted producer can reconcile instead of starting a duplicate'). This distinguishes it from the sibling 'live_status' by scoping to streams 'created by this credential' within a 24-hour window, making the tool's role clear.

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

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

It gives a clear usage context: for a restarted producer to reconcile against its own stream, and it defines a strict scope (only this credential, last 24 hours). However, it does not explicitly mention when not to use it or name an alternative tool (e.g., 'use live_status for stream status outside this scope'), so a small gap remains.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about visibility filtering and the current action_state field, but does not disclose behavior such as what happens when the id is not visible or not found.

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

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

The description is a single, dense sentence with no filler. The key information—resource, identifier, visibility constraint, and returned field—is front-loaded and 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 one well-documented parameter, strong safety annotations, and an output schema, this description is largely sufficient. The only slight gap is that 'visible' is not defined further, but this is minor for selecting and invoking the 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?

The input schema covers the single parameter notification_id with 100% schema description coverage, including format and explanation. The description's 'by notification id' phrase adds no additional semantic value beyond the schema.

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

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

The description uses a specific verb ('Fetch') and resource ('one visible ping by notification id'), and notes that the response includes the current action_state. This clearly distinguishes it from list-style siblings like list_notifications and from wait_for_notification.

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 usage context clear: call it when you have a notification id and need exactly one visible ping's current state. It does not explicitly exclude or compare against siblings, but the single-item-by-id framing is enough to guide correct selection in most cases.

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 provide readOnly, idempotent, and non-destructive hints, so the description's main added value is the 'without blocking' behavior, which is not conveyed by any annotation. It also implies snapshot semantics via 'current state', offering context beyond the structured fields.

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

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

A single, well-constructed sentence contains all essential information with no filler. The verb, resource, scope, and behavioral qualifier are all front-loaded, making it immediately scannable for an agent.

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 (one required parameter, no nested objects), the presence of an output schema, and rich annotations covering safety, the description is sufficient for correct invocation. It clearly communicates the non-blocking nature and the target resource without needing to explain return structures.

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 sole parameter 'question_id' is described as 'Question id.', so the schema carries the full semantic burden. The description adds no further parameter-level detail beyond aligning with the question resource, making the baseline 3 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 clearly states a specific verb ('Fetch'), a resource ('question'), and the exact scope ('current state') while distinguishing itself from sibling tools like wait_for_answer via 'without blocking'. It is concise and leaves no ambiguity about what operation is performed.

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 'without blocking' implies the tool is appropriate when a non-blocking fetch is desired, contrasting with wait_for_answer. However, it does not explicitly name alternatives or state when not to use this tool, leaving the agent to infer the usage context from sibling names.

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 read-only, idempotent, and non-destructive, so the description's safety burden is low. It adds useful behavioral context by specifying that the response includes members and quick actions, which is beyond what the input schema provides. It does not contradict any annotation.

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

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

The description is a single, efficient sentence that front-loads the core operation and then adds the relevant scope of returned data. Every word earns its place; there is no redundancy or 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 lookup with one fully documented parameter, an output schema, and safety annotations, the description provides everything an agent needs to invoke the tool correctly. No missing prerequisites, side effects, or return-format details are required for this level of complexity.

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 parameter 'invite_code' is already fully documented in the schema as 'Room invite code.' The description echoes that it fetches by invite code but adds no extra semantic detail such as format, length, or example values. Baseline 3 is appropriate because schema coverage is 100%.

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 ('Fetch'), names the resource ('a single room'), and identifies the exact lookup key ('invite code'). It also clarifies scope ('single room') and includes expected contents ('including members and quick actions'), making it clearly distinct from sibling tools like list_rooms and create_room.

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 this tool is for retrieving one specific room rather than listing all rooms, but it does not explicitly state when to prefer it over alternatives such as list_rooms or get_live_status. The intended use is reasonably inferable, but no explicit routing guidance is 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 mark the operation as non-read-only and destructive, so the safety profile is covered. The description adds the password condition but no additional behavioral context such as membership side effects or failure modes; still, it does not contradict 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?

Two short sentences, front-loaded with the core action and follow-up with the conditional parameter rule. No filler.

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

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

For a low-complexity join operation with only two parameters and an output schema, the description plus annotations cover the essential conditions: what to supply, when the password is needed, and the operation's side-effect profile.

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 invite_code and password are already documented. The description reinforces the password rule, but 'only if protected' largely restates the schema's own 'only required for password-protected rooms,' adding only marginal guidance.

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

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

States a clear action and target: 'Join a room using its invite code.' It names the mechanism (invite code) and implies an existing room, which separates it from create_room, but it does not explicitly distinguish itself from siblings such as get_room or list_rooms.

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

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

Provides the central prerequisite (invite code) and an explicit conditional rule for when the password should be included ('only if the room is protected'). It does not name alternatives or state exclusions, but the join-vs-create context is clear enough for an agent to route 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond the annotations: results are bounded, paginated, newest-first, scoped to this agent, and include a has_more signal for continued pagination. This meaningfully enriches the structured annotation data without contradicting it.

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 action, scope, ordering, and pagination behavior without redundancy. Every clause earns its place, and no structured information is needlessly repeated.

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 full schema coverage, rich annotations, and an output schema, the description supplies the remaining practical context: bounded pages, newest-first ordering, this agent's scope, and state-filtering semantics. An agent has enough information 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 schema already covers 100% of parameters, so baseline is 3. The description adds value beyond the schema by explaining the semantic intent of 'state' (omit/open for unresolved work vs. 'all' for history) and by linking 'page' to the has_more pagination pattern. This helps an agent choose parameter values correctly.

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, resource, and scope: it 'List[s] a bounded page of this agent's Handoffs, newest first.' It clearly differentiates from sibling get_handoff by addressing paged listing of all handoffs rather than fetching a single handoff.

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 concrete guidance on when to use different state values: omit state or use 'open' for unresolved work, and use 'all' for history. It also explains pagination with has_more. It does not explicitly name alternative sibling tools or exclusion conditions, but the provided usage context is clear and actionable.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by noting the result is bounded, paginated, filtered to approved rooms, and ordered newest-first. This goes beyond the structured annotations without contradicting 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?

Two short sentences, front-loaded with the core action, and every phrase earns its place. The pagination hint is compact and directly actionable.

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 robust annotations, an output schema, and full schema parameter coverage, the description is largely complete. It could clarify what 'pings' means relative to notifications, but this is minor given the title and existing schema.

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 documents all parameters well. The description adds extra semantic value for the page parameter by explaining the pagination loop with has_more, which is not 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 clearly states a specific verb ('List') and resource ('a bounded page of recent pings across approved rooms'), plus the ordering ('newest first'). It does not explicitly distinguish itself from get_notification, but the list-vs-single contrast is reasonably clear from the names and description.

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 operational guidance: this is a paginated list operation and the agent should use the page parameter while has_more is true. It does not mention alternatives or when to prefer get_notification, but the usage context is specific enough for correct invocation.

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, and the description adds useful context: this lists the caller's own questions, is bounded, and is newest-first. The has_more hint also clarifies pagination 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?

A single sentence conveys the action, scope, ordering, optional filter, and pagination strategy. Every clause earns its place and 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?

For a simple read-only listing tool with full schema coverage, annotations, and an output schema, the description covers the essential usage details: scope, ordering, filtering, and pagination. 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 description coverage is 100%, so the baseline is 3. The description adds value by connecting page usage to the has_more flag and clarifying the 'you asked' scope, which is not explicit in the input 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 ('List ... questions you asked') with ordering ('newest first') and the optional state filter. It is clearly distinct from the singular get_question sibling.

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

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

Provides clear pagination guidance ('use page while has_more is true') and mentions the optional state filter. It does not explicitly contrast with alternatives like get_question, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no further behavioral nuance such as authentication, failure modes, or effects, but it does not contradict 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?

One front-loaded sentence that names the action and scope with no filler. It is compact while conveying the essential operation.

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 read-only tool, the description plus schema and annotations is complete: the parameter is documented, safety is declared, and an output schema exists so return format does not need to be described. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%: invite_code is already described as 'Room invite code' and marked required. The description's phrase 'for a room' loosely reinforces this parameter but adds no additional semantic 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?

Description uses specific verb 'List' and names the resource 'quick actions configured for a room', making the read operation clear. The word 'configured' positions it as inspection rather than trigger/update, distinguishing it from siblings like trigger_quick_action and update_quick_action.

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

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

The description clearly implies when to use it: when the agent needs the set of quick actions defined for a given room. It does not explicitly discuss alternatives or exclusions, but no competing list tool exists and trigger/update siblings are clearly different 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds context about the catalog's contents and purpose, which is useful but does not add behavioral details such as whether results are sorted, cached, or paginated. Given the strong annotation coverage, the description meets the minimum bar without contradicting anything.

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, tight sentence with no filler. It front-loads the action and resource, then immediately explains the purpose. Every element contributes value.

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

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

Given the tool has no parameters, an output schema, and annotations that fully cover safety and idempotency, the description is complete for the agent's ability to invoke the tool and use its results. It states what the catalog contains and why the agent would need 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?

The tool has zero parameters, so parameter-level semantic guidance is not needed. The baseline is 4 for parameterless tools, and the description's clarification of what the catalog includes ('icon ids, tags, and categories') still provides useful context for interpreting the response.

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 a clear resource ('room-icon catalog'), and goes further to explain that it contains icon ids, tags, and categories. The stated purpose—interpreting icon values from room and quick-action reads—distinguishes it from sibling list tools such as list_rooms and list_quick_actions.

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 signals when this tool is appropriate: when an agent needs to interpret icon values returned by room or quick-action reads. It does not explicitly name alternatives or state when not to use it, but the use case is specific enough that an agent can infer the selection criteria.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the contextual detail that results are limited to rooms the authenticated account belongs to, which is useful but not a deep behavioral disclosure. 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?

A single, tightly written sentence contains the verb, resource, and scope with no filler. It is front-loaded and 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?

For a parameterless read-only list operation with a rich set of annotations and an output schema present, the description provides everything needed to select and invoke the tool 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, so the input schema is already complete. The description does not need to explain parameter semantics, and the baseline of 4 applies because there is nothing for the description to add.

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 a specific resource ('rooms the authenticated account belongs to'), clearly distinguishing this from get_room, create_room, join_room, and list_room_icons. The scope is precise: it retrieves room memberships for the authenticated account, not arbitrary rooms.

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 when this tool should be used: when the agent needs the rooms associated with the authenticated account. It stops short of explicitly naming alternatives or excluding cases like single-room lookup or creating rooms, but the membership scope provides useful guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is covered. The description adds a small behavioral detail—that the result includes trigger URLs—and the ownership constraint ('room the account owns'). This is useful but not extensive; no pagination, ordering, or permissions are discussed.

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 concise sentence, front-loaded with the verb, and contains no filler. It efficiently conveys the action and one key detail (trigger URLs).

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 operation with one parameter and an output schema, the description is reasonably complete. It states the scope (a room the account owns) and the included detail (trigger URLs). It does not mention error conditions or edge cases, but those are not expected for a read-only list tool, especially with the provided output schema.

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% with a basic description for invite_code ('Room invite code.'). The tool description does not add any further explanation of invite_code or its usage, leaving the parameter semantics no richer than the schema already 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 states a specific verb ('List'), a specific resource ('incoming webhooks'), and a clear scope ('for a room the account owns') plus the key detail of including trigger URLs. This distinguishes it from sibling operations like create_webhook, delete_webhook, and other list_* 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?

No explicit guidance is given about when to use this tool versus alternatives. The description does not mention when not to use it or point to siblings like create_webhook for creation. Usage is only implied by the verb 'List', not stated.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=true, and openWorldHint=true. The description adds meaningful behavior: it discloses that the first ping sends an alert, updates are silent, and completion sends one final alert. It also explains billing implications (new streams are charged, updates are free). No contradictions with annotations. It doesn't mention potential side effects like overriding previous state, but the essential behavioral traits are covered.

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 sentences, front-loaded with the purpose and then providing the lifecycle and billing details. No redundant words or repetition of schema content. It is tightly written and efficient.

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

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

The description explains the core state machine and the relationship between pings and billing, which is sufficient for an agent to call the tool correctly for the primary use case. Given the extensive nested schema and output schema, the description does not need to enumerate every field. It misses edge cases like behavior after completion or template-specific constraints, but these are documented within the schema, making the description adequate.

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

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

Schema description coverage is 100%, so every parameter already has a description. The tool description adds value by framing the correlation_id lifecycle and the distinction between stream creation and updates, which reinforces but does not introduce new meaning beyond the schema. Since schema covers the parameters thoroughly, the baseline of 3 is appropriate; the description does not compensate for any gaps.

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: 'Start, update, or end a live progress card on the room members' lock screen', clearly distinguishing it from sibling tools like broadcast or ask_question. It also names the underlying platform (iOS Live Activity / Android live update), leaving no ambiguity about what this tool does.

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 a clear usage pattern by explaining the lifecycle: first ping starts the card, subsequent 'running' pings update silently, and 'done'/'failed' ends it with an alert. It also notes the correlation_id reuse requirement. However, it does not explicitly contrast with alternatives like get_live_status or wait_for_ack, though the context is adequate for basic usage.

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 destructiveHint=true, so mutation is known. The description adds 'Delivered as a push to the user. Rate-limited.' which is useful. However, 'then block on their answer' is internally inconsistent with the pairing hint: if it blocks, why pair with wait_for_approval? This ambiguity misleads about whether the call is blocking or not, reducing transparency. It does not contradict annotations directly, but it is confusing.

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 brief: three short sentences that front-load the purpose. It is concise and easy to scan. The only flaw is the confusing 'then block on their answer' which could have been clearer, but the overall structure is efficient.

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

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

For a tool with 8 parameters, a nested output schema, and destructive annotations, the description is too ambiguous about the flow. The pairing with wait_for_approval is mentioned but not explained clearly, leaving the agent to guess whether this tool blocks or just sends. It also does not indicate what happens on expiry or how to handle the response. The schema and output schema cover much, but the interaction flow is a critical gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already states. It does not, for example, clarify the intended use of idempotency_key or data, but the schema covers these. No value is added over the schema.

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

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

The description states a clear verb and resource: 'Ask the human to approve or reject an action.' It also notes delivery as a push, distinguishing it from a blocking wait. The phrase 'pair with wait_for_approval' hints at a separation from the waiting sibling, though it does not explicitly name alternatives like ask_question. This is clear but slightly marred by the ambiguous 'then block on their answer'.

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 usage for approvals and explicitly suggests pairing with wait_for_approval, providing a sequential usage guideline. However, it does not state when to use this over ask_question or other siblings, nor any exclusions. The guidance is mostly about the flow after calling, not about selecting this tool versus alternatives.

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

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

Annotations already indicate destructive, non-idempotent behavior. The description adds useful context by framing the action as a kill-switch, implying the old handle is invalidated and this is a security response. This goes beyond the bare annotations without contradicting 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 a single, tight sentence that front-loads the action and immediately gives the practical reason for using it. Every word contributes meaning, with no filler or repetition of the title.

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 that the tool has no parameters, the annotations already flag it as destructive, and an output schema exists, the description provides enough context for an agent to select and invoke the tool appropriately. The kill-switch framing answers the key 'why/when' question.

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, so the schema fully covers input semantics and the description rightly adds no parameter details. The baseline of 4 applies because there is no parameter ambiguity for the agent to resolve.

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 ('rotate') and resource ('this agent's public handle'), and immediately clarifies the purpose with 'kill-switch for a leaked handle.' This clearly distinguishes the operation from sibling tools, none of which involve handle rotation.

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 'kill-switch for a leaked handle' provides a clear trigger condition for when to use this tool. It does not explicitly mention alternatives or when-not-to-use, but no sibling tool performs a similar function, so the guidance is sufficient.

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, readOnlyHint=false, and idempotentHint=true, so the behavioral safety profile is covered. The description adds a bit of scope ('this agent's avatar') but does not describe side effects beyond what the annotations imply.

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 deliver the action and the critical constraint with no filler. The verb is front-loaded and 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?

For a single-parameter tool with full schema coverage, an output schema, and annotations covering destructiveness and idempotency, the description plus schema is sufficient for correct selection and invocation. There is no missing information an agent would need to call this tool effectively.

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 parameter includes an example ('bots-3'). The description adds meaningful value by specifying that avatar_id must reference one of the PingRoom bot avatars, narrowing the valid input domain beyond what the schema alone 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?

The description uses a specific verb and resource ('Set this agent's avatar') and adds the key constraint that the avatar must be a PingRoom bot avatar. It is clear and unique among the sibling tools, though it doesn't explicitly differentiate itself from any named alternative.

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

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

The intended usage is implied by the imperative: use this tool when you need to change this agent's avatar. However, it does not explicitly state when not to use it or name a more appropriate alternative for related tasks.

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

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

Given annotations already declare destructiveHint=true and readOnlyHint=false, the description adds the rate-limit constraint (not present in annotations) and clarifies the notification side effect. This goes beyond what annotations alone communicate, though it doesn't detail irreversible effects or prerequisites, which is acceptable 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 a single sentence with zero filler—every word contributes meaning. It front-loads the core action ('Press a room quick action') and follows with the key side effect and constraint. Highly efficient and well 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?

With a full output schema and annotations covering destructive behavior, the description provides enough context: the action, its effect (notifying members), and a critical constraint (rate-limiting). It doesn't explain parameter-level behavior, but the schema already covers that. The description is adequate for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so all five parameters (invite_code, action_number, is_urgent, requires_ack, trigger_source) are well documented in the schema itself. The description adds no additional parameter context, but since the schema fully covers them, the baseline of 3 applies.

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

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

The description clearly states the verb ('press' meaning trigger) and resource ('room quick action'), and explicitly mentions the side effect of notifying members. This distinguishes it from siblings like list_quick_actions and update_quick_action, which are read or modify operations. The rate-limit note adds specificity without ambiguity.

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 purpose implies usage (triggering a quick action to notify members), but there is no explicit comparison to alternatives such as 'broadcast' or 'wait_for_ack', nor any condition for when not to use it. The description provides clear context but lacks exclusions or routing guidance, leaving the agent to infer applicability.

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=true, and idempotentHint=true, so the description does not need to restate those. It adds the ownership requirement, which is useful authorization context. However, it does not disclose what is overwritten or what destructive side effects occur when reconfiguring an existing slot, even though the annotation flags destructiveness.

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, tight sentence with no filler. Key qualifiers like 'numbered' and 'room the account owns' are included without redundant restatement of the tool's title or 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?

With six parameters, full schema docs, and an output schema, the description is adequate but minimal. It covers the core purpose and ownership requirement, but does not explain how 'configure' behaves (e.g., overwriting existing slots, effects on triggers) or when an agent should prefer this over related quick-action tools.

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 reinforces the 'numbered' aspect of action_number and ties invite_code to room ownership, but it does not add substantial meaning beyond the schema's parameter descriptions.

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

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

The description uses a specific verb ('Configure') and identifies the resource ('numbered quick-action slot') as well as its scope ('for a room the account owns'). It clearly indicates the tool's action but does not explicitly differentiate it from siblings like trigger_quick_action or list_quick_actions, relying on the resource wording instead.

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 about what the tool does—configure a quick-action slot for an owned room—and implies the prerequisite that the account must own the room. It does not explicitly state when not to use it or name alternatives, but the context is enough to route an agent correctly in most cases.

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 mutation and risk are known. The description adds the ownership constraint ('on a room the account owns') and the ability to change specific fields, but does not disclose side effects like immediate effect, possibility of failure if the room is not owned, or implications of regenerating secrets. With annotations covering the safety profile, the description adds modest context but not rich behavioral detail.

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

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

A single sentence that front-loads the verb and resource, then gives representative examples. No wasted words; the key ownership constraint is included. Perfectly concise and structurally sound.

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 (12 params) and the existence of an output schema, the description does not need to explain return values. It provides the essential context of updating an existing webhook owned by the account. The schema covers all parameter semantics, so nothing critical is missing. A small gap is the lack of guidance on which parameters are commonly updated together, but this is not essential.

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 each parameter has a meaningful description. The tool description does not add parameter-level detail beyond the examples, which are illustrative not exhaustive. Baseline 3 is appropriate because the schema carries the semantic load, and the description's examples do not significantly enhance parameter understanding.

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 the specific verb 'Update' on the resource 'incoming webhook (by id) on a room the account owns', and gives concrete examples of what can change (icon, title, message, sound). This clearly distinguishes it from create_webhook and delete_webhook without ambiguity.

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 implicitly indicates when to use it (modify an existing webhook owned by the account) by mentioning ownership and the nature of the update. It does not explicitly name alternatives, but the context makes the usage clear. It lacks explicit exclusions like 'use create_webhook for new webhooks', but that is fairly obvious.

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 indicate this is not read-only. The description adds meaningful behavioral constraints: the ~90 KiB MCP limit, the Pro account requirement, and the fact that the tool returns an attachment id for later use. This goes beyond what annotations provide, though it does not discuss retention or cleanup.

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 key constraint and purpose. The final sentence routes to alternatives without padding. 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?

With a fully described input schema and an output schema present, the description covers the essential selection and invocation context: size limit, account requirement, resulting id, and alternative for larger files. Nothing needed to call the tool correctly is missing.

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

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

The input schema has 100% parameter descriptions, so the schema already documents filename, mime_type, and content_base64. The description adds minimal parameter-level meaning beyond 'upload a file'; it mostly restates the body content. Baseline 3 is appropriate because the schema carries the load.

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: 'Upload a small file' and states the outcome: 'get an attachment id to include in broadcast or ask_question via attachment_ids.' This clearly distinguishes the tool from siblings like get_attachment and delete_attachment.

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 explicitly says when to use this tool (small files, for use with broadcast/ask_question) and when not to use it: 'Larger files: use the PingRoom CLI or agent REST API.' This is concrete routing guidance, not vague context.

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

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

The annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond those hints: it is a long-poll, it can end by acknowledgement, expiration, or timeout, and it is generic rather than question-specific. This is useful transparency for an agent deciding whether to call it.

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 sentence concisely captures the tool's operation and all exit conditions, and the second sentence routes question-related use to the correct sibling. 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?

For a simple 2-parameter, 1-required-parameter tool with a complete schema and an output schema present, the description covers behavior, termination conditions, and the relevant sibling distinction. There is no meaningful gap that would prevent an agent from invoking it correctly.

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

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

The input schema already documents both parameters fully, including timeout semantics and notification_id format, so the baseline is 3. The description mentions 'timeout elapses' which obliquely maps to the timeout parameter, but it does not add meaning 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 states a specific action and resource: 'Long-poll a generic acknowledgement-required ping' with concrete termination conditions: recipient acknowledgement, expiration, or timeout. It also explicitly differentiates from the sibling wait_for_answer by saying 'Questions use wait_for_answer instead.'

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 usage context: use this for acknowledgement-required pings, not for questions. The parting sentence names the alternative tool directly, which is strong when-to-use/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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations: the long-polling nature, the server-capped timeout, and the specific state/return behavior on answer. This complements the annotations without contradicting 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 two sentences with no filler. The core action ('Long-poll a question until it is answered or expires') is front-loaded, and the return details are compactly appended. Every clause adds 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?

Given the tool's simplicity, the presence of a full output schema, and annotations covering safety/idempotency, the description is complete. It covers the waiting behavior, the termination conditions, and the key return fields. An agent has enough information to invoke this tool correctly.

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

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

Schema description coverage is 100%, with both question_id and timeout already documented. The description adds no new parameter-level meaning beyond the schema; it only restates the timeout cap and explains return values, which is not parameter semantics. 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 uses a specific verb ('Long-poll') and resource ('a question'), clearly stating what the tool does: waits until the question is answered or expires. It also distinguishes itself from sibling wait_* tools by specifying the question context and return payload (state, option value + label, responder).

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 conveys when to use this tool: when an agent needs to block until an answer arrives or the wait times out. It does not explicitly name alternatives like get_question for non-blocking polling or exclude other wait_* tools, but the context is clear and no misleading guidance is present.

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 read-only and idempotent safety; the description adds meaningful behavior by revealing long-polling semantics, the expiry condition, and that the result contains status plus the chosen option once decided. It does not contradict annotations and does not overstate side effects.

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, front-loaded with the key behavior and return info, with no redundant filler. Every sentence earns its place.

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

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

With the fully described schema, read-only annotations, and an output schema, the description completes the picture by naming the polling behavior, stopping condition, and returned status/option. No critical operational details are 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 parameters timeout and approval_id already have descriptions. The tool description adds context about decision/expiry, but it does not enrich the parameter semantics beyond what the schema provides; baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Long-poll an approval request') and specifies the termination conditions ('until the human decides or it expires'). It also states the return value, making it easy to distinguish from get_approval and the other wait_for_* 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?

'Long-poll...until...' clearly frames when to invoke: use this when you want to block until an approval decision or expiry. However, it does not explicitly tell the agent to prefer get_approval for a non-blocking read, so no exclusions are named. This is clear context but lacks explicit alternatives.

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

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

Annotations only state readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description carries the burden of explaining behavior. It does so by disclosing blocking semantics, timeout expiration, terminal states, and the precise success condition ('answered result with activation_completed true'). This goes well beyond what annotations alone could convey.

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

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

Two sentences deliver the core action, termination conditions, and a tricky success-criterion edge case without wasted words. The primary behavior is front-loaded, and the onboarding-specific nuance is placed exactly where it is needed.

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 polling tool with an output schema present, the description covers the main behavior, edge cases, and success criteria thoroughly. It does not explicitly map to sibling tools, but the activate_agent_inbox reference anchors it in the broader flow, so nothing essential is missing for correct invocation.

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

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

The input schema already provides complete descriptions for both handoff_id and timeout, including the use of 0 for an immediate state read. With 100% schema coverage, the baseline is 3, and the description adds only a small behavioral note about using a bounded local deadline rather than new parameter-level semantics.

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

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

The description opens with a specific verb phrase, 'Long-poll a Handoff until the human resolves it, it expires, or the bounded timeout elapses,' which precisely defines the action, resource, and termination conditions. It also names a specific integration point ('the onboarding Question returned by activate_agent_inbox'), making the tool's role unmistakable among the wait_for_* siblings.

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

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

The description gives clear context for when this tool is appropriate: waiting on a Handoff, with a special scenario for the activation-completion flow. It does not explicitly state when not to use it or name alternative tools like get_handoff or wait_for_answer, but the bounded-timeout language and the reference to activate_agent_inbox convey the intended usage well 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?

The annotations already mark this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely valuable behavioral context beyond the annotations: it blocks, it long-polls, it returns on arrival or timeout, and it excludes the agent's own sends. No contradiction with the annotations.

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

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

The description is three concise clauses that immediately front-load the key behavior ('Long-poll', 'Blocks until one arrives or the timeout elapses') before adding the real-time framing and the own-sends exclusion. Every sentence earns its place with no filler.

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

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

Given the low parameter count, high schema coverage, supportive annotations, and an output schema, the description provides all necessary invocation context. An agent knows this is a blocking read operation, what it waits for, when it returns, and what filters apply.

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 input schema fully documents 'after' and 'timeout'. The description itself does not add parameter-level detail, but it doesn't need to: the schema already explains the cursor semantics and the timeout behavior. This matches the baseline for high 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 names a specific verb ('Long-poll'), a specific resource ('the next ping'), and one distinguishing behavioral trait (the tool is 'the real-time inbound channel for an agent'). It tells an agent exactly what this tool does and separates it from siblings like get_notification or list_notifications, which are pull-based rather than blocking.

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

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

The description gives clear context for when this tool is appropriate: it is the real-time inbound channel, blocking until a ping arrives or timeout elapses. It also adds an explicit exclusion ('The agent's own sends are excluded'), which is a useful when-not. It stops short of explicitly naming and contrasting alternatives such as wait_for_ack or wait_for_answer, so it earns a 4 rather than a 5.

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