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

The annotation declares idempotentHint=false, but the description says 'A duplicate acknowledgement is safe,' which implies idempotent behavior and directly conflicts with the annotation. Although it adds useful atomicity and old-ID constraints, the contradiction is serious.

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 front-loaded with the core action and uses three compact sentences with no wasted wording. Each sentence adds either the main purpose, a precondition, or a safety constraint.

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 tool with no output schema, the description covers the main action, precondition, and key state constraints. However, it leaves the name parameter unexplained and contains an idempotency inconsistency against the annotations, so it is only adequately complete.

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 undocumented parameters. It hints at batch_id semantics via 'an old ID cannot acknowledge a newer pending batch,' but never explains the required name parameter or its relationship to the subscription being acknowledged.

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: confirming a processed batch and atomically advancing subscription positions. It clearly distinguishes this acknowledgement operation from read-oriented siblings such as get_watch_changes and get_changes.

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 explicitly says to acknowledge only after processing messages and omissions, which gives clear usage context. It also adds state constraints about duplicate acknowledgements and old IDs, though it does not explicitly name alternative sibling 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 only declare the safety profile (not read-only, not destructive, not idempotent, open-world), while the description supplies the substantive behavior: no scheduled/background polling, folder membership refreshed between passes, new members starting at the previous completed pass, positions persisting until explicit deletion, and a 35-second creation deadline with retry delays. 'Identical creation retries preserve positions' adds nuance beyond the annotations without contradicting idempotentHint=false, since it is retry semantics rather than full idempotency.

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 purpose and the source-selector constraint are front-loaded, and the remaining sentences are short, clause-per-line statements with little filler. It is dense with distinct facts, though the paragraph form makes some operational details (deadline, retry) easy to skim past.

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 creation tool with no output schema and four undocumented parameters, the description covers lifecycle (persistence until deletion), concurrency (shared clients, name scoping), limits (20 chat_refs, 100 folders implied), and failure handling (35-second deadline, retry delays). An agent has enough to invoke it correctly and set expectations about what happens afterward.

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 must carry semantics and largely does: date_from selects older history, folder_ids handles larger selections, chat_refs is capped at 20 with equivalent links resolving once, and name scoping determines sharing between clients. The only gap is the name format constraint (lowercase pattern), which is left entirely to the schema's regex.

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 (Create) and a precisely qualified resource: a named, on-demand subscription with exactly one source selector. That framing immediately separates it from sibling operations like list_watches, delete_watch, or get_watch_changes, which manage or read subscriptions rather than create them. The tool's role is clear without opening the 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 provides concrete selection guidance: 'Start now, or supply date_from for available older messages' and 'Use folders for larger selections' when chat_refs would exceed 20. It also explains the naming convention needed for independent consumers. It stops short of explicitly naming alternatives (e.g., list_watches to discover existing subscriptions, get_watch_changes to consume), so it is clear but not fully routing.

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 flag destructiveHint=true and idempotentHint=true, but the description adds real substance beyond them: what is destroyed (subscription, positions, unacknowledged batch), what survives (Telegram and permanent archive copies), and the recovery consequence (a recreated watch starts fresh coverage). This is exactly the kind of blast-radius disclosure a destructive tool needs.

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 short sentences, front-loaded with the action and its blast radius before the caveats. No filler, and the what-is-destroyed information comes first where an agent will read it.

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 one-parameter destructive tool with full annotation coverage and no output schema, the description covers the essential unknowns: persistence of data, recoverability, and scope of deletion. The only shortfall is how to obtain a valid watch name and whether the deleted watch can be restored from anywhere but the archive.

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?

There is one required 'name' parameter with 0% schema description coverage, and the description never mentions it — no guidance on where the name comes from (list_watches output), matching rules, or case sensitivity. With only a single self-evident parameter the gap is survivable, but the description adds no meaning over 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?

States a specific verb and resource ('Explicitly delete a subscription, positions and any unacknowledged batch') and even enumerates the sub-objects removed. This clearly separates it from create_watch, list_watches, and ack_watch_changes without needing to open the 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?

