PingRoom

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

Adds significant behavioral detail beyond annotations: bounded local deadline, terminal result handling, retry policy, and the native phone receipt requirement. No contradiction with readOnlyHint=false or openWorldHint=true; the description enriches these 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?

Every sentence adds necessary information: purpose, conditional handling, polling instruction, success/retry semantics, and final stamp requirement. The description is dense but efficient, front-loaded with the core purpose.

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

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

Given a complex orchestration tool with no parameters and an output schema, the description fully covers the process, states, external dependencies, timeout behavior, and retry logic. Nothing an agent needs to call it correctly is missing.

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

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

Tool has 0 parameters, so baseline is 4. The description references external entities like question.id and install_url but does not need to explain parameters since schema coverage is complete and there are none to define.

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 states a specific action ('Start or resume the onboarding Question'), identifies the resource ('private room the human chose during authorization'), and clarifies its role relative to wait_for_handoff. It clearly distinguishes itself from sibling tools by describing its orchestration 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?

Provides conditional guidance: what to do when recipient_not_ready, when to call wait_for_handoff, and when to retry. It gives clear context on the workflow but does not explicitly state when not to use this tool or name alternative tools for the same scenario.

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

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

The description adds meaningful behavior beyond the annotations: it is a push delivery answerable from the lock screen or in-app, it blocks waiting on an answer, and rate limiting is disclosed. Annotations only indicate read/write intent, so this contextual information genuinely helps the agent.

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, then usage pairing, then delivery/behavioral constraints. Every sentence earns its place and there is no filler or repetition of schema details.

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 11 parameters and nested objects, the description captures the essential interaction model: push, options, blocking, and rate limiting. The output schema exists and schema coverage is complete, so the remaining details like default Approve/Deny options and ttl behavior are already covered by structured fields.

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 of 3 applies. The description's mention of '2-4 tappable options' reinforces the options schema but adds little new meaning beyond what the input schema already documents for ttl, data, text_input, idempotency_key, etc.

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: 'Ask a person a question with 2-4 tappable options' and clarifies the follow-up blocking behavior. This distinguishes it from siblings like wait_for_answer, request_approval, and broadcast without needing to inspect schemas.

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

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

It gives explicit workflow guidance with 'pair with wait_for_answer' and describes delivery and answer semantics ('first valid answer wins'). It does not enumerate when-not-to-use alternatives such as request_approval or broadcast, but the usage context is clear.

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

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

Annotations already signal readOnlyHint=false and idempotentHint=false. The description adds rate-limiting and the personal-room restriction, which are behavioral facts not visible in the schema. It could elaborate on open-world side effects, but the description meaningfully supplements 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, no filler. The exception and alternative are compressed efficiently into the second sentence.

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

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

For a 12-parameter tool with full schema coverage, an output schema, and annotations, the description covers purpose, membership, rate limiting, and the key routing alternative. Nothing required for correct tool selection is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all 12 parameters and nested objects. The description itself adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific action ('Send a custom ping') with a clear resource ('a room the account belongs to'). It also distinguishes itself from trigger_quick_action by noting personal rooms are out of scope.

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

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

Explicitly names the alternative tool (trigger_quick_action) and the exact condition ('personal rooms') where broadcast should not be used. This is direct routing guidance beyond what the schema provides.

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 readOnly/idempotent annotations, the description discloses important behavioral details: the ping feed requires the saved credential, the install URL is token-free, and credentials must never be sent to that URL. This is exactly the kind of context that helps an agent avoid incorrect invocation.

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 primary purpose is front-loaded, the two link types are enumerated, and the critical security warning is included without bloating the description.

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

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

With an output schema present and safety already covered by annotations, the description supplies all the extra context an agent needs: what the links are, which one requires credentials, and which one must never receive credentials. Nothing essential 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 accepts zero parameters, so the schema imposes no burden and the description correctly adds no parameter details. Per the baseline for no-parameter tools, this is well handled.

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 the exact resource ('this connection') and specifies the two distinct outputs: a latest-pings feed and a token-free PingRoom app install URL. This is more specific than a generic 'get info' and clearly differentiates the tool from siblings like get_live_status or get_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 makes the tool's purpose self-evident: use it to retrieve stable connection links. It also gives a crucial usage warning about not sending credentials to the install URL. It does not explicitly contrast with alternatives, but none are strongly competing for this task.

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

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

