Check free public Telegram search quota

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

Annotations already mark this readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: token expiry in five minutes, the consent gate, that returned scope includes channels the user has not joined, and an explicit warning not to assume a fixed 10-attempt quota. No behavior is hidden and nothing conflicts with 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?

Purpose is front-loaded and every clause is informative, but the description doubles as an agent policy playbook (what to tell the user, when to wait), making it longer than a pure tool description needs to be. The density is justified by the consent-critical workflow, but it could shed a sentence or two.

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 an output schema present, the description needn't enumerate return fields, yet it usefully interprets is_current_query_free and the remaining/daily count. Given the multi-step, consent-gated nature of the tool and the rich annotations, the description covers everything an agent needs to call it and hand off to the search tool correctly.

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 0% for the single 'query' parameter, so the description must carry the semantics, which it partially does: the value must be the exact proposed query and it determines whether is_current_query_free holds (i.e. it drives whether a new slot is consumed). It does not restate the min/max length bounds, but the meaning of the parameter in the flow is clarified well beyond the bare 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?

The opening sentence gives a specific verb and resource ('Check the linked account's live free quota') and explicitly scopes it versus the sibling search tool by noting it does so 'without performing a public search'. An agent can distinguish this from telegram_search_public_posts without opening either 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?

It states the precondition (first search accessible account history), the exact call pattern (pass the exact proposed query), the required human-in-the-loop step (ask and WAIT for explicit consent), and the sequencing into telegram_search_public_posts via confirmation_token/user_confirmed. It also defines re-invocation conditions (new query or changed quota requires a fresh check) and prohibitions (no paid search, Stars, or automatic retry).

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