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

Annotations already set readOnlyHint=false and destructiveHint=false, and the description adds that clicking sends a callback query and may change bot state. This goes beyond the structured hints and helps the agent anticipate side effects.

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 tight sentences convey the action, the primary behavior, and the exclusions without redundancy. The core action 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 small action tool with no output schema, the description gives the key context: what a click does, that bot state may change, and which button types are unsupported. It could add a pointer to telegram_get_inline_buttons for discovering button positions, but it is otherwise 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 is the only textual source for parameter meaning. It clarifies that row and column locate the button, and chat_id/message_id are self-evident message identifiers, but it does not document all four parameters in detail or explain indexing.

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 begins with a specific verb ('Press') and a precise resource ('a Telegram bot inline callback button'), then narrows scope by row and column. It also distinguishes this from siblings by explicitly limiting itself to callback buttons and naming blocked button types.

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 when-not guidance: only callback buttons, with payments, URL/login, web-app, game, and password buttons excluded. It stops short of naming a sibling alternative as the right choice for those other button kinds, so it doesn't earn a 5.

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

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

Beyond the destructiveHint annotation, the description explicitly warns 'This is destructive and requires explicit confirmation.' It also clarifies the revocation behavior, providing transparency about the irreversible impact on all chat participants.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences covering function, scope, and destructive nature. No unnecessary words or redundant details.

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

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

With no output schema, the description need not cover return values. It includes essential context about own-message restriction and revocation scope, though it omits potential limitations (e.g., message age constraints or errors for non-own messages) that could be relevant but are not strictly required for a delete operation.

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

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

The schema provides no descriptions for chat_id or message_id, and the description adds no explanatory text. However, the parameter names are self-explanatory in context, and the exclusiveMinimum constraint on message_id provides some guidance, so the lack of compensation is acceptable but not ideal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: deleting a message previously sent by the authenticated account, and adds the specific effect of revoking it for everyone when Telegram permits. This fully distinguishes it from sibling tools like edit_own_message or send_message.

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 implicit usage guidance by specifying that it only works on the authenticated account's own messages and that it is destructive. While it doesn't explicitly compare with alternatives, the scope and consequence are clear enough for an agent to decide when to use 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?

It explicitly states a non-destructive behavior (never overwrites an existing file), which is valuable. It does not mention other side effects like authentication requirements or rate limits, but the key safety aspect is covered.

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 two sentences: the first states the core action, the second lists the key parameter constraint. It is concise, well-structured, and free of unnecessary details.

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

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

The description is sufficient for an agent to understand the tool's functionality and main parameters. It does not cover edge cases (e.g., no media attached, error behavior), but given the sibling tools and the clarity of the purpose, it is reasonably 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?

The schema provides no descriptions for parameters, but the description explains the constraints for 'destination' (new file name, specific directory). 'chat_id' and 'message_id' are implicitly clear from the tool's purpose, so the description adds reasonable meaning beyond parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads media attached to a specific message, distinguishing it from sending files or retrieving messages. It is specific about the action and the target resource.

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 practical constraints: destination must be a new file name, saved in a configured directory, and never overwrites. However, it does not explicitly compare when to use this tool over other search or retrieval tools, though the purpose is clear enough.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that the operation changes external state and requires explicit confirmation, which is a procedural trait not present in annotations. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence states the action and target, the second warns about external state change and confirmation. Information is front-loaded and every sentence earns its place.

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

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

For a simple three-parameter mutation with no output schema, the description covers the essential context: ownership (authenticated account), message type (text), and the need for confirmation. It does not cover error cases or time limits, but the sibling tools and schema provide enough context for correct invocation.

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

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

With 0% schema description coverage, the description must supply meaning. It maps the three parameters to 'chat', 'message', and 'replacement text', giving semantic roles to chat_id, message_id, and text. It does not elaborate on constraints or how to obtain chat_id/message_id, but the schema provides the validation rules.

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 ('Edit') and resource ('one text message previously sent by the authenticated Telegram account'), clearly distinguishing it from siblings like send_message and delete_own_message. The scope is explicit: only the authenticated account's own messages. This leaves no ambiguity about the tool's function.

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 states the target condition: a message previously sent by the authenticated account, which tells the agent when this tool is appropriate and implicitly rules out messages from others. It also requires explicit confirmation of chat, message, and replacement text, serving as a precondition. However, it does not explicitly compare against alternatives like delete_and_resend or mention when not to use 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?