The description adds valuable behavioral detail beyond the annotations by noting that the server verifies device support for the complete Handoff action before creating anything. This implies a precondition and clarifies that no object is created if the verification fails. The annotations already indicate a non-read-only, non-destructive mutation, and the description enriches that context 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 two sentences, front-loads the core purpose, and includes a meaningful behavioral guarantee in the second sentence. Every word earns its place, and it is not padded with redundant information that already exists in the schema or annotations.

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 (10 parameters, nested objects, output schema), the description provides the essential purpose and a key precondition. The output schema covers return values, and the annotations provide safety hints. The main omission is lack of explicit routing guidance among sibling tools, but that is partially covered by the purpose statement.

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 high (90%), so the schema already documents most parameters. The description adds minimal parameter-level meaning beyond rephrasing the kind distinction (acknowledgement vs. question). Per the baseline rule, this is adequate, but the description does not significantly compensate for any parameter ambiguity.

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

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

The description states a specific verb and resource: "Hand work to exactly one human" as either an acknowledgement or a tappable question. It also conveys the constraint of exactly one recipient, which helps differentiate it from broadcast and room-based siblings. This is more specific than the title alone and clearly identifies what the tool creates.

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 one-to-one handoffs requiring acknowledgement or a question, but it does not explicitly state when to prefer this tool over siblings like ask_question or broadcast. The phrase "exactly one human" provides a hint, but there is no explicit when/when-not guidance or mention of 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 this is a mutating, non-idempotent operation, and the description adds valuable behavioral context by disclosing that the operation counts toward the free-plan five-room cap. It does not go into failure behavior or authentication requirements, but for a create operation with these annotations, the disclosed quota limit is meaningfully transparent.

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 convey the core action, the public-discoverability scope, the unique-handle constraint, and a consequential quota side effect. There is no redundant phrasing, and the main purpose 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?

The description covers the most important behavioral consequences for an agent: the public nature of the room, the unique handle requirement, and the quota impact. Given the rich input schema and existing annotations, this is nearly complete, though it could briefly mention how this relates to the sibling `create_room` for even clearer tool selection.

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

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

The input schema already provides 100% parameter description coverage, including format constraints, defaults, and valid values. The description does not need to restate parameter details, and it adds no extra parameter-level semantics beyond mentioning the unique @handle requirement.

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') with a specific resource ('publicly discoverable room') and a distinguishing constraint ('unique @handle'). It clearly separates this tool from the sibling `create_room` by emphasizing public discoverability, which is exactly the information an agent needs to select this tool.

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

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

The public discoverability qualifier gives clear context for when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it, such as 'use create_room for private rooms,' so it stops short of a full usage-routing explanation.

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 provide false hints for readOnly, openWorld, idempotent, and destructive, so they do not describe side effects. The description adds meaningful behavioral context: the five-room quota for free accounts and the conditional promotion of the new room to delivery-room status, which affects where handoffs and direct questions land. This goes beyond what annotations 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?

The description uses three sentences, each adding distinct information: the core purpose, the quota limitation, and the delivery-room side effect. It is front-loaded with the main action and contains no redundant or filler phrasing.

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

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

The description covers purpose, ownership, quota, and the side-effect condition, and an output schema is present, so return-value details are not needed. The only minor omission is an explicit pointer to create_public_room, but the word 'private' already signals that boundary, making the description complete enough for correct tool selection and 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%, so the input schema already documents name, icon, and color with examples and constraints. The description adds no parameter-level detail beyond what the schema provides, 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.' The 'private' qualifier clearly differentiates it from the sibling create_public_room, so an agent can correctly identify which tool to use.

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 clear context: this is for private rooms owned by the caller, and it explains the delivery-room condition when the agent has every room. It does not explicitly name create_public_room as the alternative for public rooms, but the private/public contrast and the sibling list make the intended use reasonably clear.

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

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

Annotations provide no safety hints beyond all-false flags, so the description carries the behavioral burden. It adds genuine value: the return value is a secret credential ('treat it as a credential') and the account-tier requirement is disclosed. No contradiction with annotations — 'Create' is consistent with readOnlyHint=false.

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

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

