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

The description goes well beyond the annotations by disclosing async behavior via requestId, the polling lifecycle, the manage_broadcasts requirement, no side effects on Telegram content, a 60-second deadline, shared read limits, persistent flood cooldowns, sponsored-ad caching, and that returned content must be treated as untrusted data. This is rich behavioral context that annotations alone do not provide.

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?

Every sentence earns its place. The description is front-loaded with the core purpose, then flows logically through schema lookup, return/polling behavior, permissions, safety, constraints, and data trust. It is dense but not bloated.

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 tool with no output schema, it fully describes the response pattern (requestId + polling) and all operational constraints: concurrency, deadline, rate limits, cooldowns, caching, and data trust. The nested input object is handled by directing the agent to the authoritative sibling tool rather than duplicating schema content.

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?

The schema already documents applicationId thoroughly and input partially. The description adds the key semantic pointer: 'Call list_telegram_operations for the input schema' and warns that only documented fields are accepted. This compensates for much of the missing parameter context, though botId remains undocumented in both the schema and the description.

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 clearly states the action: 'Submit one supported read operation on the connected telegram_mtproto account.' It names the resource, the read-only nature, and the supported operation set via the schema enum. It also distinguishes itself from siblings by pointing to list_telegram_operations for input schema and get_telegram_operation for polling.

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 gives explicit usage instructions: call list_telegram_operations for the input schema, submit one operation, then poll get_telegram_operation until completed, error, or timed_out. It also states the required permission (manage_broadcasts) and account-level constraints, so an agent knows how and when to use the tool correctly.

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