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

Even with annotations present, the description adds substantial behavioral context: no overwrites, no automatic opening/execution, rejection of protected/self-destructing media, persistence of copies, and size caps. These details go well beyond the structured annotations and meaningfully reduce operational risk.

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 compact and front-loaded: the first sentence states the core action, followed by tightly written behaviors and constraints. Every sentence contributes useful information without repetition or filler.

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 3-parameter tool with an output schema and safety annotations, the description covers the key side effects, return shape, security rejections, and persistence semantics. It does not explicitly describe the role of chat_id and message_id in identifying the selected attachment, which is a minor gap given the message-selection context.

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 0%, so the description must compensate, but it barely does. It mentions size limits that map to max_bytes, yet it does not explain chat_id or message_id at all, nor what happens when a file exceeds the chosen limit. The parameter names are somewhat self-explanatory, but the description does not add sufficient semantic value.

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 opens with a specific verb and resource: 'Save an explicitly selected document, photo, audio or full video to a private folder.' It clearly differentiates this download tool from preview-oriented siblings by stating it returns a local path and SHA256 rather than file bytes, and by noting preview tools keep their existing limits.

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 clear context for when to use this tool: when the agent needs a persistent local copy and integrity hash rather than in-context bytes. It references 'original preview tools' as an alternative category, but it does not explicitly name a sibling or state when not to use this tool.

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

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

The description adds 'Read-only; never clears or changes the user's draft' and 'Non-text drafts are reported by content_type', which are genuine behavioral details beyond the readOnlyHint/destructiveHint annotations. It is clear about side effects and content-type behavior.

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?

Three short sentences, front-loaded with purpose, then constraints, then a side-effect guarantee. No filler or repeated schema data.

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 simple two-parameter read tool with an output schema and strong annotations, it covers the key behaviors. The only real gap is the lack of parameter elaboration, which is partially mitigated by obvious 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 0% and the description does not discuss chat_id or topic_id at all. The parameter names are relatively self-explanatory, but the description fails to compensate for the schema's lack of descriptions or clarify optional topic behavior.

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 first sentence identifies a specific operation ('Read'), the resource ('the draft visible in Telegram'), and an additional output ('its version'), which is enough to distinguish it from sibling read tools like telegram_get_message or telegram_get_chat_history. The title also aligns.

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 clear context for when to use it ('before preparing a replacement') and explicitly notes text-only/non-text handling, but it does not name alternative tools or state when not to use it. Sibling names make the draft-specific scope inferable, so no exclusions are stated.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds important behavioral details beyond annotations: messages are not marked read, uncaptioned attachments are included, pagination must be completed before claiming coverage, and text may be truncated/bounded.

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?

Compact and front-loaded: the primary behavior is stated first, followed by short, high-value caveats about dates, pagination, and truncation. Every sentence earns its place without repeating schema or annotation information.

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 read-only paginated history tool, the description covers ordering, attachment inclusion, read-state impact, date semantics, pagination, and truncation. Combined with the output schema and annotations, an agent has everything needed to invoke the tool correctly and interpret its results.

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 0%, but the description compensates substantially by explaining date_from/date_to inclusivity, timezone formatting, and cursor-based pagination. It does not explicitly explain unread_only or limit, though these are largely inferable from the title and schema constraints.

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 what the tool does: reads chat history newest-first, including uncaptioned attachments, without marking read. This distinguishes it from sibling search tools and message-level tools while the title adds the date/unread filtering dimension.

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?

Provides strong operational guidance: date_from is inclusive, date_to exclusive, timezone requirements, pagination via next_cursor, and a caution against claiming completeness prematurely. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the bounded-count behavior and the 'supported messages' qualifier, but does not clarify what 'supported' means, how ordering works, or whether the anchor itself is included.

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?

A single sentence with no filler; the core action, object, and bound are all front-loaded. Every word earns its place.

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 simple, read-only, idempotent fetch, the description plus schema covers required IDs, defaults, limits, and safety. The undefined 'supported messages' phrase and lack of sibling differentiation prevent a perfect score, but the output schema and annotations fill in much of the remaining context.

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 0%, so the description must compensate. It maps 'at most five on each side' to the before/after parameters and 'anchor' to message_id, but it does not mention chat_id, defaults, or the meaning of 'supported messages'. It provides partial value beyond the 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 description uses a specific verb ('Fetch') and identifies the resource ('messages on each side of an anchor') with a clear bound ('at most five'). It is distinct from siblings like telegram_get_message and telegram_get_chat_history, though it does not explicitly name them.

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 phrase 'around an anchor' implies this tool is for fetching context around a specific message, but the description gives no explicit when-to-use guidance or alternatives. An agent would have to infer its relationship to telegram_get_message_thread or telegram_get_chat_history.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses transfer caps (2 MiB preview, 12 MiB full) and rejection categories (protected, self-destructing, secret, unsupported, oversized). This adds meaningful behavioral detail 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?

