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 convey readOnly=false and idempotent=false, so the description is not burdened with stating the obvious. It adds concrete behavioral facts not present in annotations: rate-limiting and unavailability in personal rooms. These are useful operational warnings beyond what the schema and annotations provide.

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

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

Three short, front-loaded sentences carry the essential purpose, a critical rate-limit warning, and a routing exclusion. There is no filler, restatement, or irrelevant detail.

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 13 parameters and nested objects, the description is brief but covers the key selection constraints. The rich input schema and presence of an output schema carry most invocation details, and the description supplies the missing operational guidance: rate-limit awareness and the personal-room alternative.

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 names no parameters and adds no extra semantics beyond the schema; however, the schema itself documents each parameter thoroughly, including nested data fields and reserved meanings. The description neither helps nor hurts here.

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

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

The description opens with a specific verb and resource: 'Send a custom ping to a room the account belongs to.' It immediately distinguishes itself from the sibling trigger_quick_action by explicitly excluding personal rooms. The purpose is unambiguous and not a tautology.

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

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

It states both a precondition ('a room the account belongs to') and an explicit exclusion with a named alternative: 'Not available in personal rooms (use trigger_quick_action there).' This gives an agent clear routing guidance without opening other tool definitions.

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?

Annotations already indicate read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it warns about a credential-protected latest-pings feed and a token-free install URL, and explicitly says 'never send credentials to the install URL.' This is a significant safety behavior not captured by annotations.

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

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

Three sentences with no filler. The first sentence states the purpose, the second gives usage and mismatch handling, and the third warns about credential safety. Information is front-loaded and each clause earns its place.

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

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

For a zero-parameter tool with an output schema present, the description covers the essential invocation context: what the tool verifies, when to call it, what to check, and a critical security caveat. 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameter meanings; it instead clarifies what the returned fields represent, which is relevant to the output. No parameter documentation gap exists.

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

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

The description opens with a specific verb and resource: 'Verify the current connection.' It then explains the meaning of the key fields (owner.id, handle, home_room), making the tool's purpose immediately clear. No sibling tool appears to cover connection verification, so it is naturally distinguishable.

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

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

The description gives explicit when-to-use guidance: 'After login or reconnect, match owner.id and handle to the approved account and robot before sending.' It also specifies the action to take on mismatch: 'stop and reload or restart the MCP client.' This is concrete, actionable routing information.

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 readOnlyHint=false (mutating) and destructiveHint=false (not destructive). The description adds an important business rule: 'Counts toward the free-plan five-room cap', which is not in annotations or schema. It provides practical side-effect information that helps an agent anticipate consequences.

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 exceptionally concise: two sentences, with the most critical information (public, unique handle, quota impact) front-loaded. No extraneous words, every element serves a 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 the complexity (10 parameters, output schema exists, annotations cover safety), the description covers the essential business constraint (quota) and public nature. The output schema likely documents return values, so no further explanation is needed. The only minor gap is not explicitly mentioning the handle uniqueness requirement as a parameter constraint, but the schema's pattern provides 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?

Schema coverage is 100%, so all 10 parameters are described in the schema. The description adds no new parameter-level semantics, but it does reinforce the handle uniqueness context. Baseline 3 is appropriate since the schema carries the parameter 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?

The description clearly states verb ('Create'), resource ('a publicly discoverable room'), and a distinguishing constraint ('unique @handle' and free-plan cap). It differentiates from sibling create_room by emphasis on public discoverability and handle uniqueness.

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

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

The description implies when to use this tool (creating a public room, as opposed to create_room which likely handles private rooms). It does not explicitly mention alternatives or when not to use, but the context is clear enough for an agent to infer the distinction.

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 cover the safety profile (non-readonly, non-destructive, not idempotent). The description adds two non-obvious behaviors the schema does not: the Pro-account requirement and that the returned secret trigger URL is a credential to be protected. It does not mention whether webhooks can be recreated or valid-invite requirements, but what it provides is high-value.

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, front-loaded with the purpose and the precondition, closing with the credential warning. No filler.

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

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

An output schema exists, so return values need not be explained, yet the description still flags the sensitive nature of the returned URL. It covers purpose, precondition, and output caution; it omits failure modes or room-ownership constraints beyond 'owns,' which is minor.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters in detail; the description adds no parameter-level meaning. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Create an incoming webhook') and adds scope ('for a room the account owns'), which distinguishes it from list_webhooks, update_webhook, and delete_webhook among 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 precondition 'the account must be Pro' is genuine when-to-use context an agent cannot get elsewhere. However, there is no guidance on when to prefer this over other creation tools or how it relates to update_webhook/delete_webhook.

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?

Beyond the destructiveHint and idempotentHint annotations, it reveals the concrete consequences: revocation of access/refresh credentials and room memberships, current-connection-only scope, and post-login requirements to restart/reload and verify connection_info owner.id and handle. The description is consistent with destructiveHint=true and does not contradict 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 front-loads the core action and consequence, then provides conditions, ordering, scope, and post-login steps in compact sentences. No sentence is filler; each adds decision-relevant or execution-relevant detail.

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

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

