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 annotations already mark this as non-read-only, non-idempotent, and non-destructive, but the description adds important behavior: delivery as a lock-screen or in-app push, blocking on the answer, first valid answer winning, and being rate-limited. These are material operational traits beyond the annotations.

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

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

The description is compact and front-loaded: purpose first, then workflow pairing, delivery behavior, and rate-limit note. Every clause provides useful information without repetition.

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

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

Given the rich input schema, output schema, and annotations, the description covers the critical workflow and delivery behavior an agent needs. It is slightly incomplete because it does not mention required fields like invite_code or clarify room scoping, though those are documented in the 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%, so the input schema already documents all 11 parameters thoroughly. The description only restates the 2-4 option constraint and does not add syntax, defaults, or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Ask a person a question') and immediately clarifies the shape of the interaction ('2-4 tappable options') and its blocking behavior. It also names a sibling tool ('wait_for_answer'), so an agent can distinguish this from related question/approval 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?

It gives clear workflow context: ask a person, then block on their answer by pairing with wait_for_answer. It does not explicitly compare itself to alternatives like request_approval or broadcast, and it states no exclusions, so it falls short of full when/when-not guidance.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, openWorldHint=true). The description adds substantial behavioral context the annotations cannot: rate limiting, Pro-account requirement in others' personal rooms, text-only enforcement including refusal of links, silent ignoring of title/is_urgent/requires_ack there, the visitor two-ping cap, and the checklist tick-back model.

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?

Purpose is front-loaded in the first sentence, followed by the checklist behavior and rate-limit note. The final sentence is a long chain of exceptions, but every clause carries distinct conditional information, so nothing is wasted even if it reads densely.

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 13-parameter, nested-schema tool with an output schema and annotations, the description covers the highest-risk edge cases (personal-room restrictions, ignored fields, rate limits, checklist semantics). It leaves the remaining optional parameters to the schema, which is acceptable given full schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining cross-parameter behavior: data.checklist.items turns the ping into a room-ticked checklist read back as checklist_state, and title/is_urgent/requires_ack are ignored in personal rooms. It does not add format or value guidance for the remaining parameters, which the schema already documents.

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 ('Send a custom ping to a room the account belongs to') and immediately distinguishes itself from the sibling trigger_quick_action for personal rooms. An agent can identify the operation and its main alternative without opening the schema.

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

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

Explicitly routes the agent: use this to broadcast a ping, but 'otherwise use trigger_quick_action there' for someone else's personal room when the Pro/text-only constraints don't fit. Conditions for the restricted path (Pro account, text only, no link, ignored fields) are spelled out rather than implied.

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

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

Annotations already declare 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 already establish the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description's job is to add context — and it does: the Pro-plan gate, the ownership requirement, and the warning that the returned trigger URL is a credential to be handled as such. It doesn't cover failure modes or rate limits, but the safety-relevant disclosure is present.

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, both load-bearing: the first gives purpose plus scope, the second gives a hard prerequisite and a security caveat. No filler and the credential warning is not buried.

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

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

An output schema exists, so the description needn't explain return values, yet it still flags the one return value an agent must handle carefully. Prerequisites and ownership are covered; what's missing is behavior on prerequisite failure (e.g. non-Pro account) for a 10-parameter mutation 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% across all 10 parameters, so the schema already carries the field semantics (including cross-references like list_room_icons for icon ids). The description adds no parameter-level detail, which is acceptable at this coverage level but yields the baseline score.

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 ('Create an incoming webhook') plus a scoping constraint ('for a room the account owns'). This cleanly separates it from update_webhook, delete_webhook, and list_webhooks, which share the resource but differ in verb.

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

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

Gives a clear precondition for use — the room must be owned by the account and the bound account must be Pro — which tells the agent when this tool is applicable. It stops short of naming alternatives or stating what to do instead when the plan requirement isn't met.

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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds important context beyond annotations: credential-scoped results, a 24-hour retention window, null rather than omitted fields, and the ability to resume a stream without re-sending content. These details help an agent understand both result shape and reconciliation behavior.

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

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

