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

Goes well beyond the readOnly/idempotent annotations by disclosing the long-poll shape, the presence side effect ('the widget shows the business as online'), the 60s fast-return when nobody is online, and that the call is free. The presence change is a real behavioral trait the annotations do not capture; only the exact response payload remains undisclosed.

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

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

The core behavior is front-loaded in the first clause and every clause carries information (loop mechanics, presence side effect, webhook alternative, cost). It is dense with nested parentheticals, which makes it slightly harder to parse than it needs to be.

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 no-required-parameter long-poll tool with no output schema, it covers the calling loop, timing, side effects and the server alternative. The one substantive omission is a description of the returned payload (message fields, the next_after/call_again_in_seconds values) since no output schema documents them.

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 50%: 'after' is documented in the schema while timeout_seconds is not, and the description does give timeout_seconds meaning plus the intent of 'after'. However it introduces two fields, next_after and call_again_in_seconds, that appear nowhere in the schema and there is no output schema to define them, leaving the agent guessing about the return shape.

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: it listens for visitor chat messages and returns when a visitor writes or the timeout elapses. It also carves out a scope boundary against the server-side webhook approach, though it never names a concrete sibling such as chat_list_conversations or chat_get_conversation as an 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?

Gives explicit operating instructions (pass next_after as after, re-call after call_again_in_seconds) and an explicit when-not-to-use: 'A server should subscribe a webhook to chat.message_received instead.' It stops short of routing the agent between the sibling chat tools, which is the remaining gap.

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