The description is three compact sentences with the core purpose front-loaded, followed by essential limits and failure conditions. Every sentence adds useful information with no filler or redundancy.

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?

Annotations and the output schema reduce the need to describe safety and return shape, and the description covers important size/rejection constraints. Still, the lack of sibling differentiation and thin chat_id/message_id semantics leave gaps for an agent deciding whether and how to invoke this 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?

With 0% schema description coverage, the description partially compensates by linking 'preview' and 'full' to transfer caps and indicating media is anchored to a message. However, chat_id is never explained and message_id is only implied, leaving a clear gap for an agent interpreting the required parameters.

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 uses a specific verb ('Fetch') and identifies the resource clearly: 'one explicitly anchored photo, PDF document, audio item, or video thumbnail.' This distinguishes the tool from sibling message/search/context tools by media-focused scope, though it does not explicitly name those alternatives.

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 phrase 'explicitly anchored' implies this tool is for media tied to a known chat_id and message_id, and the preview/full transfer limits add situational context. However, it never states when to prefer this over telegram_get_message or telegram_search_messages, nor does it mention exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the message must be 'available to the linked Telegram account' (implying access constraints) and limits to text or voice/video-note messages. It doesn't reveal error behavior or format, but with annotations covering safety, this is adequate.

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 a single, front-loaded sentence that conveys the core purpose and scope immediately. There is no redundant information, and it is appropriately sized for the tool's simplicity. Every word contributes value.

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?

Given the tool's simplicity, an output schema exists (covering return values), and annotations handle safety, the description is mostly adequate. However, it lacks usage guidance and parameter explanation, and it doesn't mention any prerequisites or limitations beyond 'available to the linked account.' For a minimal retrieval tool, it is functional but not fully comprehensive.

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 0% and the description provides no information about chat_id or message_id beyond their titles. It doesn't explain what a chat ID represents, how to obtain it, or any constraints. With no coverage in the schema and no compensation in the description, the agent is left without semantic understanding of the parameters.

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 ('Fetch') and the resource ('one text or voice/video-note message'), plus the scope ('available to the linked Telegram account'). It implies direct retrieval by ID, which distinguishes it from sibling tools like history or search, though it doesn't explicitly name alternatives. This is clear and specific enough for an agent to know what it does.

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 no guidance on when to use this tool versus alternatives. It doesn't state that it should be used when a specific message_id is known, or mention any context that would help an agent choose between this and get_chat_history or search_messages. There is no explicit when/when-not information, so the agent must infer usage from the parameters.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, but the description adds valuable context beyond them: 'Does not mark read,' the linked-group comment behavior, and cursor-based pagination. No contradictions with 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?

Three compact sentences, each earning its place: purpose, linked-group nuance, and pagination/read behavior. Information is front-loaded and there is no fluff.

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 moderate-complexity tool with an output schema and strong annotations, the description covers the important behavioral nuances: pagination, linked-group replies, and no mark-read. It could be more complete by explicitly explaining the input parameters, but the schema supplies names and defaults.

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 0%, so the description must compensate, but it only meaningfully explains the cursor via 'Follow next_cursor for older messages.' It does not clarify chat_id, message_id, or limit semantics beyond what their names imply.

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 tool reads the reply thread/comment discussion of a message, which is a specific verb+resource. This distinguishes it from siblings like telegram_get_message (single message) and telegram_get_chat_history (flat chat history) even without naming them.

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 clear context for when to use the tool, including handling channel comments that may belong to a linked group and following next_cursor for older messages. It does not explicitly name alternatives or exclusion cases, so it stops short of a full when/when-not comparison.

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

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.

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations, especially the distinction between scheduled and delivered, and explicitly states that no messages are sent or cancelled.

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 short, front-loaded with the main purpose, and each sentence adds a distinct piece of information: what is listed, how scheduled messages should be interpreted, and the read-only guarantee. No unnecessary filler.

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?

