telegram-archive-mcp

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

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lower burden. But it adds nothing about what 'statistics' contains, whether results are cached, or how it relates to refresh_stats — meaningful gaps for a stats-retrieval tool whose sibling implies staleness control.

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 efficient sentence with the resource front-loaded. No waste, though also no additional structure to aid 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 and no annotations beyond readOnlyHint, the description should explain what statistics are returned or at least the freshness model. Given the sibling refresh_stats exists, the omission of any staleness/caching semantics leaves the agent unable to choose confidently between the two.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single chat_id parameter, so the schema fully documents the input. The description adds no format hints (e.g., numeric vs. @username) beyond the schema, which is the expected baseline.

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 (Get) and resource (statistics) scoped to a Telegram chat, so the action is unambiguous. It does not, however, distinguish itself from the sibling refresh_stats, which an agent must reason about when deciding whether stats are stale.

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?

No guidance on when to call this versus refresh_stats, or whether it returns cached vs. freshly computed statistics. The agent is left to infer usage entirely from the name.

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?

Despite only a readOnlyHint annotation, the description discloses rich behavioral detail: which formats return viewable images, the 1568px scaling on the longest side, the exact JSON prelude emitted, and that non-image files return only JSON with an explanatory note. This goes far beyond the annotation and fully characterizes the output 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-loaded with the core action and format-handling behavior in the first sentence, with return-structure details following. The enumeration of JSON fields is dense and slightly run-on, but given there is no output schema, each detail 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: JSON fields for the message and file, the image-return condition, and the fallback note. Nothing an agent needs to call and interpret the result 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 100%, so both parameters (chat_id, message_id) are already documented in the schema. The description adds no syntax or format guidance beyond what the schema provides, so the baseline 3 applies.

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 (Get) and resource (the photo or file attached to one message), clearly distinguishing it from sibling message tools like get_messages or get_pinned_messages that return text. An agent can tell exactly what this returns 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?

The purpose implies usage (fetch media for a known message), but there is no explicit when-to-use, when-not, or named alternative among siblings. The agent must infer that this is the tool for extracting attachments from a message id it already holds.

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, so the safety profile is covered. The description adds genuine context beyond that: newest-first ordering, constant-time keyset pagination on large chats, and that dates are naive UTC. It does not cover edge cases like empty results or limits at the end of a chat.

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 tightly packed sentences: ordering and source first, then pagination modes, then the timezone caveat. No filler, and the most important constraint is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool with no output schema, the description covers ordering, both pagination strategies, and date semantics adequately. Minor gaps remain around result boundaries (empty page at end of chat) and whether limit applies per page, but nothing essential for a correct call 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 100%, so the baseline is 3, and the description adds value above it by explaining how before_date and before_id combine as a cursor pair and noting the performance rationale. The offset-ignored-when-cursor-given rule repeats the schema, so the gain is modest.

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 ('Get messages from a Telegram chat') plus a defining behavioral trait ('newest first'). It does not explicitly differentiate from the sibling get_messages_by_date or search_messages, so an agent must infer the boundary from the pagination detail rather than being told.

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 explains how to paginate (offset vs. keyset cursor via before_date/before_id, or after_id for newer) but never says when to choose this tool over get_messages_by_date or search_messages. Usage of the tool itself is implied by the pagination recipe; sibling routing is absent.

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?

With readOnlyHint already declaring the safety profile, the description adds real behavioral context beyond annotations: oldest-first ordering, timezone vs. UTC archive storage, and keyset-cursor efficiency on very large chats. It stops short of describing truncation/pagination at the description level, though the schema covers the limit case.

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 sentences, purpose front-loaded, zero filler; the timezone and efficiency notes are compact and each 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 read-only, 4-parameter tool with full schema coverage and no output schema, the description supplies the ordering, timezone semantics, and cost model an agent needs. Only truncation/limit behavior is left entirely to the schema.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: that the day is interpreted in the supplied timezone while the archive stores UTC, clarifying how date/timezone interact. It adds little on limit beyond what the schema already documents.

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 (Get), resource (every message of a Telegram chat), and tight scope (one calendar day, oldest first). It clearly differentiates from the generic get_messages by the day-scoping and ordering, but 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?

The day-scoped framing implies when this tool applies versus a general message fetch, but there is no explicit when-to-use/when-not guidance and no alternative (e.g. get_messages or search_messages) is named for other cases.

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, so the safety profile is covered. However the description adds nothing beyond that: no note on pagination, message limits, or what the returned pinned messages contain, which for a list-retrieval tool is a real gap.

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 with zero filler. It is efficient, though its brevity borders on under-specification rather than ideal conciseness.

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 simple read-only single-parameter tool with full schema coverage, so minimal description is tolerable. Still, it omits any indication of return size or pagination behavior, leaving the agent slightly under-informed compared to a sibling-aware definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is only one parameter (chat_id), which the schema documents. The description adds no format or ID-semantics detail beyond the schema, so baseline 3 applies.

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 ('Get') and resource ('pinned messages') scoped to 'a Telegram chat', so the agent knows exactly what it retrieves. It does not distinguish itself from siblings like get_messages or search_messages, so it stops short of a 5.

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 guidance on when to use this versus get_messages, get_messages_by_date, or search_messages. The purpose is implied by the name, but no conditions or alternatives 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?

