telegram_watch

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds what they cannot: the call blocks and holds the account exclusively for the duration, empty results at the timeout ceiling are a success not an error, policy-refused chats are silently omitted rather than reported as suppressed, and reads never mark seen. These are exactly the non-obvious traits an agent must plan around.

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 core blocking behavior, and most sentences carry distinct gotchas. There is mild redundancy: the account being held is stated twice ('holds the account until it returns' and 'the account's session is held for the duration of the wait'), which slightly dilutes an otherwise tight narrative.

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 blocking long-poll tool with no output schema, the description covers the failure modes an agent would otherwise stumble into: timeout semantics, empty-result-as-answer, silent policy filtering, and session exclusivity. Nothing an agent needs before invoking it 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 and the per-parameter descriptions already document each field. The description goes marginally further by explaining the interaction between debounce_sec and the burst model ('replies that land within debounce_sec of each other wake the caller once'), which the schema states only per-field.

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 (blocks/wait) plus resource (message in a permitted chat) and the burst-handling semantics that make wake-once behavior concrete. It explicitly separates itself from telegram_inbox and telegram_chat_read, so an agent can pick it without opening any sibling 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?

Gives an affirmative use case ('when the user wants to wait for the next message instead of asking again') and an explicit exclusion with named alternatives ('Do not use this to look at what already arrived; call telegram_inbox or telegram_chat_read'). The routing decision is fully resolved in the text.

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