Find Telegram chat ids

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description deepens all of these: 'Nothing is consumed — no update offset is confirmed, so this cannot eat the bot's pending updates' explains the idempotency mechanism, and 'Free, 0 credits' adds cost behavior. The 24-hour retention window and webhook caveat are non-obvious behavioral traits disclosed 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 longer than average, but nearly every clause earns its place by preventing a real misinterpretation: membership vs. senders, the 24-hour window, the webhook empty-list trap, and the no-consumption guarantee. It is front-loaded with purpose and scoping before caveats. Minor verbosity such as the inline Telegram quote and 'whose absence means nothing at all' could be trimmed without loss.

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 must convey return semantics, and it does: the result is chat ids addressable by the bot. It covers the data source (updates in last 24h), the edge case (webhook configured → empty with explanation), side effects (none), and cost (free). For a one-parameter list tool with tricky domain semantics, 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 coverage is 100% — the single 'limit' parameter is fully described as 'how many recent updates to scan, 1–100 (default 100)'. The description references the limit ('STATE THE LIMIT') and ties it to the 24-hour recency window, adding mild context, but the schema already carries the semantic load. 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 opening sentence states a specific verb and resource: 'Find the chat ids this Telegram bot can be addressed by.' This clearly distinguishes the tool from siblings like post_to_telegram and the other list_* tools, and the title reinforces the same purpose without contradiction.

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 operational guidance: 'STATE THE LIMIT WHENEVER YOU USE IT,' explains what the tool is NOT ('NOT the list of chats the bot belongs to'), and tells the agent what to do in the channel case ('post to it by @username or numeric id anyway'). It also explains how to interpret the webhook empty-list case, which is direct when-to-trust guidance.

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