The description is front-loaded with purpose and constraints, which is good structure. However, it spends a long sentence enumerating return fields even though an output schema exists, making that portion less concise than necessary. The null-behavior sentence earns its place, but the field list is largely redundant.

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 an output schema and full annotation coverage, the description provides everything an agent needs: purpose, scope limits, retention window, return null semantics, and recovery intent. No critical operational context is missing for a read-only status lookup.

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 invite_code and correlation_id are already documented in the input schema. The description does not add parameter syntax, format, or edge-case meaning beyond what the schema provides. With the schema doing the heavy lifting, a 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 gives a specific verb and resource: read back the current state of a live stream you created. It also defines scope precisely by saying only streams started by this credential within the last 24 hours are returned. It does not explicitly distinguish itself from the similar sibling live_status by name, so it is clear but lacks direct sibling differentiation.

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

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

It clearly states the use case: allowing a restarted producer to reconcile instead of starting a duplicate. The 24-hour and credential constraints implicitly tell the agent when this tool will and will not return useful data. It does not explicitly name alternatives or when not to use it, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: only *visible* notifications can be fetched (an access-scope constraint), and checklist_state is conditional on a checklist item being checked — a non-obvious behavioral trait.

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, front-loaded with the retrieval action and scoped by id, with the conditional return nuance tucked in a subordinate clause. 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 single-param read tool with an output schema and full annotation coverage, this is nearly sufficient — purpose, access scope, and conditional field behavior are all present. The only soft spot is that it doesn't say what happens when the id refers to a non-visible or nonexistent notification.

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?

There is only one parameter and schema coverage is 100% (uuid, 'Room notification id'), so the schema already does the work — baseline 3 applies. The description restates 'by notification id' and adds the 'visible' qualifier, but no extra syntax or format meaning.

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 ('Fetch one visible ping by notification id'), which clearly distinguishes it from the sibling list_notifications by cardinality. It also names the salient return fields (action_state, checklist_state), so the agent knows what it gets back. It doesn't explicitly name sibling alternatives, but the singular-by-id 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?

Usage is implied rather than stated: the agent can infer this is for retrieving a single known notification, versus list_notifications for enumeration or wait_for_notification for blocking. The word 'visible' hints at an access precondition, but there is no explicit when-to-use or when-not guidance.

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

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

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavioral context beyond them: results are a bounded page, ordered newest first, and iteration is driven by a has_more flag. It omits any note on room-membership prerequisites or rate limits, but that is a minor gap.

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

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

Two short sentences, zero filler, with the scope and ordering front-loaded and the pagination instruction following. 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?

An output schema exists, so return values need not be enumerated, and the description still flags the has_more contract the agent must act on. Combined with full schema coverage and safety annotations, little is missing, though a hint about what 'approved rooms' means operationally would close the last gap.

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

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

Schema description coverage is 100%, so the schema already documents date, page, type and limit with formats, enum values and bounds. The description mentions 'page' and 'bounded page' but adds no format or default detail beyond the schema, which is the expected baseline when structured fields do the work.

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 ... pings'), plus scope ('across approved rooms') and ordering ('newest first'), which cleanly separates it from get_notification and wait_for_notification. It stops short of naming a sibling or explicitly contrasting with them, so it is clear but not fully differentiated.

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

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

The only guidance is pagination mechanics ('Use page to continue while has_more is true'), which tells the agent how to iterate but not when this tool is the right choice over get_notification, list_rooms, or wait_for_notification. Usage is implied rather than stated, and there are no exclusions.

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

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

Annotations already declare 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 only declare the safety profile (idempotent, destructive, open-world); the description goes well beyond by disclosing alert behavior (one alert on start, silent moves, one completion alert), the billing/charge model, and the fact that a first ping already marked done/failed is charged as a new stream. None of this is derivable from annotations or schema.

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

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