For a zero-parameter destructive tool, the description covers when, in what order, with what scope, and what to do after login. The presence of an output schema means the description need not explain return values, and the annotations already communicate safety and idempotence.

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

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

With zero parameters, the schema already exhaustively documents inputs, giving a baseline of 4. The description goes further by explicitly stating the tool 'accepts no account or robot selector,' preventing an agent from assuming optional selector parameters are allowed.

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 ('Revoke') and a specific resource ('this authenticated robot connection'), and details what revocation covers ('access and refresh credentials and room memberships'). It clearly distinguishes the tool from read-oriented siblings like connection_info and from robot/account management by stating it accepts 'no account or robot selector'.

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 when-to-use conditions ('only when the human explicitly requests logout, disconnection, or reconnection'), ordering constraints ('Call BEFORE clearing local credentials or running MCP logout/login'), and a scope exclusion ('affects only the current connection'). This gives an agent unambiguous decision rules and sequencing without needing to infer from the name.

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, covering the safety profile. The description adds only the scoping context 'configured for a room' and does not disclose additional behavioral details such as ordering or filtering, though the output schema covers return values.

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 clean, front-loaded sentence with no redundancy. It communicates the exact action and scope while leaving parameter details to the schema.

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, idempotent tool with one fully documented parameter and an output schema, the description is sufficient for an agent to select and invoke it correctly. 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 single parameter invite_code is fully documented in the schema with 100% coverage. The description adds no new parameter-level meaning beyond reaffirming the room context, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('quick actions configured for a room'), clearly distinguishing it from sibling tools like trigger_quick_action and update_quick_actions. The scope is unambiguous.

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

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

The description implies a read-only listing use case via the verb and resource, but it does not explicitly state when to prefer this over alternatives such as trigger_quick_action or update_quick_actions. No exclusion or alternative 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 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 scoping detail that results are limited to the authenticated account's rooms, which is useful. It does not describe pagination, ordering, or response format, but with an output schema present and annotations covering safety, this is adequate.

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 is front-loaded with the verb and resource, and includes the key scope qualifier. Every word earns its place; no fluff or repetition.

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

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

For a zero-parameter, read-only list operation with an output schema and safety annotations, the description is nearly complete. It could mention whether the list is sorted or paginated, but those are minor gaps given the output schema likely covers return structure.

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 there is no parameter semantics burden. The description correctly implies no inputs are needed. Baseline 4 is appropriate for a no-parameter tool.

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 ('rooms'), and clarifies scope ('the authenticated account belongs to'). It is clear, though it doesn't explicitly differentiate from sibling tools like get_room or list_handoffs; the resource name itself provides enough distinction.

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

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

The description implies usage context: call this to see rooms for the authenticated account. It does not explicitly state when to use this versus alternatives like get_room or create_room, but the scope qualifier gives some guidance. No exclusions or alternative tool mentions are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, 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?

Annotations already declare readOnly=false, idempotent=true, destructive=false, but the description adds real operational context: exactly one alert on start, silent updates, one completion alert on end, plus a billing/rate-limit note (free accounts limited NEW streams per day; updates and final ping never charged). That is substantive disclosure beyond structured fields.

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

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

Four tight sentences, front-loaded with the core action before lifecycle and pricing details. Every sentence carries distinct information with no filler.

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

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

An output schema exists so return values need not be explained, and the nested live_status object is fully documented in the schema. The description supplies the lifecycle and billing context an agent needs to drive the tool correctly across multiple calls.

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 baseline is 3, but the description adds lifecycle semantics for the key parameter by explaining that correlation_id is "the stream key" that must be reused across pings, and it defines the meaning of the state transitions. This meaningfully extends beyond the schema text.

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?

Names a precise verb set ("Start, update, or end"), the resource ("live progress card"), and the platform surface ("room members' lock screen / iOS Live Activity / Android live update"). This clearly separates it from the read-side sibling get_live_status without needing to name it.

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

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

Explains the full lifecycle usage: reuse the same correlation_id per stream, "running" pings update silently, "done"/"failed" end the stream. However it never explicitly names the alternative read tool (get_live_status) or states when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations already 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?

Beyond the annotations, it discloses the rate limit, the member-notification side effect, and the 422 quick_action_input_required failure mode. It doesn't contradict 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 tightly packed sentences front-load purpose, add the rate-limit caveat, and then give the prerequisite; no filler. The dense middle 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 complex 9-parameter tool with full schema descriptions, an output schema, and annotations, the description covers the main risk areas: side effect, rate limiting, and input_type-dependent payload requirements. Nothing essential to 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 covers all 9 parameters, but the description adds cross-parameter meaning: which payload key satisfies which input_type and that file/photo/pdf require attachment_ids. This is valuable beyond individual schema descriptions.

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

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

The description uses a clear verb–resource pair–'Press a room quick action'–and states the side effect ('notifying its members'), which separates it from list/update quick-action tools. The title is reinforced without being merely restated.

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 tells the agent to read the action's input_type first via list_quick_actions and gives the matching payload mapping before pressing. It stops short of explicit when-not/alternative exclusions, so not 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 communicate that this is destructive, idempotent, and not read-only. The description adds one useful scoping detail, account ownership of the room, but does not disclose that the action overwrites or replaces an existing slot configuration.

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

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