The readOnlyHint annotation already covers the safety profile, and the description adds a useful behavioral nuance: for private chats it may return the other person's user_id and profile fields, but only when Telegram makes them available. It does not describe group/channel return details or error behavior, but these are minor gaps.

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 with no filler and the primary action is front-loaded. The private-chat caveat is meaningful 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?

For a one-parameter read-only lookup with no output schema, the description covers the essential invocation requirements and one important return variance. It omits group/channel return specifics and not-found behavior, but these are secondary to correct selection and invocation.

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

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

The schema defines chat_id as a required integer with no description (0% coverage). The description adds the key 'exact' matching semantics and clarifies this is a single-chat lookup, but it does not explain how to obtain the chat_id or any Telegram-specific ID conventions.

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 action (get details), a specific resource (one Telegram chat), and a hard lookup condition (exact chat_id). This clearly distinguishes it from sibling tools like telegram_list_chats, telegram_search_chats, and telegram_resolve_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 phrase 'by its exact chat_id' clearly implies the tool should be used when the caller already has the precise numeric identifier. It does not explicitly name alternatives or say when not to use it, but the context is clear enough.

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 indicates a read-only operation ('List') and mentions that the result contains row and column values, adding some behavioral context. However, it does not disclose potential errors, edge cases, or output format details beyond the annotations' readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using only two sentences with no redundant information. It is well-structured and immediately communicates purpose and follow-up usage.

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

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

For a simple two-parameter read-only tool, the description provides sufficient context: what it lists, that it relates to a single Telegram message, and how the result feeds into a sibling tool. It does not fully describe output structure, but the reference to row and column values covers the essential need.

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

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

Schema description coverage is 0% and the description does not explain the parameters chat_id or message_id. While their names are somewhat self-explanatory, the description does not compensate for the lack of schema-level documentation, especially given the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the specific resource ('inline buttons attached to one Telegram message'). It also distinguishes itself from sibling tools like telegram_get_messages by focusing on inline buttons and explicitly linking to telegram_click_inline_button.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: to obtain row and column values needed for telegram_click_inline_button. It stops short of explicitly mentioning when not to use it or naming alternative tools, but the follow-up instruction provides strong usage 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 description discloses a privacy-relevant behavior beyond the readOnlyHint annotation: the phone number is intentionally omitted. This adds useful context about what will not be returned. There is no contradiction with the read-only annotation.

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 two brief sentences with no filler. The main action is front-loaded, and the additional privacy note earns its place by disclosing an important omission.

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 zero-parameter read-only identity tool, the description is largely sufficient. It could be slightly more explicit about what fields are returned besides the phone number omission, but the low complexity and annotation coverage make the description adequate.

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 has zero parameters, so the description has no parameter semantics to clarify. The baseline of 4 applies because no param documentation is 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?

The description uses the specific verb 'Get' and a clear resource: the authenticated personal Telegram account. It is clearly distinct from sibling tools, which focus on chats, messages, and media.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this tool is for retrieving identity details of the current authenticated account, and the sibling tool names show everything else targets chats or messages. It provides clear context, though it does not explicitly state exclusions or when to prefer alternatives.

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 establishes safety, and the description adds valuable behavior beyond that: it discloses internal repeated TDLib history requests and states that media is not automatically downloaded. This gives the agent a clearer model of the tool's runtime behavior. It could add ordering or error behavior, but the key traits are covered.

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 focused sentences front-load the core purpose and then add the most important behavioral caveats. There is no fluff or repetition of schema details; every sentence 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 tool with no output schema, the description covers what it returns ('text and metadata only'), its limit, and its internal pagination behavior. It is sufficiently complete for an agent to invoke correctly with chat_id and optional parameters, though exact message ordering and the meaning of a partial result are not spelled out.

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 only 33%, and only from_message_id has a schema description. The tool description adds some meaning for limit ('up to 100 messages') and chat_id ('known Telegram chat'), but does not explicitly explain optionality or how the parameters interact. It partially compensates for the low schema coverage but leaves room for more clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Read'), the resource ('messages'), and the scope ('up to 100 messages in a known Telegram chat'). This inherently distinguishes it from siblings like telegram_search_messages or telegram_get_chat, even though it does not name an alternative 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 phrase 'in a known Telegram chat' implies the tool is for retrieving messages when a chat_id is already available, and not for discovery/search. However, there is no explicit when-to-use, when-not-to-use, or mention of alternative sibling tools such as telegram_search_messages.

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 establishes safety, and the description adds that only text and metadata are returned. However, it does not disclose behavior when no message is pinned, what happens with an invalid chat_id, or any error/edge-case 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?