The phrase 'Explicitly delete' plus the note that 'Recreating a watch starts a new coverage interval' implies this is the terminal teardown action, and hints at create_watch as the re-entry path. However, no explicit when-to-use/when-not statement or named alternative (e.g. how to locate a valid name via list_watches) is given.

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 extensive behavior beyond annotations: returns a local path and ResourceLink without inline bytes, requires resources/read before expires_at, expires after 15 minutes or server shutdown, the path is on the server, and temporary failures require retrying with retry_after_seconds. It also clarifies no partial resume and current-vs-archived attachment semantics.

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 front-loads the core action and scope, then groups prerequisites, return behavior, expiry, retry behavior, and save semantics. Although multi-sentence, every sentence adds operational value for a tool with nontrivial download and expiry behavior.

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?

There is no output schema, so the description appropriately explains the return shape: local path and ResourceLink, no inline bytes, and use resources/read before expiry. It also covers permissions, exclusions, expiry, retry behavior, and save semantics, which is complete for this tool.

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 carry parameter meaning. It explains attachment_id as an explicitly selected attachments[].id that selects the current attachment rather than an archived version, and it explains save=true as retaining a permanent copy when archive_directory is configured.

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: downloading one explicitly selected attachment by attachments[].id, with a clear 20 MiB scope. It distinguishes the operation from selecting messages/albums and from interpreting attachment content.

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 explicitly states prerequisites (allow_attachment_downloads and ordinary source-read permission), how to select an attachment first via get_messages or get_album, and exclusions for protected and expiring media. It also explains save=true retention behavior.

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?

Discloses far more than the annotations: per-part limits (1000 records/20 MiB), RPC/time budgets, a 15-minute expiry on the returned resource, server-local temporary files, attachments as metadata only, omission of protected/expiring records, semantics of complete/omitted_count/issues, checkpoint survival across restarts, retry behavior on temporary vs tool errors, and absence of snapshot consistency. The readOnlyHint=false annotation is consistent with the described file-writing/archive 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?

Front-loads the action and then packs only operational facts with no filler. The telegraphic sentence fragments ('Upper date and ID are frozen', 'A non-null next_checkpoint survives restart') cost some readability but every line carries 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 complex paginated export with no output schema and no parameter descriptions, the description covers the mechanics an agent needs: pagination loop, resource expiry, error handling, and completeness signals. It leaves the concrete return shape (resource reference/URI) only implied by 'Read the returned resource explicitly'.

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 carry the load and largely does: it defines chat_ref, lower-inclusive/upper-exclusive dates, checkpoint continuation, format, and save as a permanent archive copy. It omits chat_ref's accepted form (ID vs username vs link) and save's default, keeping it short of a 5.

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: export one selected chat's original history as JSONL or Markdown, with file-based output. That distinguishes it from in-context readers like get_history or search_messages, though it never names a sibling explicitly.

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 a clear call sequence (start with chat_ref plus optional dates, then continue with checkpoint only) and notes save=true for a permanent archive copy. It never says when to prefer this over get_history/get_messages or what disqualifies it, so the when-to-use dimension is only implied.

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 annotations, it discloses result expiry (15 minutes or server shutdown), re-validation of access and attachment identity, that limit failures return no partial text, and the non-capabilities (no OCR, passwords, external URLs, permanent save). Adding an untrusted-content warning is meaningful behavioral context that annotations cannot express.

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 core selector rule is front-loaded and each clause carries operational weight (offset semantics, expiry, DOCX/PDF coverage differences). It is dense but slightly long, with several constraints packed into a single block that could be split for scanning.

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 no output schema, the description still communicates the important return semantics: next_text_offset in Unicode code points, one-based physical PDF page_spans, DOCX body/table coverage, and an issues field for omissions. Only the top-level response shape (e.g., the text field itself) is left implicit.

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 does for attachment_id and extraction_id (offset behavior, immutability) and relates Unicode code points to offsets. However, text_limit and text_offset are never explicitly explained—no mention of the 24000 maximum, default 12000, or that text_offset is the continuation cursor paired with next_text_offset.

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 names a specific verb and resource ('Extract local text from one selected PDF or DOCX') and covers both operating modes: fresh extraction versus resuming a saved one. It also draws the boundary against the sibling download_attachment by stressing it reads text 'without downloading or parsing again'.

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 an explicit exclusivity rule ('Supply exactly one selector') and explains what each selector implies: attachment_id starts at offset 0, extraction_id reads an immutable result. Prerequisites (allow_attachment_downloads, source access, [extraction] extra) and the terminal condition ('Follow next_text_offset until null') make the usage path unambiguous.

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?

