chat_receive

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries most of the load and does add meaningful traits: the one-shot claim semantics, a 16-message batch cap in v2, an ack-by-delivery_id requirement, and an explicit anti-polling constraint. It does not say what happens on a double-claim, on expired delivery_ids, or what the returned payload contains.

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?

Compact and rule-dense, with the one-shot claim constraint front-loaded and no filler sentences. The telegraphic Chinese phrasing and unexplained tokens ('v2', '旧协议', 'needs_review') cost some readability, but nothing is 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?

With no output schema, the description should describe the return shape (message list, delivery_id, context pagination token, needs_review field), but it only references those identifiers without explaining how they come back. Combined with the missing required-parameter explanation, an agent can form the workflow but not the data contract.

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 67% and the description says nothing about any of the three parameters — the required 'room' is documented only by a regex pattern, and neither 'server' nor 'session_id' is mentioned despite session_id's 'must be reused across all calls' rule being critical. The description's only 'parameter' content is delivery_id and message ID, which are not even 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 concrete action plus resource: claim arriving messages once, with v2 batching up to 16 and legacy single-message behavior. The protocol split is informative, but the description never names which sibling performs the confirmation (chat_ack) or which tool 'context' refers to, so sibling separation is only implicit.

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 real operational rules: claim only once after a notification, never poll, paginate long messages via context before confirming, and verify needs_review items instead of auto-redoing them. It stops short of explicitly routing to named alternatives (chat_ack, chat_checkpoint, chat_context), so the agent must infer which tool implements each step.

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