user_telegram_web_auth_post

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

No annotations are provided, so the description carries the full burden and largely fails. It never states that this is an authentication/credential-issuing operation, what token or session it returns, whether the confirm:true preview gate applies (that fact only appears in the confirm parameter's own schema description), or what happens on invalid credentials. The only behavioral hint is the parenthetical about the two accepted credential formats.

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 text is short but most of it is boilerplate: a bare path, a Russian gloss, and two generated tag/spec lines ('Тег: Telegram bot', 'Спека: user') that carry no information an agent can act on. The one substantive clause (the credential-type parenthetical) is buried rather than front-loaded.

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?

This is a nested-body, zero-annotation, no-output-schema auth endpoint sitting among ~20 sibling auth tools. The definition does not give the agent enough to construct a request or choose this tool over its siblings — no body contract, no linkage to the init/start/callback steps, no statement of what success yields. Incomplete for the tool's complexity.

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 apply — but the description adds nothing about any parameter. It does not tell the agent what the request body should contain (the body object has zero defined properties in the schema, and the description does not compensate despite the parenthetical naming two credential encodings), and it does not relate confirm or user_id to this specific flow.

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 is essentially the raw endpoint signature 'POST /telegram/web/auth' plus a Russian gloss 'Авторизация через Telegram Login (OIDC id_token или legacy Widget)'. It identifies the resource (Telegram web auth) and the auth mechanism, but the verb reads as a restatement of the HTTP method rather than a stated action, and it does not distinguish itself from the many sibling auth tools (user_telegram_web_auth_init_get, user_telegram_web_auth_start_get, user_telegram_web_callback_get, user_telegram_webapp_auth_get).

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?

There is no when-to-use or when-not-to-use guidance. The gloss mentions two credential forms (OIDC id_token or legacy Widget) but never says which body shape triggers which path, nor how this endpoint relates to the sibling *_init_get/*_start_get/*_callback_get steps. The 'Тег: Telegram bot' / 'Спека: user' lines are generated metadata, not usage advice.

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