The description is a single, front-loaded sentence with no wasted words. The verb, object, and output scope are all presented 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?

Given the tool's low complexity—one required integer parameter and read-only behavior—the description covers the essential purpose, input constraint, and return scope. The absence of an output schema leaves the exact response shape unspecified, but the simple nature of the tool makes this 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?

The schema only defines chat_id as an integer with 0% description coverage. The description adds the useful 'known Telegram chat' constraint, implying the ID must refer to an already resolved chat, but it does not explain the ID format or how to obtain it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Read'), the specific resource ('currently pinned message'), and the context ('in a known Telegram chat'). It is easily distinguished from sibling tools like get_messages or search_messages because it explicitly targets the pinned message.

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 guidance about when to use this tool versus alternatives, nor any mention of when-not-to-use it. The phrase 'known Telegram chat' implies a prerequisite, but no alternative tools or conditions are referenced.

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 is consistent with the readOnlyHint annotation and adds useful context about filtering to recent unread chats. However, it does not disclose additional behavioral details such as ordering, pagination, whether unread state is affected, or authentication requirements, though the annotation already covers the read-only safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence with no filler or repetition. The core action and filtering criterion are front-loaded and every word contributes 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?

For a simple read-only listing tool with one optional parameter and no output schema, the description provides enough context for an agent to understand the primary purpose and invoke the tool appropriately. It does not specify output shape or 'recent' semantics, but the low complexity and readOnlyHint mitigate the 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?

The schema has 0% description coverage, and the description does not mention the 'limit' parameter at all. While the parameter name and constraints are somewhat self-explanatory, the description fails to compensate for the low schema coverage by clarifying the parameter's meaning, default, or effect on the result set.

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 ('List') and resource ('Telegram chats') with a clear filter ('that have unread messages'), making its purpose immediately understandable. It also inherently distinguishes itself from sibling tools like telegram_list_chats and telegram_get_chat by focusing specifically on unread chats.

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 guidance is given about when to use this tool versus alternatives such as telegram_list_chats or telegram_search_chats. The intended usage is only implied by the description and tool name, with no exclusions, conditions, or preference signals.

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=true already covering safety, the description adds meaningful context by stating that credentials and message data are not exposed. It also discloses that the optional check_connection parameter verifies the saved TDLib session, clarifying the tool's behavioral scope.

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 deliver the purpose, the safety guarantee, and the optional verification behavior with no redundancy. The core diagnostic purpose is front-loaded, and every word adds value.

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

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

For a simple, read-only health diagnostic with one optional parameter and no nested objects, the description is largely complete. It could specify what form the diagnostic result takes, but the absence of an output schema and the straightforward nature of a health check keep this from being a significant 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?

The single parameter is fully documented in the schema with a description and default, so the schema carries the parameter semantics. The description adds marginal context by linking check_connection to session verification, but no additional depth is needed beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Diagnose') and a clear resource ('local Telegram plugin setup'), making the tool's purpose unambiguous. It also distinguishes this tool from all sibling Telegram operations, which are focused on data access or messaging rather than setup health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this tool is for diagnosing local plugin setup issues, which is distinct from the sibling tools' data-oriented functions. It does not explicitly name alternatives or exclusions, but the context is strong enough that an agent would know when to invoke 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 already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context about 'recent' chats and the inclusion of Saved Messages, but does not disclose sorting or pagination behavior, which is minor for this tool.

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 with no filler. The action and scope are front-loaded, and the usage guidance follows immediately. Every sentence 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 list tool with one optional parameter, the description plus schema is sufficient for correct invocation. It clearly scopes the tool, distinguishes it from the search sibling, and the return shape is reasonably implied by 'List recent Telegram 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%, with the single 'limit' parameter fully documented including default and maximum. The description does not need to repeat parameter details, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and a clear resource scope: recent Telegram chats, groups, channels, and Saved Messages. It also distinguishes itself from telegram_search_chats by explicitly defining when to search instead, so an agent can tell it apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to use search when the user names a person or a chat, naming the alternative tool and providing a clear routing condition. This gives concrete guidance for when list is not appropriate.

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 that the operation 'changes external state', which goes beyond the raw annotations and explains why confirmation is required. The description also implies a user-driven safety rule. It does not mention failure behavior or response format, but for a simple state-changing tool the disclosure is 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?

Two concise sentences with the core operation front-loaded and the safety constraint immediately after. Every sentence earns its place and there is no redundant restating of schema details.

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

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