Two sentences with zero waste: verb+resource first, then the ownership/Pro constraints, then the credential warning. Every clause earns its place and the most security-critical information is placed last for emphasis.

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 write tool with an output schema, the description appropriately focuses on what the schema cannot express: ownership requirement, Pro-tier requirement, and the sensitive nature of the returned trigger URL. Minor gaps remain (e.g., what happens on duplicate names or whether creation is immediately active), but the essentials for correct invocation are covered.

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 10 parameters are already documented in the schema. The description adds no parameter-level detail, but at full coverage the schema does the heavy lifting, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Create an incoming webhook') and adds a scoping condition ('for a room the account owns'), which clearly distinguishes it from siblings like update_webhook, delete_webhook, and list_webhooks. The create-vs-mutate-vs-delete distinction is unambiguous even without opening the schema.

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

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

The description gives clear contextual prerequisites: the room must be owned by the account and the account must be Pro. This tells the agent when it is permitted to call the tool. It does not explicitly name alternatives or when-not-to-use conditions, but the operational contrast with the webhook siblings is evident from the tool name itself.

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, so the safety profile is covered. The description adds meaningful context by restricting retrieval to 'visible' notifications and highlighting 'current action_state', which signals that the state may change over time.

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 sentence with no filler: verb, resource, lookup key, and returned field are all front-loaded. Every part of the 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?

For a simple get-by-id read tool, the description is nearly complete: annotations cover safety, the output schema covers return shape, and the parameter is fully documented. The only small ambiguity is what exactly counts as 'visible', but this is minor for 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 notification_id is already documented as 'Room notification id.' The description only repeats 'notification id' without adding extra format, source, or usage 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 states a specific verb ('Fetch'), a specific resource ('one visible ping'), and the exact lookup key ('by notification id'). It also says the response includes 'current action_state', which distinguishes this from list-oriented siblings like list_notifications and 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 usage context is implied: use this when you have a notification id and want that single notification's current state. However, it does not explicitly say when to prefer this over list_notifications or wait_for_notification, nor mention any exclusions.

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

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

Annotations already 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the 'bounded page' and 'newest first' ordering behavior, plus pagination semantics. It doesn't disclose rate limits or which rooms count as approved, but annotations carry the core safety burden.

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

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

Two sentences, front-loaded with the core behavior and then the pagination instruction. 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?