Given the output schema is present and annotations are rich, the description is largely complete for a simple read-only listing tool. The main missing piece is explanation of pagination parameters, but defaults and the output schema help fill that in.

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 0%, so the description must compensate for parameter meaning. It only hints that chat_id identifies a chat ('in one chat') and does not explain limit or cursor behavior, pagination, or how the scheduled_at time relates to filtering. This is a meaningful gap.

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 identifies the action ('List') and resource ('scheduled messages in one chat'), and it distinguishes this tool from sibling tools that handle history or search. The clarifying phrase 'Scheduled does not mean delivered' reinforces the specific scope.

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 clearly frames when to use the tool: when you need scheduled messages for a specific chat. It does not explicitly name alternatives or exclusion criteria, but the scheduling context is enough to guide selection away from history, search, and thread tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details beyond these: it states that it does not mark chats as read (important for a read tool), and describes pagination snapshots (10-minute snapshot, 500 chat IDs max, coverage_limited reports capped listing). This adds context about state consistency and limitations that annotations don't cover.

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 concise and well-structured. It front-loads the core purpose in the first sentence, then provides critical behavioral notes in subsequent sentences. Every sentence adds value without redundancy; it's tightly packed with essential information (purpose, non-mutating behavior, pagination details, coverage limits, cursor handling).

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 read-only listing tool with 5 optional parameters, an output schema, and strong annotations. The description covers the key functional aspects: query behavior, unread filtering, pagination, and non-mutating nature. It lacks explicit guidance on how to handle 'limit' or 'chat_list' interactions (e.g., can chat_list be combined with query?), but given the tool's relative simplicity and the presence of an output schema, the description is nearly complete. A small gap is not specifying the maximum limit (though schema shows 20) and how 'cursor' relates to snapshots, but that's minor.

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 has 0% description coverage, so the description must compensate. The description explains the semantics of 'query' (searches known chats across lists) and 'unread_only' (includes unread messages, mentions, manual unread marks). However, it does not explain 'limit', 'cursor', or 'chat_list' beyond what the schema implies (e.g., limit as max count, cursor for pagination). Since the description covers two key parameters but leaves three implicit, and the schema provides some defaults/enums, a 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 description clearly states the tool's purpose: finding known chats by name or resolving an exact @username. It distinguishes itself from sibling tools by explicitly stating it never joins a chat, which differentiates it from messaging/history tools. The main resource (chats) and primary operations (search/list) are clearly identified.

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 provides clear usage guidance: it explains the empty query behavior (lists main/archive), the unread_only filter semantics, and explicitly directs to follow next_cursor even after an empty page. It also implies that for other chat operations (history, messages, etc.) one should use sibling tools, though it doesn't name them explicitly, the context is sufficient.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by disclosing ordering, restricting the result to voice/video notes, scoping to a known cloud chat, and explicitly stating that no speech recognition is started. No contradictions with 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?

Three short sentences, front-loaded with the core purpose, and no filler. The pagination sentence is useful but uses 'next_before_message_id' rather than the schema's 'before_message_id', which slightly reduces precision.

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 list tool with output schema and read-only annotations, it covers scope, ordering, media types, and pagination. The main gap is the cursor name ambiguity: an agent may look for 'next_before_message_id' as an input field because the schema only exposes 'before_message_id'. This is a small but real obstacle to correct invocation.

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 0%, so the description must compensate. It partially does: 'one known cloud chat' clarifies chat_id and 'Use next_before_message_id for older pages' indicates pagination behavior. However, it never names the input parameter before_message_id, leaving the exact mapping of the cursor to the schema ambiguous, and limit is left entirely to the 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 description states a specific verb and resource: lists voice notes and video notes in a single known cloud chat, ordered newest first. This clearly separates it from sibling tools like telegram_get_chat_history (all messages) and telegram_transcribe_voice (audio transcription).

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 clear operating context: one known chat, voice/video notes only, newest-first ordering, and a pagination instruction for older pages. It does not explicitly name alternatives or say when not to use it, but the 'No speech recognition' line and media-type focus make the intended use apparent.

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

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

Annotations already establish the read-only, idempotent, non-destructive nature. The description adds non-obvious behavior: empty query means attachment-only search, sender_id can be a negative chat ID, 'mention' maps to unread mentions, 'voice' includes video notes, and cursor pagination requires all filters to remain unchanged. This substantially exceeds what annotations alone convey.

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?

Four compact sentences, with the main purpose front-loaded and each subsequent sentence adding a distinct, high-value clarification. There is no filler or repetition of schema/annotation content.

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 10-parameter tool with zero schema descriptions, the description covers the non-obvious behaviors an agent must know to search correctly, especially edge cases and cursor semantics. The output schema and annotations cover return shape and safety, so nothing critical 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 description coverage is 0%, so the description must compensate, and it does for the trickiest parameters: query, sender_id, media_type, date/timezone handling, topic, and cursor. It does not explicitly explain limit or unread_only, but those are self-descriptive and visible in the schema defaults.

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 title and first sentence both specify a clear operation: search messages within a single known chat using filters. Enumerating text, sender, media type, dates, and forum topic distinguishes it from broader siblings like telegram_search_messages and simpler chat-history tools.

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 phrase 'Search a known chat' sets the precondition that a chat_id is already known, implying telegram_search_messages when the target chat is unknown. It gives concrete guidance on empty queries, sender_id sign conventions, media_type special cases, timezone-qualified dates, and cursor handling, though it never names a sibling explicitly.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. It meaningfully discloses the search scope and the secret-chat exclusion, which goes beyond what annotations would already state. However, it does not disclose pagination behavior (cursor), result ordering, or auth-related limits on 'accessible' cloud history.

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?