For a simple four-parameter tool with no output schema, the description covers the essential purpose and the confirmation prerequisite. However, it leaves the optional `remove` parameter's default behavior and the expected return value unspecified, so it is adequate but not fully 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, the description partially compensates by mapping 'chat, message, emoji, and whether it should be added or removed' to the parameters and clarifying the `remove` boolean's purpose. It does not specify what happens when `remove` is omitted or provide additional format-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Add or remove your emoji reaction') on a specific resource ('one Telegram message'), which is clearly distinct from all sibling tools. The second sentence also reinforces the exact entities involved: chat, message, emoji, and action type.

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?

Explicitly provides a precondition: use only after the user confirms the chat, message, emoji, and whether to add or remove the reaction. It does not name alternatives or when-not-to-use conditions, but the confirmation requirement gives clear context for safe invocation.

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?

It explicitly states that the tool 'changes external state,' which complements the annotation readOnlyHint=false. It also adds a meaningful operational caution about user confirmation that is not present in the annotations. No contradiction with the annotations exists.

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, each earning its place. The core action is front-loaded, followed immediately by the critical usage caution. There is no filler or repetition of schema details.

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

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

For a simple three-parameter mutation tool with no output schema, the description provides purpose, external-state warning, and a clear invocation condition. It could add guidance on the relationship between chat_id and reply_to_message_id, but overall it is sufficiently complete for an agent to use it correctly.

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

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

With 0% schema description coverage, the description partially compensates by mapping key concepts: 'recipient' hints at chat_id, 'text' maps to text, and 'specific Telegram message' maps to reply_to_message_id. However, it does not clarify that reply_to_message_id must belong to the same chat or explain how to obtain these IDs.

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: 'Reply to a specific Telegram message.' This clearly distinguishes the tool from send_message, react_to_message, and other sibling tools, even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit precondition: call only after user confirmation of recipient and text. It implies this is the correct tool for replying to an existing message rather than sending a new one, though it does not explicitly name alternatives or 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 the readOnlyHint annotation, the description explicitly says 'never sends a message' and mentions returning 'candidate' IDs, implying a non-destructive, multi-result behavior. This adds useful transparency not present in the annotation.

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 concise, information-dense sentences with no redundant phrasing. Every word adds value, efficiently covering purpose and a key safety aspect.

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

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

Given the tool's simplicity, the description covers the essential purpose and safety guarantee. It does not detail the return format or error behavior, but these are likely predictable from the context of sibling tools and the term 'candidate chat IDs'.

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 parameter names 'query' and 'limit' are self-explanatory, and the description hints at accepted input formats (person, group, channel, @username). However, it does not specify the exact meaning of 'limit' or how the query is matched, leaving some ambiguity. Schema has no descriptions, so more detail would have been helpful.

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?

Clearly states the tool's function: resolving a person, group, channel, or @username into chat IDs. The phrase 'for later read tools' distinguishes its role from other tools, making its purpose specific and unambiguous.

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 indicates when to use the tool—before read tools that require chat IDs—and notes that it never sends a message, hinting at safe read-only usage. It does not explicitly contrast with alternatives like search_chats, but the workflow context is clear enough.

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 signals a safe read operation, and the description adds useful behavioral detail: private-chat results include the contact's user_id where available, and the tool is meant for disambiguating recipients before sending. No contradiction exists. The description could add scope limitations or result pagination, but with the annotation covering safety, this is solid.

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 sentences, with the primary purpose in the first sentence and only functional extras after it. The user_id detail and usage advice both earn their place. There is no filler, repetition, or ambiguity.

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

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

For a simple two-parameter read-only search with no output schema, the description covers what the tool searches, how the query is interpreted, one key return detail (user_id), and the recommended workflow. It is slightly light on the exact shape of results beyond user_id, but the simplicity of the tool and presence of annotations make it 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 carries the burden of parameter meaning. It explains the required 'query' parameter well by defining it as name, username, or title. However, 'limit' is left undescribed; only the schema's numeric min/max constraints hint at its purpose, and the description does not mention result count or default behavior. This is partial compensation, not full.

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 starts with a specific verb 'Find' and clearly delimits the resource: people, groups, channels, or Saved Messages searchable by name, username, or title. This distinguishes it from siblings such as telegram_search_messages (message content) and telegram_list_chats (listing existing chats). It also adds a distinctive behavior—returning user_id for private chats—which further clarifies the tool's role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: 'Before sending to an ambiguous name, search and confirm the intended chat.' This tells the agent when this tool is the right choice. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a fully explicit routing guide.

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 readOnlyHint annotation, the description clearly discloses that no media is downloaded automatically and only message metadata is returned, fully revealing side effects.

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 concise, information-dense sentences with no filler or redundancy; the essential purpose and side-effect constraint are 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?