Although the annotations already declare readOnlyHint and openWorldHint, the description adds substantial behavioral detail that the annotations do not cover: completeness is always 'unknown' because Telegram provides no album manifest, exhaustion fields describe history boundaries rather than album completeness, there is no cursor, text budgets apply, and explicit public channels require read permission. It also documents error semantics (MESSAGE_UNAVAILABLE, NOT_AN_ALBUM), partial results with issues, and retry via retry_after_seconds. This is far more than the annotations 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 purpose is front-loaded in the first sentence, and the remaining sentences are dense with operational facts rather than filler. The text is long and reads as a series of terse fragments (for example, 'There is no cursor.' and 'Initial access/anchor failures are errors.'), which is efficient but slightly clipped for an agent parsing the meaning of return values.

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 two-parameter read tool with no output schema, this description is essentially complete: it covers anchor resolution, scan semantics, ordering (oldest_first), completeness caveats, error codes, partial-failure behavior, retry guidance, permission requirements, text budget handling, and explicit non-goals. Nothing an agent needs in order to call this tool correctly 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 has to carry the full burden, and it does. It spells out the three accepted forms of ref (URL, 'chat_id:message_id', or {chat_id, message_id}), which the anyOf schema alone does not disambiguate. It also explains that scan_limit scans that many messages on each side, which resolves the key ambiguity left by the bare integer with default 30 and maximum 100.

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: 'Read messages from one album around a member's Telegram URL or message reference.' That is distinct from the sibling tools get_messages, get_context, and get_thread, because 'album' is a clearly bounded resource, and the description reinforces the difference by naming get_messages as the fallback for truncated text.

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 says when to use this tool (you have an anchor message that belongs to an album) and names an alternative for one specific situation ('use get_messages with next_text_offset for truncated text'). It also lists exclusions: no linked discussions, no attachment downloads, no marking read. It never explicitly contrasts this tool with get_context or get_thread for neighboring-message retrieval, so the guidance is clear but not exhaustive.

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 only give the coarse profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description adds substantial context beyond that, including that only the last 100 messages are rechecked, that intermediate edits and deletions are unrecoverable, that 'unavailable' does not prove deletion, that retries may produce duplicate revisions, and that checkpoints expire after 30 days. It also discloses that non-inline output writes a temporary file/resource and that no binary attachments are downloaded.

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 first sentence front-loads purpose and the remainder is densely packed with operational facts, most of which earn their place. The fragmentary sentence-per-clause style is terse to the point of being choppy, but there is little outright 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 polling tool with no output schema and five undocumented parameters, the description covers the important contract: the complete/next_checkpoint loop, token reuse safety, retention limits, and output modes. What is missing is the shape of the returned change records and the meaning of limit, so it is strong but not fully self-sufficient.

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 carry parameter meaning, and it largely does: chat_ref as baseline establishment, checkpoint as the continuation token from next_checkpoint, output=jsonl/markdown as a file/resource mode, and save=true as retention in archive_directory. The limit parameter (1-100, default 30) is never explained, leaving one real 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 opens with a specific verb and resource: 'Poll one selected chat for new messages and available recent revisions.' That is far more informative than the name alone and implies incremental/delta semantics. It doesn't name a sibling for contrast (e.g. get_watch_changes or get_messages), so differentiation is left to inference.

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 a concrete operational sequence: 'Supply chat_ref only to establish a baseline... Then supply checkpoint only,' which is genuinely useful for correct invocation. However, it never states when to pick this tool over get_messages, get_history, or get_watch_changes, so tool selection against siblings remains implied.

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 and openWorldHint, so the safety profile is covered, and the description adds genuinely new context: allowlist gating and the allow_public_channel_reads flag for public channels. It does not describe the returned metadata fields, which keeps it from a 5.

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, the primary purpose is front-loaded, and every sentence adds a distinct fact (accepted formats, allowlist gating, ID resolution). No 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 single-parameter read tool with no output schema, the definition covers input formats and access constraints well. What 'chat metadata' contains is left implicit, but nothing required to invoke the tool correctly 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 coverage is 0%, so the description carries the full burden, and it does: chat_ref accepts a numeric ID, an exact @username, or a t.me[/s]/username URL. That is exactly the missing meaning an agent needs to construct a valid argument.

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: 'Read permitted chat metadata', and confines scope to metadata (not messages or history), which separates it from siblings like get_messages or search_messages. It never names a sibling directly, so it stops short of the top score, but an agent can tell 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?