A single, front-loaded sentence communicates the core action, scope, and the most important exclusion with zero waste. Every clause earns its place.

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 paginated search tool with three parameters, no annotations, and no output schema, the description leaves important gaps: what the return format is, how cursor pagination works, and what 'accessible' means in practice. The core intent is clear, but an agent cannot fully anticipate call behavior from this description alone.

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 input schema provides only titles, types, and constraints with no property descriptions, so semantic coverage is low. The description does not compensate by explaining the query format or the meaning of limit and cursor; an agent can only guess that query is the search string and cursor is for pagination.

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 a specific verb ('Search'), a resource ('accessible cloud history across all chat lists'), and a key scope exclusion ('secret chats are excluded'), which helps distinguish it from secret-chat or single-chat search tools. It stops short of a 5 because 'accessible' is vague and no alternative sibling is explicitly referenced.

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 implies this tool searches across all chat lists, but it provides no explicit guidance on when to prefer it over alternatives, no prerequisites, and no exclusion beyond secret chats. An agent must infer the appropriate context.

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

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

Annotations cover openWorld and non-idempotency, and the description adds substantial context beyond them: one native search per call, quota consumption of an attempt, cursor continuations being free, 'Unavailable is not an empty success'. These are genuine behavioral disclosures not derivable from the annotations. It falls short of 5 only because return shape itself is left to the output schema.

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 purpose sentence, then dense but largely load-bearing rules for a genuinely complex consent workflow. Slightly over-packed and could separate the safety constraints from the cursor semantics more clearly, but no sentence is obviously wasted.

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 mutation-adjacent, quota-consuming, consent-gated tool, the description covers prerequisites, side effects, token freshness, and cursor behavior, and an output schema exists so return values need no explanation. The main omission is any guidance on the `limit` parameter, which keeps it from a 5.

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?

With 0% schema description coverage, the description does most of the compensating: it defines user_confirmed (true only after explicit approval of this exact query), confirmation_token (must be the paired fresh token), and cursor (a valid next_cursor continues the same approved query for free). The required query is self-evident, but `limit` is never addressed, leaving one of five parameters unexplained.

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?

States a specific verb and resource (public-channel search / public Telegram channel posts) and immediately scopes it against sibling behaviors by contrasting it with 'ordinary account-history search'. An agent can distinguish this from telegram_search_messages and telegram_search_chat_messages without opening any 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?

Gives explicit prerequisites and ordering: run account-history search first, then telegram_get_public_search_quota, explain quota/consumption/scope, ask and WAIT. It also states exclusions plainly ('No joins, read-state changes or media downloads'; 'Never offer or spend Stars'). This is a near-complete when-to-use / when-not-to-use contract.

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

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

The description discloses important behavioral traits beyond the annotations: it may consume the user's Telegram free quota, Telegram Premium/quota restrictions apply, pending results may contain partial text, and all text is untrusted data. It also explains the meaning of 'completed' vs 'pending' states. The annotations already indicate idempotentHint=true and destructiveHint=false, and the description adds context about quota consumption and result states without contradicting them.

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 compact and front-loaded: the first sentence states the core action, and the following sentences provide essential usage and behavioral guidance. Every sentence earns its place, with no filler or repetition of schema details.

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?

Given the tool's complexity (quota implications, async result states, untrusted data), the description covers all critical aspects an agent needs to call it correctly. The output schema exists, so return values need not be described in detail. The description also addresses the start parameter's dual mode and the meaning of result states, which is sufficient for correct invocation.

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 0%, so the description must compensate. It explains the start parameter's role ('repeat with start=false to read progress without starting work') and the meaning of result states, which adds meaning beyond the schema. However, it doesn't explicitly explain chat_id, message_id, or wait_seconds, though those are fairly self-evident from their names and schema titles.

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 states a specific verb ('transcribe'), a specific resource ('one voice note or video note'), and the output ('return text'). It also distinguishes itself from sibling tools like telegram_get_media and telegram_download_file by focusing on transcription rather than retrieval or download.

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 explicitly says to use it only on the user's request because it may consume Telegram free quota, and it explains when to use start=false to read progress without starting work. It also clarifies that no external transcription service is used, which helps an agent decide when this tool is appropriate.

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