Telegram

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds meaningful context the annotations cannot: a per-resource credit cost, the fact that failures are free, the result reporting charged and remaining credits, and that max_age_days trades freshness for zero cost. It does not cover auth requirements or freshness guarantees beyond the cache window.

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 dispatch rule, followed by a scannable bulleted resource list with costs and a paging note. Every sentence carries operational information; the only looseness is the opening inventory of data types that doesn't exactly match the available resources.

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 multi-resource dispatcher with no output schema, the description covers the essentials: how to dispatch, how to page, how billing works, and how to get free cached results. It stops short of describing what a channel or post result contains, leaving the agent to infer the payload shape from the resource names.

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 a baseline of 3 would be defensible. The description earns one point above baseline by mapping each resource to the identifier it accepts (handle|url), clarifying that `params` holds per-resource extras, and attaching cost to each resource, which the schema does not express.

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 the platform and enumerates the three concrete resources (channel, channel.posts, post) with the identifier each takes, so an agent can tell it apart from sibling platform tools like youtube or twitter. The opening line is slightly looser than the resource list ('communities and groups, posts and videos'), since no group or video resource actually exists in the enum, but the enumeration that follows resolves the ambiguity.

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 states the invocation pattern clearly: choose a `resource`, pass that resource's parameters as top-level arguments, extras in `params`, and pass `cursor` back unchanged for pagination. It does not name any sibling alternative (get_post, search, get_profile) or say when to prefer this tool over them, which keeps it below a 5.

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