Front-loads the purpose, then packs lifecycle and charging rules into two dense sentences with little waste. Slightly long, but nearly every clause carries actionable 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 complex tool with nested objects and an output schema, the description covers the stream lifecycle and economic constraints an agent needs. It omits interaction details on secondary params (requires_ack, template/category fixed-at-creation), but those are documented in the 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%, so the schema already documents all 8 parameters, and the description's correlation_id guidance ('reuse the same correlation_id for every ping') largely restates the schema's own text. Baseline 3 is appropriate; no additional syntax or format meaning is supplied.

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 set of verbs (start/update/end) on a specific resource (live progress card on members' lock screen, iOS Live Activity / Android live update), and is immediately distinguishable from the read-side sibling get_live_status.

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

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

Explains the lifecycle discipline for correlation_id (first ping starts, running pings move silently, done/failed ends) and gives concrete when-to-use cost rules for free accounts. It stops short of naming alternative tools (e.g. get_live_status, wait_for_ack) or stating exclusions, so it is strong context without 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?

Adds real behavioral context beyond the annotations: delivery as a push to the connected human only, no trigger permission needed, refusal in public/personal rooms, and rate-limiting. These are traits the readOnly/openWorld/idempotent hints do not convey, though the blocking semantics could be stated more explicitly.

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

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

Front-loads the core purpose and pairs it with the workflow in the first sentence, with constraints in the second and a terse 'Rate-limited.' closer. Dense but largely earned; the parenthetical and clause stacking make it slightly busy.

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

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

With an output schema present and full annotation coverage, the description need not explain return values. It supplies the delivery, permission, room, and rate-limit context an agent needs to call it correctly, leaving only minor gaps around expiration/blocking behavior.

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

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

Schema description coverage is 100%, so all eight parameters (including ttl, options, data, idempotency_key) are already documented in the schema. The description adds no parameter-level detail beyond what structured fields provide, matching the baseline 3.

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 (ask) and resource (the human / an approval) plus the asynchronous behavior (block on the answer). It distinguishes itself from siblings by naming wait_for_approval as the pairing tool and comparing itself to ask_question.

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?

Clearly explains the workflow ('pair with wait_for_approval') and the room-context constraint (public and personal rooms are refused), which tells the agent when this call will fail. It stops short of an explicit when-not / alternative comparison against ask_question or get_approval.

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?

Annotations declare a non-read-only, non-idempotent, open-world, non-destructive write; the description goes well beyond that by disclosing rate limiting, the 422 quick_action_input_required and quick_action_input_type errors, the 409 quick_action_layout_changed guard, and the important caveat that is_urgent/requires_ack are ignored in someone else's personal room. The only gap is that "Rate-limited" is asserted without any limit or backoff detail.

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

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

Three sentences, each carrying a distinct payload: effect, input-type contract, permission caveat. Front-loaded with the action and warning, though the middle sentence is dense and reads as a run-on rather than cleanly separated steps.

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

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

This is a 9-parameter mutation with nested objects and an output schema, and the description covers the preconditions, the conditional data requirement, the owner-only location path, and the ignored-flag edge case. Return values need not be described because the output schema exists, so nothing an agent needs to fire 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?

Schema coverage is 100%, so per-parameter docs are already strong; the description's added value is the cross-parameter conditional (press fails with 422 unless data/attachment_ids match the action's input_type), which the schema alone only implies. It does not restate the individual field docs, which is correct.

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?

"Press a room quick action, notifying its members" gives a specific verb (press/trigger) plus resource (room quick action) and states the side effect (notifying members). It is clearly distinguishable from the read sibling list_quick_actions and the config sibling update_quick_action, both of which are named or implied by name.

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

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