The readOnlyHint annotation already tells the agent this is a safe read. The description adds no behavioral context such as pagination, ordering, failure on non-forum chats, or what is returned; it only restates the resource. With annotations covering safety, this is thin but not contradictory.

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 with no filler. Appropriately sized for a one-parameter read tool, though it is arguably too sparse to be maximally useful.

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 one-param read with annotations and no output schema, the definition is minimally adequate but omits return shape, ordering, and the fact that it only applies to forum chats.

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 100% and the single chat_id parameter is fully described there, so the description adds nothing beyond the schema. Baseline 3 applies when the schema carries parameter 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 states a specific verb and resource ('Get topics') and disambiguates the term by equating topics with 'forum threads' in a Telegram chat. It is clear, though it does not explicitly distinguish itself from siblings like get_messages or get_pinned_messages beyond the resource noun.

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?

No guidance on when to use this tool versus get_messages or the other retrieval siblings. The only implied condition is that topics exist in forum chats, which is never 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 only declare readOnlyHint, so the description carries the rest of the burden and does so well: it discloses ordering, the cross-tool contract (ref = chat_id), the fields on each row (id, type, accounts, title/name), and the exact response envelope plus the has_more-driven paging contract. With no output schema present, this is exactly the behavioral context 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?

Three tightly packed sentences with no filler, front-loaded with purpose and the 'use this first' directive before the field list and the paging contract. Every clause carries information an agent would otherwise have to infer.

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, no-required-argument, read-only list tool with no output schema, the description supplies the return shape, the field meanings, the ordering guarantee, and the pagination termination rule. Nothing needed to call it 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 100% and both limit and offset are documented there, so the 3 baseline applies; the description adds value by tying offset to the has_more flag in the response envelope, giving the parameter an operational meaning the schema alone lacks. It does not restate or extend the limit/default/max 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?

States a specific verb and resource ('List archived Telegram chats') plus the ordering ('most recent first'), and further positions itself against the sibling tools by explaining that each chat's ref is the chat_id the other tools accept. An agent can tell this is the entry-point enumeration tool 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?

'Use this first' gives an explicit usage directive relative to the other tools, and 'page with offset while has_more is true' supplies the continuation condition. It stops short of naming a specific alternative to use instead (e.g., list_folders or search_messages), so no exclusion criteria 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 readOnlyHint=true, so the safety profile is covered. The description adds the key behavioral fact that this returns ALL folders with no filtering or parameters, which contextualizes why it's parameterless. Slight gap: no mention of ordering or whether archived folders are 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?

Single front-loaded sentence with no waste; every word earns its place. Ideal for a simple parameterless list tool.

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 trivial zero-param read tool with annotations covering the safety profile, the description is nearly sufficient. However, it does not clarify return shape (e.g., array of folder names) or whether it includes default/all chats folder, leaving a minor gap.

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?

Tool takes zero parameters, so the baseline is 4. The description correctly communicates the no-argument nature and implies a complete listing, which matches the empty schema. No additional parameter detail is possible or needed.

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 'List' and resource 'Telegram chat folders'. Distinguished from siblings like list_chats (lists chats, not folders) and get_messages (retrieves messages). No ambiguity for an 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?

No explicit when-to-use or when-not-to-use guidance, though the scope ('folders') implies it's the tool for enumerating chat folders. Sibling tool list_chats makes the distinction clear enough, but the description does not state it.

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 declare idempotentHint=true and destructiveHint=false, so safety is already covered. The description adds the useful scope qualifier 'global' (all chats, not one) and the forced/override nature of the operation, but says nothing about cost, duration, or whether it blocks — relevant for a recalculation job.

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 with no filler; the verb and scope arrive immediately.

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 parameterless, output-schema-less maintenance tool with annotations covering idempotency and safety, the description conveys enough to call it correctly. Minor gap: no indication of whether it is expensive or long-running.

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 clarify beyond what the empty schema already conveys. Baseline 4 applies.

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 ('Force recalculation') and resource ('global telegram-archive statistics'), which is distinguishable from sibling get_chat_stats (read-only stats retrieval). It does not explicitly name that sibling, so it falls just short of a 5.

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?

No guidance on when to use this versus get_chat_stats, or when recalculation is warranted (e.g. stale data). The 'Force' wording hints at an override of cached values, but usage conditions are left entirely 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?

readOnlyHint=true already tells the agent this is a safe read, so the safety profile is covered. The description adds nothing further: no result ordering, no pagination behavior, no note on whether search is case-insensitive or spans the full chat 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 with no filler; the resource and scoping constraint come first. It is efficient, though bordering on under-specified rather than genuinely concise.

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 read-only search with full schema coverage and no output schema, the description is minimally viable but does not clarify retrieval scope versus sibling list tools. An agent could call it correctly, but with little confidence about when it beats the alternatives.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (chat_id, query, limit) are already documented in the schema. The description only echoes 'keyword' for query and adds no syntax, matching, or formatting detail beyond the structured fields.

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 (search), resource (messages), scope (a Telegram chat) and mechanism (by keyword), which implicitly separates it from siblings like get_messages and get_messages_by_date. It does not name an alternative explicitly, so it falls short of the top mark.

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?

No guidance on when to choose keyword search over get_messages, get_messages_by_date, or get_pinned_messages, all of which occupy adjacent retrieval roles. The agent must infer the selection rule from names alone.

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