The description is adequate for basic intent but lacks guidance on how 'query' filters results and what 'limit' controls. No output schema exists, so return metadata is only briefly described.

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 coverage, the description must explain parameters. It partially covers 'kind' by enumerating media types and implies 'chat_id' via 'known chat', but fails to explain 'query' and 'limit' entirely.

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?

Description clearly states the tool finds recent media messages of specific types within a single known chat, and explicitly distinguishes itself from file download by noting it returns metadata only.

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 it (targets media in a known chat) but does not explicitly contrast with sibling tools like telegram_search_messages or telegram_download_file, leaving some selection ambiguity.

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=true annotation is not contradicted and already covers the safety profile. The description adds useful scoping context (global vs chat-scoped search), but it does not disclose behavioral details beyond that, such as whether only accessible chats are searched, result ordering, or how matches are returned.

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 with zero filler. The core action is front-loaded, the scoping modifier comes second, and the use-case sentence earns its place by helping an agent decide when to invoke the 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?

Adequate but with gaps: there is no output schema, so the description is the only place an agent could learn what results look like, and it remains silent on that. The limit parameter is undocumented, and there is no mention of ordering or pagination behavior, which matters when locating a specific deadline or topic.

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 schema description coverage at 0%, the description must compensate for the undocumented parameters. It explicitly explains chat_id ('inside a supplied chat_id') and implicitly explains query ('Search Telegram message text'), but it says nothing about the limit parameter, which remains unexplained by both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Search'), a clear resource ('Telegram message text'), and two scopes ('globally' vs 'inside a supplied chat_id'). It distinguishes itself from sibling tools like telegram_search_chats and telegram_search_media by anchoring on message text, and the use cases (topic, deadline, specification, file discussion) sharpen what the tool is for.

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 to locate a topic, deadline, specification, or file discussion' gives actionable context on when the tool is appropriate. However, it does not explicitly state when NOT to use it or name alternatives such as telegram_search_chats/telegram_search_media, leaving some sibling differentiation 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?

The description explicitly states 'This changes external state,' which complements the annotations readOnlyHint=false. It also adds a meaningful safety condition requiring explicit user confirmation, going beyond what 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?

Two sentences with no filler. The primary action is stated first, and the critical side-effect warning and user-confirmation requirement are included without redundancy.

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

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

The description covers the action, side effect, and consent gate, which is sufficient for a simple send-file tool. It does not describe response or error behavior, but this is not essential for correct invocation given the straightforward parameter 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?

With 0% schema description coverage, the description must compensate for parameter meaning. It maps 'recipient, file, and caption' to chat_id, file_path, and caption, but it does not explain what a chat_id is, what file_path should contain, or any path/type requirements.

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: 'Send a local file through the personal Telegram account.' This clearly differentiates the tool from siblings like telegram_send_message, telegram_reply_message, and telegram_download_file.

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 an explicit usage condition: 'call only after the user explicitly confirms recipient, file, and caption.' This is clear contextual guidance, though it does not explicitly mention alternatives or when not to use the tool.

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

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

The description explicitly states that the tool 'changes external state', which adds important behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false). It also adds a consent requirement, making the external effect and its preconditions transparent.

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 with no filler; the first identifies the action and scope, and the second adds the critical behavioral guardrail. Every sentence earns its place and the most important operational warning 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 simple two-parameter send operation, the description covers the required side effect, the explicit user confirmation prerequisite, and enough parameter meaning to invoke correctly. It does not describe the return value or error conditions, but the tool's simplicity and sibling context make this 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?

Schema coverage is 0%, so the description must compensate. It maps chat_id to 'recipient chat' and text to 'exact message', which provides some semantic grounding. However, it does not explain how to determine chat_id, mention text length constraints, or clarify expected formats beyond what the parameter names already imply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Send text') and a specific resource ('personal Telegram account'), which clearly distinguishes it from siblings like telegram_send_file and telegram_reply_message. The verb+resource structure leaves no ambiguity about what the tool 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?

Provides an explicit precondition: call only after the user has confirmed both the recipient chat and the exact message. It does not explicitly name alternative tools or when-to-prefer them, but the confirmation condition gives clear operational guidance.

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