A read-only list tool with a full output schema, 100% parameter coverage, and annotations covering idempotence/read-only/destructive safety. The description completes the picture with pagination semantics and ordering. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema documents all four parameters. The description adds the pagination loop concept and 'bounded page', which reinforces page/limit semantics. It does not add new parameter meaning beyond what schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a bounded page of recent pings across approved rooms, sorts newest first, and explains pagination via 'has_more'. It distinguishes itself from get_notification (single notification) and list_handoffs/list_questions (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?

The description gives clear pagination guidance: use page while has_more is true. It implies a read-only listing context but doesn't explicitly contrast with get_notification or wait_for_notification. Sibling names provide context but the description does not say when to choose it over 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 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 covered. The description adds useful context about the catalog's contents and its role in supporting creation tools, which goes beyond the annotations.

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

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

Two sentences, front-loaded with the core listing function, followed by precise usage guidance. No filler or redundancy; every sentence provides 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 no parameters, an output schema, and annotations covering safety and idempotency, the description is complete. It tells the agent what the catalog contains, when to call it, and how to use the results, leaving no important 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?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to explain about parameters. The baseline for zero-parameter tools is 4, and the description appropriately focuses on usage rather than parameter details.

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

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

The description starts with a specific verb and resource: 'List the room-icon catalog', and specifies the contents (icon ids, tags, and categories). This clearly distinguishes it from sibling list tools like list_rooms 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 explicitly says when to call this tool: before create_room, create_public_room, or create_webhook to pick a valid icon id, and also to interpret icon values from reads. It gives clear context, but does not mention alternatives or say when not to use it.

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

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

Annotations already 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context beyond that: the operation returns trigger URLs and requires the room to be owned by the account, which is a meaningful behavioral/requirement disclosure.

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

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

A single, compact sentence with no wasted words. The verb and primary subject are front-loaded, and the scope qualifier is placed at the end, making the purpose immediately clear.

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 annotations and an output schema, the description covers the essential information: what is listed, what detail is included (trigger URLs), and what precondition applies (room ownership). Nothing necessary is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the invite_code must reference a room the account owns, which is a semantic constraint not present in the schema's generic 'Room invite code' description.

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

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

The description states a specific verb ('List') and resource ('incoming webhooks with their trigger URLs'), and qualifies the scope ('for a room the account owns'). This clearly distinguishes it from sibling tools like create_webhook, delete_webhook, and update_webhook.

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 clear context: use this tool for a room the account owns, identified by invite_code. It doesn't explicitly name alternatives or exclusions, but the list-versus-create/delete/update framing makes the usage 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 description reveals important behavioral details beyond annotations: alert side effects on first and final pings, silent intermediate updates, and quota/charging behavior for free accounts. This gives the agent critical expectations about mutating behavior and cost, with no contradiction to 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 two well-structured sentences: first the overall function, then the lifecycle and quota behavior. Every sentence contributes essential guidance 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 input schema and output schema, the description covers the essential runtime behavior an agent needs: how to start, update, and end a stream, when alerts happen, and cost implications. Nothing critical appears missing for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful semantics for key parameters like correlation_id ('Reuse the same correlation_id for every ping') and live_status states, which helps the agent understand how parameters drive the stream lifecycle.

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 specific verbs and a concrete resource: 'Start, update, or end a live progress card' on a defined platform (iOS Live Activity / Android live update). This makes the tool's function unambiguous and distinguishes it from read-only siblings like get_live_status.

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 explains the stream lifecycle: first ping starts the card, running pings update silently, and done/failed ends it with a completion alert. It does not explicitly name alternatives or exclusions, but the conditional usage rules are strong enough for an agent to know when to call this tool.

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

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

Annotations already mark this as destructive and non-idempotent, and the description adds valuable context beyond those flags: the code is single-use and consumed, redemption grants Pro to the connected account, eligibility limits apply, and retrying a successful redemption is forbidden. This directly informs the agent about irreversibility and 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?

The description is compact and every sentence carries operational weight: what the action does, who it affects, what prerequisites are absent, what limits apply, and what not to do. It is effectively front-loaded with the core redeem behavior.

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 a 100% covered schema, an output schema, and annotations indicating destructiveness, the description provides all necessary context: target account, single-use behavior, eligibility limits, and retry guidance. Nothing an agent needs to call this correctly is missing.

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

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

The schema fully describes the code parameter, including its pattern, case-insensitivity, and whitespace trimming, so schema coverage is 100%. The description adds only contextual instruction ('Use only a code the user supplied') but no additional parameter-level semantics beyond what the schema already provides, matching the baseline for high 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 clearly identifies the verb ('Redeem'), the resource ('a gifted Pro or promo code'), and the effect ('grants Pro'). It also clarifies the target account ('the human account that connected this agent'), which distinguishes it from any room- or plan-scoped operations among the 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 concrete when-to-use guidance: only redeem a code the user supplied, no room or paid plan is required, and eligibility/one-per-account limits apply. It also explicitly says not to retry a successful redemption. It doesn't name an alternative tool, but the sibling list has no obvious competing redemption tool, so this 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?

Beyond annotations, the description discloses push delivery, blocking expectation, and rate limiting. It doesn't detail side effects or what happens after rejection, but the annotations already mark it as non-read-only and non-idempotent, so the added behavior notes are useful.

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

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

Two short sentences convey purpose, pairing, delivery mode, and rate limiting with no filler. The critical pairing hint is front-loaded in the first sentence.

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

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

For a tool with an output schema and fully documented parameters, the description covers the remaining operational essentials: it creates a push approval request, should be followed by wait_for_approval, and is rate-limited. No critical calling detail 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 parameters are fully documented there. The description adds no parameter-specific guidance, but with full schema coverage the baseline of 3 is appropriate.

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

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

States a specific action ('ask the human to approve or reject an action') and identifies the delivery mechanism (push). It also names the sibling wait_for_approval, so an agent can distinguish the request-creating tool from the waiting/reading tools without inspecting schemas.

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

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

The description explicitly pairs this tool with wait_for_approval, giving clear workflow context for when to call it. It does not enumerate exclusions like 'use ask_question for non-approval decisions,' but the approve/reject phrasing supplies enough situational 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 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?

The annotations already mark this as non-read-only and non-idempotent, and the description does not contradict them. It does add useful behavioral context by saying members are notified and the action is rate-limited, but it gives no specifics about rate-limit behavior, error handling, or 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?

The description is two short sentences with no filler. It front-loads the core action and effect, and the rate-limit note is a meaningful addition that 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 trigger tool with a rich schema, output schema, and annotations, this is mostly adequate. However, it lacks context about how trigger_quick_action relates to update_quick_action or broadcast, and it does not explain what happens when the rate limit is hit or when acknowledgement is required.

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 every parameter already has a meaningful description, including the enum restriction, default behavior, and send-time-only semantics. The description adds no parameter-level meaning beyond what the schema provides, 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 clearly states the operation ('press'), the resource ('room quick action'), and the effect ('notifying its members'). It is distinct from sibling update_quick_action, though it does not explicitly contrast itself with related tools like broadcast or 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?

There is no guidance on when to use this tool versus alternatives such as update_quick_action or broadcast. It also does not state that the quick action must already exist or that configuration should be done separately. 'Rate-limited' is a constraint, not a usage rule.

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

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

Annotations already mark this as non-read-only, destructive, and idempotent, so the description does not need to restate safety cues. It adds a useful authorization/scoping detail ('room the account owns') beyond the annotations, although it does not explicitly say the existing slot configuration is overwritten.

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 11-word sentence with no filler. Every phrase contributes to tool selection and invocation, and the most salient resource ('numbered quick-action slot') is front-loaded.

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

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

Given the fully documented schema, an output schema, and annotations covering the safety profile, the one-sentence description supplies the key missing context: ownership of the room and the slot concept. The only real gap is the unspecified overwrite behavior, but destructiveHint and idempotentHint partially cover that.

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

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

The input schema has 100% description coverage and documents all six parameters, including label constraints, action_number range, sound behavior, and requires_ack meaning. The description's 'numbered slot' and 'room owns' map to action_number and invite_code but add no new parameter-level detail, so baseline 3 is appropriate.

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

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

The description states a specific operation ('Configure') and resource ('numbered quick-action slot') and adds a clear ownership condition ('for a room the account owns'). This distinguishes it from siblings like trigger_quick_action and list_quick_actions, which execute or read quick actions rather than configure them.

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

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

The description implies the main use case — configuring a quick-action slot in an owned room — but it does not explicitly name alternative tools or state when not to use it. The configure-vs-trigger distinction is inferable but not spelled out.

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

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

The annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds materially useful behavior: each slot write triggers a device wake/background refresh, repeated calls consume finite daily push budget, omitted slots are preserved, and nothing in this tool deletes an action. This clarifies the destructive hint 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?

Three sentences, each earning its place: the core operation, the push-budget rationale for preferring this tool, and the preserve-omitted-slots behavior that also justifies single-slot use. The most important scoping information is front-loaded, and there is no filler or repetition of schema content.

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

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

For a two-parameter tool with a rich input schema and an output schema present, the description supplies the missing decision-relevant context: why to batch operations, what happens to omitted slots, and the cost tradeoff against the sibling tool. An agent has everything needed to select and 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%, and the schema already explains invite_code, actions, action_number, label, icon, sound, and requires_ack in detail. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate; the schema carries the parameter-semantics burden.

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

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

States a specific verb and resource: 'Configure several of a room's quick-action slots in one call.' It is immediately distinguishable from the sibling update_quick_action because the description explicitly frames this as the batch/multi-slot variant. The title and name are not merely restated; the description adds the 'several slots at once' scope.

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 explicit routing guidance: prefer this over repeated update_quick_action calls, with a concrete reason about background refreshes and the daily push budget. It also states that omitted slots remain unchanged, making the tool appropriate even for editing a single Ping, which directly addresses the alternative single-slot 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 signal readOnlyHint=false and destructiveHint=true; the description adds the ownership requirement and that the update targets an existing webhook by id. It does not disclose the concrete destructive consequences (e.g., overwriting settings or that regenerating the secret invalidates the old trigger URL), relying on the schema and annotation to carry that burden.

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 definition is a single front-loaded sentence with the verb and resource up front, which is appropriately concise. It loses one point because the 'title, message' example list is not aligned with the actual schema properties, so not every part of the 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?

The schema covers all parameter semantics and an output schema exists, so the description does not need to explain return values. Still, for a destructive multi-option update tool, the description omits prerequisites (e.g., obtaining webhook_id from list_webhooks) and the overwrite/rotation consequences, leaving an agent to discover these from the schema and annotations.

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

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

The input schema has 100% description coverage, so the baseline is 3, but the description actually adds confusion by naming 'title, message, or sound' when the schema exposes icon, name, color, sound, action_number, cooldown_seconds, and regenerate_secret — there is no title or message parameter. This can lead an agent to attempt invalid parameters under additionalProperties:false.

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 ('Update'), a concrete resource ('incoming webhook (by id)'), and a scope ('on a room the account owns'). It also gives concrete examples of what can be changed, so an agent can distinguish this from sibling create_webhook, delete_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 ownership condition ('on a room the account owns') implies the user must have an owned room and an existing webhook id. However, it gives no explicit when-to-use guidance or exclusions versus create_webhook/delete_webhook, leaving the routing decision mostly to inference.

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

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

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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral detail: long-polling, termination conditions (acknowledgement, expiry, timeout), and the concept of an eligible recipient. 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?

Two tight sentences: the first front-loads behavior and termination conditions, the second routes to an alternative. Every sentence earns its place with 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?

Given the presence of full annotations, complete parameter schemas, and an output schema, the description covers all invocation-relevant information: what it does, when to use an alternative, long-poll behavior, and timeout semantics. Minor ambiguity around 'eligible recipient' does not hinder correct calling.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable extra semantics for the timeout parameter, specifically 'Use 0 for an immediate authoritative state read', which is beyond the schema's basic range and description.

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

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

The description clearly states the operation: long-poll a generic acknowledgement-required ping until acknowledged, expired, or timeout. It also distinguishes itself from wait_for_answer, making the tool's purpose and scope unambiguous.

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

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

It explicitly tells agents to use wait_for_answer for questions, providing a clear when-not condition. However, it does not mention other similar siblings like wait_for_approval, wait_for_handoff, or wait_for_notification, so differentiation from those is left implicit.

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

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

Annotations already declare readOnlyHint=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?

Annotations already establish readOnly, idempotent, and non-destructive traits. The description adds genuinely useful behavioral context beyond those: it explicitly says the call blocks until a ping arrives or the timeout elapses, that it is the real-time inbound channel, and critically that the agent's own sends are excluded. This helps the agent predict runtime behavior without contradicting the annotations.

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

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

The description is a single, tight sentence that front-loads the core action ('Long-poll for the next ping') and packs essential behavioral details into a short em-dash clause. There is no fluff, no repetition of schema field names, and every phrase earns its place.

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

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

Given the output schema exists, the description does not need to explain return values. The key operational facts—blocking behavior, timeout elapse, inbound direction, exclusion of own sends, and real-time nature—are all present. Combined with the schema and annotations, an agent has everything needed 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%, meaning both 'after' and 'timeout' are fully documented in the schema itself. The description provides no additional parameter-level guidance beyond what the schema states, so the baseline 3 is appropriate. It does not hurt, but it also does not compensate or enrich beyond the structured schema.

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

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

The description uses a specific verb phrase 'Long-poll for the next ping' and immediately defines the resource being waited on. It also adds scope ('the real-time inbound channel for an agent' and 'own sends are excluded'), making it easy to distinguish from siblings like get_notification or list_notifications.

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 'real-time inbound channel for an agent' clearly communicates the intended use case: blocking to receive incoming pings. It does not explicitly name alternatives or conditions for when not to use it, but the blocking semantics versus the polling nature of get_notification/list_notifications is strongly implied. A small explicit comparison would have made this a 5.

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