Gives real usage conditions: public channels outside the allowlist need allow_public_channel_reads, and unknown numeric IDs may need resolving via username or URL first. It does not compare against alternatives such as list_chats or search_public_channels, so there are no explicit exclusions.

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 annotations already establish readOnlyHint and openWorldHint, so safety is covered. The description adds useful access/breadth context via the server access policy and the bounded parent-reply chain, but it does not clarify ordering, pagination behavior, or edge cases.

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, with the core purpose and alternative front-loaded. Every sentence adds value and there is no wasted repetition.

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?

The description covers the high-level return composition (message, neighbors, parent replies) and sibling routing, which is useful given there is no output schema. However, for a 4-parameter tool with zero schema description coverage, it omits how to supply ref and how after, before, and reply_depth affect the result.

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 description only alludes to the message ref, chronological neighbors, and bounded reply depth; it never names after, before, or reply_depth, nor explains accepted ref formats or the meaning of the bounds. With 0% schema description coverage, this leaves most parameter semantics undocumented.

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 set: read a message, its chronological neighbors, and a bounded chain of parent replies. It also distinguishes this from get_thread, so an agent can tell they are different tools 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 explicitly frames the tool as temporal context and names get_thread as the correct alternative for all comments/replies in a discussion. That gives a clear when-to-use-this versus when-to-use-another signal.

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 readOnlyHint and openWorldHint, the description discloses many behavioral details: half-open date range, default ordering/max_sources/max_messages, SOURCE_LIMIT_EXCEEDED before reading, budget/exhausted cursor semantics, ordering=global synchronization, forum access requirements, allowlist requirements, and retry_after_seconds handling. These are substantial operational disclosures not present in 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?

The description is front-loaded with the core operation and then organized around selector rules, pagination, topics, and access constraints. It is dense but mostly earns its length given the 13-parameter complexity, though some sentences are run-on and could be tighter.

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 history tool with no output schema, the description covers the critical invocation behaviors: selector exclusivity, date requirements, pagination, limits, error conditions, topic access, and public-channel access. Remaining gaps around limit/order semantics and full return-shape expectations keep it from being complete.

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 across 13 parameters, the description must compensate. It explains most important selectors and controls (chat_id/chat_ref/chat_ids/folder_ids, dates, ordering, topic_id, max_sources, max_messages, cursor follow-up), but it omits limit and order entirely and uses 'next_cursor' while the schema parameter is 'cursor'.

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 states a specific verb and resource: read history over a date range, or recent chat messages when dates are omitted. It clearly describes the tool's scope, but it does not explicitly differentiate it from sibling tools such as search_messages or get_messages.

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 detailed usage constraints: supply exactly one chat selector, multi-source reads require both dates, topic_id is only for a single chat, and public channels need allow_public_channel_reads. It does not explicitly name when to prefer this tool over sibling search or message-retrieval tools, leaving that to inference.

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/openWorldHint, and the description adds substantial behavior beyond them: metadata is pulled from the payload without extra requests, previews are not fetched externally, voter/reactor identities are not resolved, missing messages surface as per-item issues, and order/duplicates are preserved. This is exactly the kind of side-effect and access detail an agent needs.

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 call signature and accepted inputs, followed by return contents and then edge cases. Dense but nearly every sentence carries a distinct fact; the telegraphic 'has_link is independent of content_type' and 'Polls retain content_type="other"' lines are cryptic out of context.

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 no output schema, the description steps in to enumerate return contents (authors, reply refs, attachments, links, counters, reactions, polls, previews) and error shape (per-item issues with zero-based input_index). Combined with truncation and permission notes, an agent can call and interpret this 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%, so the description must carry the load; it does well by explaining the non-obvious string forms of 'refs' that the schema leaves untyped. However, text_limit is never mentioned and the offset parameter is referred to as 'next_text_offset' rather than the actual name 'text_offset', creating a slight naming mismatch.

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 ('Fetch') and resource ('posts'), and immediately enumerates the three accepted reference forms (URL, 'chat_id:message_id', {chat_id, message_id}). This exact-reference retrieval is clearly separable from the sibling search_messages 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?