It explicitly routes the agent to list_quick_actions first to read input_type, then specifies exactly which field each input_type requires (data.location, data.url, attachment_ids). It also states the when-not condition for trigger_source=location (room owner only, 403/409 errors), so the agent knows both the prerequisite sequence and the failure modes.

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=true, so the mutation/idempotency profile is covered. The description adds real value beyond that: it discloses a side effect on other users ('sends a background room refresh to room members' devices') and an ownership prerequisite, neither of which is in 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 tight sentences, zero waste, with the primary purpose front-loaded ahead of the side-effect note. Nothing needs trimming or reordering.

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

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

With a full output schema and rich annotations, the description need not explain returns or safety. It covers purpose, ownership prerequisite, and the cross-device side effect; the only real gap is sibling differentiation against update_quick_actions.

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 seven parameters (including the enum, sound defaults, and the 1–16 slot range). The description only alludes to 'numbered' slots and adds no syntax or format detail beyond the schema, so the 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?

States a specific verb (configure) and resource (numbered quick-action slot) and adds an ownership scope ('a room the account owns'). However, it does not distinguish itself from the near-identical sibling 'update_quick_actions' (plural) or from 'trigger_quick_action', so an agent cannot tell which to pick from the text alone.

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

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

No when-to-use guidance and no reference to alternatives. The two nearest siblings (update_quick_actions, trigger_quick_action) are left unmentioned, so nothing tells the agent when this singular tool is preferred over the plural one.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely useful context beyond them: omitted slots are left exactly as-is (softening the destructive semantics), and each single write triggers a device-waking background refresh against a finite daily push budget. 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?

Front-loaded with the purpose, then the rationale and the single-Ping case. Three sentences, all serving selection; the middle sentence is somewhat long but the push-budget justification is what makes the preference actionable.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Combined with the routing guidance and the omitted-slot editing semantics, an agent has everything needed to call this 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 coverage is 100% and the schema itself richly documents action_number, input_type, label, and the omitted-slot behavior. The description adds no parameter-level syntax or field detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb (configure) and resource (a room's quick-action slots) with explicit scope (several in one call). It names the sibling update_quick_action and positions itself against it, so an agent can distinguish the batch tool from the single-slot one without opening either schema.

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

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

Explicitly says to prefer this over repeated update_quick_action and gives the reason (each single-slot write consumes the daily push budget). It also states the non-obvious case where this batch tool is still correct: editing a single Ping. When-to-use is fully specified with the alternative named.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation/safety profile is covered. The description adds the ownership scope, but is silent on notable side effects the schema reveals, e.g. that regenerate_secret rotates the trigger URL or that passing null for action_number clears a preset.

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 with zero waste; the operation is front-loaded and the scope restriction follows immediately. Nothing to trim.

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

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

For a 12-parameter mutation tool with a fully documented schema, an output schema, and annotations, the description is adequate: purpose, identifier, and ownership scope are covered. It stops short of flagging destructive side effects like secret rotation, but the structured fields largely carry that load.

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

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

Schema description coverage is 100%, so all 12 parameters are fully documented in the schema; baseline is 3. The description only echoes icon/title/message/sound and adds no format or constraint detail beyond what the schema provides.

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

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

States a specific verb and resource ('Update an incoming webhook (by id)') and adds scope ('on a room the account owns') plus example fields. 'Update' implicitly distinguishes it from create_webhook/delete_webhook siblings, though no sibling is named explicitly.

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

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

The phrase 'on a room the account owns' hints at a prerequisite, but there is no explicit when-to-use guidance, no exclusion conditions, and no routing to alternatives such as create_webhook or delete_webhook. Usage is only implied from the verb.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: long-poll holds, the any/all confirmation-rule semantics, and the three ways the call can terminate. It stops short of describing the returned state shape, but with an output schema present that is acceptable.

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 written sentences with no waste; the core action and its termination behavior are front-loaded, and the sibling routing is appended where it belongs.

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 2-parameter schema at full coverage, an output schema, and annotations covering the safety profile, the description supplies exactly the missing pieces: long-poll semantics, rule interpretation, and alternative-tool routing.

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

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

Schema description coverage is 100%, so both parameters (including the 'use 0 for an immediate authoritative state read' nuance) are fully documented in the schema. The description only alludes to the timeout as a terminating condition and adds no syntax or format detail, so the baseline 3 is correct.

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 ('long-poll a generic acknowledgement-required ping') plus its scope and termination conditions. It explicitly differentiates itself from the sibling wait_for_answer, so an agent can route correctly without opening either schema.

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

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

Names the alternative tool directly with the condition that selects it ('Questions use wait_for_answer instead'), which is exactly the when-not guidance missing from most definitions. The three terminating conditions (rule met, expiry, timeout) further scope its 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 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds important behavior beyond those: it blocks until a ping arrives or timeout elapses, and it filters out the connected human's and the agent's own sends. Return details are left to the output schema.

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

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

The description is three tight sentences and front-loads the core action, "Long-poll for the next ping." Every sentence adds useful scope or filtering context without waste.

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

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

For a two-parameter wait tool with full schema coverage, annotations, and an output schema, the description covers the key behavioral points: blocking long-poll semantics, timeout, real-time inbound channel, and sender exclusions. No critical calling information 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 after cursor and timeout parameters are already documented in the schema. The description only indirectly references timeout behavior and does not add syntax or format details beyond what the schema provides.

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

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

The description gives a specific verb and resource: "Long-poll for the next ping." The blocking long-poll and real-time inbound channel framing clearly distinguish it from non-blocking notification siblings, though no sibling is explicitly named.

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 implies this is for waiting on inbound pings and states that human and self sends are excluded, but it does not explicitly contrast with get_notification, list_notifications, or other wait_for_* tools. The agent must infer when to use this blocking wait rather than a non-blocking fetch.

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