A single, front-loaded sentence with no filler. It communicates the verb, resource, and key scope in eleven words, which is ideal for this dimension.

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 is adequate when combined with the rich schema and annotations, but it omits usage-routing context versus the plural sibling and does not mention constraints like the Pro requirement for slots 5–16, which is only present in the parameter schema.

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

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

Schema description coverage is 100%, and the schema already provides detailed meanings for action_number, label, icon, input_type, and others. The description only reinforces the invite_code/action_number relationship via 'numbered quick-action slot' and ownership, adding little 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 ('configure'), a precise resource ('numbered quick-action slot'), and a scope condition ('room the account owns'). It is clear and distinct from list/trigger siblings, though it does not explicitly differentiate from the very similar sibling update_quick_actions.

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

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

The description gives an ownership prerequisite but provides no guidance on when this tool should be used instead of update_quick_actions, trigger_quick_action, or list_quick_actions. An agent is left to infer the appropriate 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?

Beyond the annotations, the description discloses an important side effect: each single-slot write triggers a background refresh and consumes from a finite push budget. It also clarifies the partial-update behavior ('Slots you do not list are left exactly as they are'), which is valuable transparency for a destructiveHint=true mutation tool.

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

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

Three sentences with no filler. The main purpose is front-loaded, the rationale for choosing this tool is concrete, and the partial-update caveat earns its place by preventing an incorrect assumption that the call resets all slots.

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, combined with the thorough input schema and an output schema, gives an agent everything needed to invoke this tool correctly. It names the alternative, explains the cost tradeoff, and clarifies the partial-update semantics; nothing relevant is left unresolved.

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 rich coverage of both parameters, so the baseline is 3. The description adds meaningful semantics by explaining that omitted slots are untouched and that this is equally valid for updating a single Ping, which clarifies how the actions array should be interpreted.

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: 'Configure several of a room's quick-action slots in one call.' It explicitly contrasts itself with update_quick_action, making the batch-vs-single distinction unmistakable and differentiating it from the sibling tool without requiring schema inspection.

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 direct usage guidance: 'Prefer this over repeated update_quick_action' and explains the concrete cost of the alternative (wasting finite daily push budget). It also covers a subtle case where this batch tool is correct for a single edit because unlisted slots are preserved.

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 idempotentHint=false, so the safety profile is covered structurally. The description adds the ownership constraint but never explains the destructive surface — notably that regenerate_secret rotates the trigger URL — nor what a non-idempotent update implies for repeated calls. Adds some value, but leaves the most consequential behavior undisclosed.

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 tight sentence with the most important information (verb, resource, scoping constraint) front-loaded before the em-dash examples. Efficient and readable, though the examples consume space that could have gone to behavioral constraints.

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 12 parameters and an output schema present, the return-value burden is offloaded, but the description is thin for a destructive, non-idempotent mutation. It omits the secret-rotation semantics, cooldown/quick-action behavior, and any notion of partial versus full updates, leaving meaningful gaps for an agent operating this tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all 12 parameters with examples (catalog ids, hex colors, canonical sound ids). The description only restates four field names and omits behaviorally significant ones like regenerate_secret and cooldown_seconds, adding little 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 names a specific verb (Update) and resource (an incoming webhook) and scopes it to 'a room the account owns'. It even enumerates example fields (icon, title, message, sound), so an agent immediately understands the operation. It doesn't explicitly contrast with create_webhook/delete_webhook, so it falls short of 5.

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

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

'Update ... (by id) on a room the account owns' implies the ownership prerequisite and that the webhook must already exist, which is useful context. However, there is no explicit when-to-use guidance or routing to alternatives such as create_webhook or delete_webhook, so usage is only 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?

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 mark this as read-only and idempotent, and the description adds substantial behavioral detail: it is long-polling, ends on confirmation, expiry, or timeout, and explains how eligible recipients are counted under any vs. all. No contradictions with the readOnlyHint or idempotentHint.

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 packs the core behavior plus confirmation semantics, and the second routes to the alternative. No filler, front-loaded with the key verb and object.

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 an output schema exists and annotations cover safety, the description explains the polling lifecycle, confirmation rules, and the main sibling alternative. It leaves out details like what the return payload contains, but the output schema is expected to cover that, so the description is reasonably complete.

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

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

Schema coverage is effectively 100% (notification_id is clearly documented, timeout has a semantic description including 0 meaning immediate read). The description reinforces the timeout behavior in context but does not add new parameter-level meaning beyond what the schema already provides.

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

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

The description names a specific verb ('Long-poll'), a clear resource ('acknowledgement-required ping'), and precise termination conditions. It also distinguishes itself from wait_for_answer, so an agent can immediately tell what this tool does and what it does not do.

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 routing guidance with 'Questions use wait_for_answer instead,' which is the key exclusion an agent needs. It also clarifies the any/all confirmation modes, but it does not contrast with other wait_for_* siblings like wait_for_notification or wait_for_approval, so some situational ambiguity 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=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.