Gives clear situational guidance: 'For truncated text call again with next_text_offset', and access conditions for public channels outside the allowlist and linked discussions. It never names search_messages as the alternative for discovery-type queries, so there are no explicit exclusions.

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 readOnlyHint/openWorldHint it discloses authorization nuances (forum topics need ordinary access; public-channel permission does not authorize forum groups), pagination mechanics (follow next_cursor with the same chat_ref and topic_id, respect retry_after_seconds), and the consistency caveat that pin membership can change during traversal. It also states explicitly that nothing is pinned, unpinned, or marked read, which reinforces rather than contradicts 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 in the first clause, and each subsequent sentence covers a distinct concern (topic scoping, access policy, pagination/retry, mutation guarantee) with no filler or repetition. The length is justified by the number of real behavioral constraints.

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 traversal tool with no output schema, the description covers ordering, scoping, access prerequisites, cursor recovery, transient-failure handling, and side-effect guarantees — everything an agent needs to call it correctly and to interpret a mid-traversal shift in 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?

With 0% schema description coverage the description carries the load, and it does so for chat_ref (ID, @username, t.me link), topic_id (omit = chat-wide, positive = forum topic, General is 1, exclusive-minimum>0 implied), and cursor (must be replayed with the same chat_ref and topic_id). Only 'limit' is left unaddressed beyond its schema default/maximum, which keeps this just below a 5.

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 ('Read a chat's pinned messages'), order ('newest first'), and accepted reference forms ('by ID, @username or t.me[/s] link'). No sibling tool operates on pinned messages, so the agent can discriminate it from get_messages/get_history/search_messages without opening a 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 when/when-not guidance for topic_id ('Omit topic_id for chat-wide pins, or supply a positive forum topic ID (General is 1)') plus the access-policy split between forum topics and public-channel pins. It lacks a direct pointer to the alternative sibling (e.g. get_history or search_messages) for non-pinned retrieval, so it stops short of full routing guidance.

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 and openWorldHint, and the description adds genuinely new behavioral detail on top: results are bounded with no cursor or completeness guarantee, telegram_total_count vs locally_truncated report different limits, and the discovery permission is separate from retrieval permission. That is meaningful disclosure for a read-only call. The main omission is any statement of what a result record contains.

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 purpose is front-loaded in the first clause and each following sentence carries a distinct operational fact (accepted formats, permission requirement, completeness caveat, retry rule). It is dense and slightly prose-like for a two-parameter tool, but no sentence is 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?

With no output schema, the description takes on return-value explanation and does so partially, naming the bounded-metadata behavior and the telegram_total_count / locally_truncated distinction. It stops short of describing the per-result shape and leaves the limit parameter's meaning unstated, which is a real gap for a discovery tool.

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%, so the description must carry the parameter burden. It does well on chat_ref, enumerating the accepted forms (numeric ID, @username, t.me[/s]/username URL) and the failure mode for unknown IDs. It says nothing about limit beyond an oblique reference to locally_truncated, leaving its default, ceiling of 100, and effect unexplained — half the parameters are effectively undocumented.

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 ("Find similar public channels") plus the scope constraint ("for a required public broadcast source"), so the agent knows this is discovery-by-example rather than keyword search. It never names the closest sibling, search_public_channels, so the boundary between the two is left to the agent.

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 supplies real prerequisites and constraints: it requires allow_public_channel_discovery independently of retrieval permission, and it will not return personalized recommendations without a source. It also gives a retry instruction for temporary failures. What it never does is state when to prefer this over search_public_channels, so alternative selection remains implicit.

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 and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: the tri-state meaning of 'authorized' (true/false/null), that 'error' explains a failure, and that 'connected' is reported independently of authorization.

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?

Two short sentences: the capability first, then the result-field meanings. No filler, no repetition of the name, and the most decision-relevant detail (the null case) is included.

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 no output schema, the description carries the burden of explaining returns and it does so for the most critical fields. It stops short of describing what the 'discovery policy' and 'read scope' portions of the response look like, which leaves a small gap for a purely diagnostic tool.

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?

Zero parameters, so there is no parameter semantics to document and the baseline is 4. The description instead spends its space on return-field semantics (authorized, error, connected), which is the useful information for a no-arg tool.

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 ('Check') and the exact resource set: Telegram authorization, connection, discovery policy and read scope. It is clearly the diagnostic/status tool among a sibling list of message and chat retrieval tools, though it doesn't name a sibling explicitly.

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?

Use is implied — an agent infers it should call this to verify auth before other Telegram operations — but there is no explicit when-to-use, when-not-to-use, or prerequisite framing. 'Fresh' hints at forcing a live check rather than cached state, but that is left implicit.

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 and openWorldHint=true, and the description adds useful behavior beyond that: newest-first ordering, the channel discussion-group permission requirement, and error behavior for unsupported threads. It does not describe pagination behavior or return shape, but the added constraints are meaningful.

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 and front-loads the core purpose. The remaining sentences add permission and error context, though the 'thread_root' wording creates avoidable confusion relative to the schema.

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?

The description establishes purpose, ordering, a permission prerequisite, and error behavior, which is enough for a minimal understanding. However, with no output schema and 0% schema description coverage, it should explain the return shape or pagination and clarify the 'ref' parameter more fully.

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 carry parameter meaning. It refers to 'thread_root', but the schema parameter is actually 'ref', and it does not explain the string-vs-MessageRef shape, limit semantics, or cursor pagination. The mismatch and missing parameter detail are significant gaps.

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 and resource: reading replies to a thread root or comments on a channel post. It also states ordering (newest first) and distinguishes the root fetch from get_messages, so an agent can identify the tool's purpose without opening the 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 gives clear usage conditions: for channels the linked discussion group must be permitted, unsupported threads return an error, and get_messages can fetch the root. It does not explicitly compare against every sibling such as get_context or get_history, but the primary context is clear.

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?

Adds substantial context beyond the annotations: batches replay until acknowledged (even after restart), retries cannot confirm a newer batch, limit applies only to new batches, save=true writes a durable copy before acknowledgement and retries reuse it, source order is fair rather than globally sorted, and only the last 100 message IDs per source are checked. This is exactly the kind of non-obvious state, idempotency, and coverage-limit disclosure an agent needs before calling a non-read-only, non-idempotent poller.

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 opening purpose sentence is well front-loaded and every line carries information, but the remainder is an unstructured wall of prose mixing acknowledgement semantics, save behavior, ordering, and coverage limits. Some sentences ('Retrying that acknowledgement cannot confirm a newer batch') are dense enough to require re-reading, which hurts scannability for an agent.

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 no output schema and 4 undocumented parameters, the description does a lot of the missing work: it explains the replay/ack lifecycle, the saved_file return, issues/omissions and retry-delay signals, and the 100-ID revision window. What it never describes is the shape of a returned batch (what a batch contains besides message IDs), so the return contract is only partially covered.

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%, so the description must carry the load, and it does: name is for continuing incomplete passes, ack_batch_id acknowledges and polls in one call, limit applies only to new batches, and save=true writes a JSONL copy and returns saved_file. The gap is that save is said to 'require archive_directory,' which is not a parameter of this tool and is left unexplained, creating ambiguity about how to satisfy that prerequisite.

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: 'Poll a named subscription without managing per-chat tokens,' plus it clarifies the batch/acknowledgement model. It differentiates itself from ack_watch_changes by naming it as the separate acknowledgement path, but it never distinguishes itself from the sibling get_changes, which sounds closely related.

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 concrete routing rules: use ack_batch_id to acknowledge and poll in one call, or use ack_watch_changes instead; set save=true when a permanent JSONL copy is wanted; 'continue incomplete passes by name.' It lacks an explicit statement of when NOT to use this tool versus get_changes or search_messages, so it stops short of full when/when-not guidance.

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 annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: archived chats are included unless folder rules exclude them, and cursors freeze the selected chat list so subsequent pages must use the same filters.

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 with the primary purpose before pagination and filtering caveats. Each sentence adds relevant operational context, though the formatting is slightly loose.

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 list tool with five optional parameters and no output schema, the description covers important non-obvious behavior: folder union semantics, archive inclusion, and cursor stability. It leaves limit and chat_type mostly to the schema, which is acceptable because their constraints and enum values are visible there.

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 carries the burden of explaining parameters. It adds meaning for query (title or username matching), cursor (freezes the list and requires consistent filters), and folder_ids (union of folders), but does not explain limit or chat_type semantics.

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 and resource, 'List permitted chats', and adds scope through optional folder unions and pagination. It is clear what the tool does, but does not explicitly distinguish itself from siblings such as search_messages, list_folders, or get_chat.

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 when to use the tool by noting optional folder filtering and full pagination, but it does not explicitly state when to prefer list_chats over adjacent tools like search_messages or list_folders. Usage guidance is present but inferential rather than directive.

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 and openWorldHint=true, so the safety profile is covered. The description adds the shape of the payload (IDs, names, order, rules), but says nothing about result size, ordering guarantees, or whether all folders are returned at once — relevant gaps for a listing tool flagged as open-world.

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?

Two short sentences, front-loaded with the outcome and followed by the parameter behavior. Nothing is padded or repeated from the schema.

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 one optional parameter, no output schema, and read-only annotations, the description covers what the tool returns and how the filter works, which is enough to call it correctly. It could be stronger by mentioning result volume or whether folders are returned in the stated order reliably.

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 single 'query' parameter has no title-level documentation beyond its name. The description compensates well by stating it is optional, case-insensitive, and a substring match rather than an exact match — precisely the semantics an agent cannot infer from 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?

States a specific verb ('Discover') and resource ('folder') plus the returned attributes (IDs, names, order, rules), so an agent knows exactly what the call yields. No sibling tool in the list deals with folders, so explicit differentiation isn't needed, but the description also doesn't name a counterpart.

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?

'Optional case-insensitive name substring' implies the call can be used as either a full listing or a filtered lookup, which is useful implied guidance. However, there is no explicit statement of when to use this versus any other discovery path, and no exclusions or prerequisites are given.

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 only declare readOnlyHint and openWorldHint; the description goes far beyond them with cursor persistence rules, retry_after_seconds handling, ordering guarantees, 'issues' for incomplete metadata, and the caveat that titles/order can shift mid-traversal. It also flags the permission trap (public read rights don't cover forum groups) that an agent could otherwise walk into.

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 nearly every clause carries operational information; clauses are short and scannable despite the lack of bullets. Minor waste in restating read-only semantics ('Listing topics does not mark them read or modify them') that annotations already imply.

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 no output schema, the description still describes the shape of the response (next_cursor, issues, top_message_ref/root_message_ref, retry_after_seconds, ordering) and the edge case that a short or empty page can still return a cursor. Nothing an agent needs to call this correctly 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 coverage is 0%, so the description must carry the load, and it explains three of four parameters: chat_ref's accepted formats, query as an optional topic-name filter, and cursor via the next_cursor/retry continuation rule. Only 'limit' is left implicit, which matters given its 30 default and 100 cap.

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?

Specific verb plus resource (list topics in a forum supergroup) with the accepted selector formats (ID, @username, t.me link) spelled out. It cleanly separates itself from read-path siblings by pointing to get_history/get_pinned_messages for topic contents and get_thread/get_messages for refs.

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 when-to-use routing ('Pass a topic ID to get_history or get_pinned_messages', 'Read top_message_ref with get_messages, or ordinary root_message_ref with get_thread') and explicit exclusions ('Bot forums and monoforums are unsupported', public discovery/read permissions do not authorize forum groups). It even states the non-effect: listing does not mark read or modify.

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 and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that results include source counts and pending batch information, but says nothing about ordering, pagination, or whether pending batches reflect unacknowledged changes (the ack_watch_changes sibling suggests they might).

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 short sentence with no padding, and the core payload (names, source counts, pending batches) is front-loaded. The trailing 'after a new session' qualifier is the only weak element — it adds words without adding determinable meaning.

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 no parameters and no output schema, the description carries the burden of explaining what comes back, and it only gestures at that. Terms like 'source counts' and 'pending batches' are left undefined, and the relationship to the closely related get_watch_changes / ack_watch_changes pair is never clarified, leaving an agent to infer the workflow.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter claims are made.

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 resource (saved subscriptions/watches) and sketches the returned fields (names, source counts, pending batches), but the verb 'Find' is weaker than 'list all' and the phrase 'after a new session' muddies the scope rather than pinning it down. It does nothing to distinguish it from get_watch_changes or get_status among the siblings, so an agent must guess whether this enumerates watches or returns their contents.

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 explicit when-to-use or when-not-to-use guidance, and no named alternative. The trailing clause 'after a new session' hints at a trigger condition but is too ambiguous to function as routing — an agent cannot tell from this whether it should call list_watches or get_watch_changes first.

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?

Adds rich behavioral context beyond the readOnlyHint and openWorldHint annotations: page-vs-global ordering guarantees, cursor reuse requirements, partial/empty pages, retry_after_seconds on temporary failures, and restricted-access behavior. Nothing contradicts the annotations, and the extra detail materially helps an agent invoke it correctly.

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 dense but appropriately sized for a 12-parameter search tool, and it front-loads the core purpose. Some sentences could be organized more scannably, but most content is relevant and 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?

Given the complex search behavior, low schema description coverage, and no output schema, the definition is largely complete: it covers ordering, pagination, filtering, access scope, and retry behavior. It could be stronger with explicit limit semantics and a brief sense of the response shape.

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 compensates well by explaining ordering, order, cursor, date_from/date_to semantics, folder_ids union behavior, chat_ids intersection, has_link constraints, and query emptiness rules. It still omits limit semantics and does not fully enumerate content_type behavior, leaving some gaps across 12 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?

States a specific verb and resource ("Search permitted chats") and clarifies the search mode (Telegram keyword, not semantic), which helps distinguish it from semantic or public-channel search siblings. It does not explicitly name alternative tools or say when to prefer them, so it is clear but lacks direct sibling differentiation.

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 substantial usage guidance: when to use ordering=page vs. global, how order and cursor interact, how date intervals work, how folder_ids and chat_ids combine, and when has_link allows an empty query. It lacks explicit guidance on when to use this tool instead of get_messages, get_history, or search_public_channels.

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?

Adds substantial behavior beyond annotations: permission requirements, metadata-only results, Telegram ordering, non-exhaustive results, no cursor, possible fewer-than-limit returns, omitted unknown participant counts, and retry advice after temporary failure. These details materially help an agent set expectations and handle results.

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 front-loaded with the core action and then lists operational caveats in compact sentences. Every sentence adds useful behavioral or permission context with no 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 read-only, open-world search tool with no output schema, the description covers permissions, result type, ordering, exhaustiveness, pagination absence, and failure handling. It stops short of describing returned channel metadata fields, but the key expectations for invoking it are present.

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 adds useful query semantics: trimmed, 1..1000 characters, plus failure/retry behavior. It does not explain the limit parameter beyond indirectly noting results can be fewer than limit, so the second parameter remains underspecified.

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: "Find public broadcast channels by a trimmed query." It also distinguishes the result from sibling search_messages by clarifying it returns channel metadata, not posts. An agent can identify the tool's scope without opening the 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 clear usage context: requires allow_public_channel_discovery, and reading selected channels requires separate retrieval permission. It does not explicitly compare against sibling tools like get_similar_channels or list_chats, so routing guidance is strong but not exhaustive.

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