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

The annotations already include readOnlyHint: true, idempotentHint: true, and destructiveHint: false, which establish the tool as a safe read-only operation. The description adds valuable context beyond annotations by specifying the offline nature ('without Telegram API calls') and the specific diagnostics it returns (integrity, size, tier). This extra context helps the agent understand the operational scope and side-effect-free 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 concise, two sentences, and front-loads the key purpose and the use case. Every word adds value: the first sentence lists specific diagnostics, the second gives the usage trigger and a key behavioral trait (offline). No wasted words or redundancy.

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

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

For a tool with zero parameters and a rich output schema (which likely details the return values), the description is complete. It covers the purpose, usage context, and key behavioral trait (offline). The annotations cover safety, and the output schema handles the return format. Nothing important is missing for an agent to decide whether and how to invoke it.

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 are zero parameters, and the schema coverage is 100% (trivially, as there are no parameters). The description doesn't need to document parameters. Since there are none, the baseline is 3, and the description adds no parameter-specific information because there is nothing to add. This is appropriate.

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

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

The description clearly states that the tool inspects local SQLite/FTS5 archive integrity, database size, and active tool tier diagnostics. It distinguishes itself from sibling tools by focusing on cache health rather than chat operations or search. The purpose is specific and actionable, though it doesn't explicitly name a sibling alternative.

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 states when to use this tool: 'Use to verify cache readiness before running local searches.' This provides clear guidance on the trigger condition, and the mention of 'Operates entirely offline without Telegram API calls' implies it is a safe, low-cost operation compared to API calls. However, it doesn't explicitly say when not to use it or name alternatives, which is a minor gap.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds value by naming the exact environment prerequisites (TELEGRAM_SEND_ENABLED=true and TELEGRAM_DESTRUCTIVE_ENABLED=true), giving operational authorization context that is not present in the annotations. It does not contradict 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?

Two sentences with no fluff: the first states the primary action and mechanism, the second provides critical safety prerequisites. The main purpose is front-loaded, and every word earns its place.

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

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

With an output schema present and a rich input schema covering all parameters, the description provides the essential missing context: destructive operation and environment-flag requirements. It does not explain post-deletion behavior or error cases, but the idempotentHint annotation and the output schema mitigate that need. Minor gap, but otherwise complete for the tool's complexity.

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 detailed descriptions for chat_id and message_id already present. The description only repeats 'by message ID,' which is already in the schema, so it adds no new parameter-level meaning beyond the baseline set by 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 opens with a specific verb and resource: 'Delete a single message from a chat by message ID.' It unambiguously distinguishes this tool from editing, pinning, or sending messages among the sibling tools, and the deletion scope (single message) is explicit.

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 operational context by stating the destructive nature and the two required environment flags, which tells an agent when its use is permitted. It does not explicitly name alternative tools or conditions where another sibling would be more appropriate, but no direct deletion sibling exists, so the context is sufficient.

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

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

Annotations already expose mutability (readOnlyHint=false), idempotency, and non-destructive behavior. The description adds the operational constraint that the destination path must be within configured MCP allowed roots, which is useful beyond 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?

Three short sentences, front-loaded with the core purpose, followed by the key constraint and the alternative tool. No filler or 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?

For a download operation, the description explains what it does, the key path constraint, and the metadata alternative; an output schema exists, so return-value details are not necessary. Minor ambiguity about the default destination when file_path is omitted prevents a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the 'destination path' framing, but it largely restates file_path's root constraint and does not clarify the file_path schema phrase about 'upload or send' or the behavior when file_path is omitted.

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 names a specific operation ('Download an attachment or media file'), the resource (message attachment), and the destination (local filesystem). It clearly distinguishes itself from siblings like get_media_info (metadata only) and send_file (upload).

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: use it to physically fetch media, and use get_media_info when only metadata is needed. It lacks an explicit exclusion for send_file or a fuller when-not-to-use statement, but the main alternative is named.

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 non-read-only, non-destructive, idempotent operation. The description adds valuable behavioral context beyond annotations: it identifies the operation as a mutation and discloses the configuration prerequisite (TELEGRAM_SEND_ENABLED=true) plus the ownership restriction. 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 dense sentences with no filler. The main action and target are front-loaded, followed immediately by the critical mutation and permission constraints. 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 mutation tool with 5 parameters, an output schema, and all parameters fully documented, the description covers the essential operational constraints: mutation status, environment flag, and message ownership. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description complements this with the ownership constraint but does not add substantial semantic detail beyond what the schema provides. Baseline 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 ('Edit'), a precise resource ('text content of an existing message'), and a key scope constraint ('previously sent by this account'). This immediately differentiates the tool from siblings like send_message, reply_to_message, and delete_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 clear context for when this tool applies: editing an existing message sent by this account, and explicitly rules out editing messages sent by other users. It does not name sibling alternatives, but the scope and the TELEGRAM_SEND_ENABLED prerequisite provide adequate 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds no side-effect, auth, rate-limit, or error behavior beyond restating that metadata is retrieved; the listed return fields are redundant with the existing output schema.

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

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

Two sentences, zero filler; the primary purpose is front-loaded, and the usage condition is appended in the same breath.

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 lookup with two params, a full schema, an output schema, and safety annotations, the description plus structured data is complete. An agent knows exactly when to call it and what it returns.

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 applies. The description's mention of 'chat ID or @username' merely echoes (and slightly under-specifies) the chat_id property description, and it adds nothing about the account parameter.

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 ('Retrieve') and resource ('core metadata, title, member count, and type for a specific chat or channel'). It distinguishes the tool from list-oriented siblings by limiting to a specific known chat, and the usage clause ('known chat ID or @username') disambiguates further.

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 clear context ('Use when inspecting a known chat ID or @username'), which indicates the intended condition for use. It does not name alternatives (e.g., list_chats for discovery, resolve_username for resolution) or offer explicit when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations already cover read-only, non-destructive, and idempotent behavior. The description adds value by specifying the exact identity fields returned and mentioning account/session verification use cases. No contradictions with annotations exist.

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 tightly written sentences: the first states what the tool returns, the second states when to use it. No filler or redundancy; key distinctions 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?

This is a simple, low-risk read-only tool with no required parameters, a rich annotation set, and an output schema. The description fully covers what an agent needs to know to call it correctly and appropriately.

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 optional 'account' parameter is fully documented by the schema. The description does not add parameter-level detail, but the baseline 3 is appropriate because the schema carries the full burden.

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 ('Retrieve') and a precise resource ('detailed profile identity of the current Telegram user account') and lists the concrete fields returned (ID, name, username, phone). This clearly distinguishes it from sibling tools like resolve_username or list_contacts, which operate on other accounts or entities.

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 clear context for use: 'verifying account identity, session details, or caller permissions.' There are no explicit exclusions or alternative tool references, but because the tool is unique among siblings, the context provided is sufficient for an agent to select 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, idempotentHint=true, and destructiveHint=false, which fully cover the safety profile. The description adds no additional behavioral traits beyond the purpose, such as side effects or return semantics, but it also does not contradict 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?

Two crisp sentences. The first states the action and scope, the second gives usage guidance. No filler or redundancy, and the core purpose 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?

The tool has a rich output schema, complete parameter descriptions, and strong annotations covering read-only/idempotent behavior. The description provides the remaining context needed to decide when to call it, making the overall definition complete for an AI agent.

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 schema already documents all parameters (account, chat_id, message_id) in detail. The description mentions 'attached to a specific message' but does not add parameter-level information beyond what the schema provides, which lands exactly at the 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 ('Inspect') and resource ('media metadata attached to a specific message'), and enumerates the exact attributes (file size, dimensions, mime type, duration). This clearly distinguishes it from download_media and get_messages, which handle fetching or listing rather than metadata inspection.

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 instructs to use the tool 'before downloading or viewing' to verify file attributes and dimensions. This gives clear context for when to invoke it, though it does not explicitly name download_media as the alternative for the actual file transfer.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's job is lighter. It adds pagination behavior context ('paginated', 'sequential message retrieval'). Minor imprecision: it says 'offset or limit' while the schema actually uses page/page_size, which is a slight terminology mismatch but not a contradiction.

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 zero waste: the action, the usage context, and the sibling alternative. The most decision-relevant information (what it does and when to use it) is front-loaded before the alternative routing.

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

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

With an output schema present, rich annotations, and 100% schema param coverage, the description covers what remains: pagination intent and differentiation from search_messages. The only gap is the 'offset or limit' phrasing that doesn't match the page/page_size schema, which could mildly confuse an agent selecting pagination parameters.

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 schema fully documents all four parameters (page, page_size, account, chat_id). The description adds no real parameter semantics beyond the schema — 'offset or limit' loosely maps to page/page_size but is arguably a slightly less accurate framing. Baseline 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?

States a specific verb and resource ('Retrieve paginated messages from a specific chat') and clearly differentiates from search_messages by naming it explicitly. The title reinforces the same purpose. An agent can immediately tell this tool fetches messages sequentially rather than searching 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?

Gives explicit when-to-use guidance ('Use for sequential message retrieval') and names the alternative tool with the condition that selects it ('To search text across messages, use search_messages'). Nothing about selection is left 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 adds meaningful behavioral context beyond the annotations: it specifies 'accessible chats' (scope) and 'pagination support,' which are not covered by readOnlyHint or idempotentHint. It does not contradict any annotations. While it could mention rate limits or pagination mechanics, the read-only and idempotent nature is already disclosed, so this is sufficient.

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 with no redundancy. The first sentence front-loads the primary function (listing all accessible chats) and the second provides a usage hint. Every word earns its place, making it highly efficient and well-structured.

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 tool has 7 optional parameters, all documented in the schema, and an output schema exists. The description mentions pagination and gives a usage context, which is enough for an agent to decide when to call it. It does not explain how to use pagination parameters, but they are fully documented in the schema, so the description is adequately complete for its purpose.

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

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

The input schema provides complete descriptions for all 7 parameters with 100% coverage, including limit, account, archived, chat_type, with_about, unread_only, and unmuted_only. The description does not add any additional semantic meaning beyond the schema, so the baseline score 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 clearly states 'List all accessible chats, groups, channels, and direct dialogs' with pagination support, defining a specific verb and resource. It distinguishes itself from single-chat fetch tools like get_chat by emphasizing 'all' and includes a usage hint about locating conversations by title or type, making its purpose 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 provides a clear usage context: 'Use when locating specific conversations by title or type.' This implies a use case but does not explicitly mention alternative tools such as search_messages or search_public_chats, nor does it state when not to use it. The guidance is present but could be more explicit about 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the scope of what is returned ('with IDs and phone numbers'), but since an output schema exists this is largely redundant and no auth or rate-limit context is added. A 3 reflects annotations doing the heavy lifting with modest added value.

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 waste; the purpose is front-loaded and the routing hint follows immediately. Every clause earns its place.

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

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

With an output schema handling return values, rich annotations covering the safety profile, and 100% schema coverage of the sole parameter, the description supplies everything an agent needs to select and invoke this tool correctly.

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

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

Schema description coverage is 100% and the single 'account' parameter is fully documented in the schema, so the baseline is 3. The description does not mention the account parameter or its multi-account fan-out behavior, adding nothing 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 verb (list) and resource (Telegram contacts in the account address book) and explicitly distinguishes itself from search_contacts. An agent can tell the two apart 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 an explicit when-to-use ('finding contacts to message') and names the alternative plus its triggering condition ('to search contacts by query, use search_contacts'). Nothing is left 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 carry readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those hints: the environment prerequisite, the badge-clearing side effect, and the all-or-up-to-ID scope. No contradiction with the annotations was found.

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 no filler. The core operation is front-loaded, and each sentence adds a distinct piece of information: scope, mutation requirement, and side effect.

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 low-complexity mutation with rich annotations and an output schema, the description is mostly complete: it covers scope, prerequisites, and effect. The main gap is that 'up to a specific ID' is not representable through the current parameters, which leaves a small but real ambiguity.

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

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

The schema already documents both parameters thoroughly, so the baseline is 3. The description's phrase 'up to a specific ID' adds semantic interest, but it is ambiguous because the input schema exposes no message_id parameter; an agent may not know how to express that threshold with the declared inputs.

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 exact operation ('Mark...as read'), the resource ('messages in a chat'), and the scope ('all messages or messages up to a specific ID'). It is clearly distinct from the sibling tools, which handle sending, editing, deleting, pinning, or searching rather than changing read state.

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: it is a mutation, requires TELEGRAM_SEND_ENABLED=true, and clears the unread badge counter. It does not explicitly mention when not to use it or name an alternative, but no sibling tool directly competes with mark-as-read functionality.

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 annotations already indicating readOnlyHint=false and idempotentHint=true, the description adds valuable operational context: it is a mutation, requires a specific environment flag, and needs admin permissions in certain contexts. It does not mention error behavior or pin limits, but that is not a required disclosure given the existing annotations.

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

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

Three short, focused sentences with no filler. The action is front-loaded, the mutation and prerequisites come second, and the unpin alternative is provided last. 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?

Given the output schema exists and the annotations cover safety/idempotency, the description supplies the remaining essentials: purpose, prerequisites, and the undo path. An agent can decide whether to call the tool and how to avoid common permission and configuration failures.

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 parameters are already fully documented in the schema. The description adds minimal parameter-level meaning beyond confirming the chat/supergroup context, which matches the baseline for high schema 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 states a specific action ('Pin a message to the top'), identifies the target resource ('chat or supergroup'), and explains the intent ('for high visibility'). It is clearly distinct from siblings like unpin_message, delete_message, and 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 explicitly names the operation type as a mutation and gives concrete preconditions: TELEGRAM_SEND_ENABLED=true and admin permissions in supergroups/channels. It also directs the agent to unpin_message when the goal is to remove a pin, which is explicit alternative 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 indicate a non-read-only, non-destructive, non-idempotent operation. The description adds the important environment requirement TELEGRAM_SEND_ENABLED=true. It does not detail side effects like reply thread placement, but the annotation coverage lowers the burden and no contradiction 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 sentences contain the core action, the operational prerequisite, and the key alternative tool. Every sentence earns its place and the most important information 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 mutation tool with five schema-documented parameters and an output schema, the description covers purpose, the config gate, and the primary alternative. It could be slightly richer about side effects of replying, but nothing essential for calling 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 description coverage is 100%, with chat_id, message_id, text, account, and parse_mode each documented. The description adds no new parameter-level detail, but the schema carries the meaning, so a baseline score 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 opens with a specific verb and resource: 'Send a message in direct reply to a specific message ID in a chat.' It also names the sibling alternative send_message for standalone messages, so agents can distinguish it immediately without comparing schemas.

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 states when this tool is appropriate (direct reply to a specific message ID) and when it is not ('To send a standalone message, use send_message'). It also adds the TELEGRAM_SEND_ENABLED=true prerequisite, giving clear selection and operational 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the tool returns entity ID and object type but does not add behavioral details such as failure modes or account-fanout behavior. This is acceptable given the strong annotation coverage.

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, front-loaded with the core action and outcome, followed by a direct usage hint. Every sentence earns its place with no 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?

With a complete input schema, an output schema, and annotations covering read-only/idempotent behavior, the description fully covers what an agent needs to invoke this tool correctly. The usage hint ties it to the broader toolset without needing to enumerate return fields.

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 schema already documents both parameters clearly, including the '@' formatting note for username and the multi-account behavior for account. The description does not add parameter meaning beyond the schema, so baseline 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 names a specific action ('Resolve'), a specific resource ('public @username'), and a concrete outcome ('underlying Telegram entity ID and object type'). It also enumerates the possible object types, which clearly distinguishes it from list/search tools among its siblings.

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 states when to use the tool: 'Use before calling ID-based tools when only a username handle is known.' This is clear contextual guidance. It does not explicitly name alternatives or when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: no live API calls, no rate limits, and the dependency on previously synchronized messages. It doesn't mention staleness or what happens for unsynced chats, keeping it at 4.

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

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

Three short sentences, front-loaded with the core mechanism, then the benefit, then the prerequisite tool. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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?

An output schema exists, so return values need no explanation, and the description covers the key non-obvious dependency (sync first) and the offline/rate-limit behavior. It could go further on cache staleness or coverage limits, but for a 4-param read tool it is largely 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 100%, with limit, offset, query, and chat_id all documented in the schema itself, so the baseline is 3. The description adds no extra meaning about query syntax (FTS5 matching rules) or pagination behavior beyond what the schema already says.

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) plus the exact resource and mechanism (local FTS5 SQLite archive), and contrasts it with live Telegram API requests, which separates it from siblings like search_messages and search_global. An agent can tell which search tool to reach for 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 a clear use condition (instantaneous, rate-limit-free search over synchronized messages) and names a concrete prerequisite alternative, `sync_chat_cache`, for populating the cache. It does not explicitly state when NOT to use it (e.g., fall back to live search_messages when the cache lacks a chat), 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds scoping context (directory search by name/phone/username) but does not disclose the multi-account fan-out behavior that the account parameter implies. Adequate given annotation coverage, but not rich.

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: purpose plus matchable fields front-loaded, then the use-when and the sibling alternative. No filler, no 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?

Complete enough for a read-only directory search: an output schema exists so return values need not be described, and annotations cover the safety profile. The only gap is that the multi-account behavior (fan-out vs. default) lives solely in the schema description rather than being reinforced here, but nothing an agent needs to call 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 100%, so both parameters are already documented in the schema, including the multi-account fan-out semantics. The description repeats the matchable fields (name, phone number, username) which loosely maps to the query parameter but adds no syntax or format detail beyond the schema. Baseline 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?

States a specific verb (search) and resource (Telegram contacts directory), and enumerates matching fields (name, phone number, username). It also explicitly distinguishes from the sibling list_contacts, so the agent can pick correctly 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?

Explicitly says when to use it ('looking up a specific person') and names the alternative (list_contacts) plus its selection condition ('to view the entire directory'). Routing is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the context that this performs live Telegram API calls versus cached search, but does not disclose rate limits, auth requirements, or pagination behavior beyond what schema/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 efficient sentences with no wasted words. The core purpose is front-loaded, and the alternative tool is named clearly in the second sentence.

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 rich annotations, a full output schema, and complete schema descriptions for all parameters, the description covers everything needed to select and invoke the tool correctly. It clarifies scope, live API behavior, and the cached alternative.

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 schema fully documents chat_id, query, limit, and account. The description aligns with the query and chat_id semantics but does not add meaning beyond the schema, 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, resource, and scope: 'Search for text keywords within a specific Telegram chat or supergroup.' It is clearly distinguishable from sibling search tools (search_cached_messages, search_contacts, search_public_chats) because it specifies the single-chat scope.

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

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

Explicitly says 'Use when finding past conversations in a single chat' and names the alternative: 'To search the offline cache without live Telegram API calls, use search_cached_messages.' This gives the agent clear routing guidance and an exclusion condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety and idempotency profile is fully covered. The description adds the global-scope trait but says nothing about result volume, rate limits, or ordering beyond what structured fields provide. Adequate but not rich.

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

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

Three short sentences, front-loaded with purpose then routing guidance. No filler 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers scope, purpose, and alternatives, leaving only minor gaps (e.g., pagination/limit guidance) relevant to correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents query, limit, and account; baseline is 3. The description refines what the query targets (public communities rather than the generic "messages, contacts, or entities" in the schema), a marginal but real addition.

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) plus the resources searched (public channels, supergroups, bots) and the scope (globally / Telegram-wide). It is immediately distinguishable from in-account search siblings. No schema opening required to understand the purpose.

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 ("when discovering new public communities") and names the alternatives with the condition that selects them ("search within your existing chats, use list_chats or search_messages"). The global-vs-local routing decision is fully specified.

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

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

Annotations already mark this as a non-read, non-idempotent mutation, so no restatement is needed. The description adds two operation-level traits beyond annotations: file_path must resolve within configured MCP allowed roots, and TELEGRAM_SEND_ENABLED=true must be set. These help the agent avoid permission and configuration failures.

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 short sentences. The first leads with the core action, and the second packs only the two operation-level constraints an agent must know. There is no filler, redundancy, or repetition of the title.

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 a full 5-parameter schema, detailed per-parameter descriptions, and an output schema, the description only needed to state purpose and operation-level constraints, which it does. The allowed-root restriction and environment flag complete the picture for a safe first call.

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 the schema already explains chat_id formats, file_path string/array support, caption, topic_id, and account behavior. The tool description only restates the file_path allowed-roots constraint already present in the schema, adding no new parameter semantics, so the baseline score 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 verb 'Upload and send' plus the resource 'local document or file to a chat' precisely states the operation. This clearly separates it from text-focused siblings like send_message and from download_media, so an agent can select it 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 description gives useful context: a local file, a target chat, and the TELEGRAM_SEND_ENABLED=true prerequisite. However, it never names alternatives or says when not to use this tool, such as using send_message for plain text or download_media for retrieval, so the usage guidance is implied rather than explicit.

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

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

Annotations already mark readOnlyHint=false, but the description adds the operational requirement TELEGRAM_SEND_ENABLED=true, which is not inferable from the schema. It also reinforces the mutation nature. While it does not detail side effects like duplicate delivery on retries, the existing annotations and output schema reduce that burden.

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: two sentences that state the core action, the prerequisite, and the primary alternative. Every sentence adds distinct value and the most important information 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 four-parameter mutation tool with a full output schema, the description covers the essential selection and invocation needs: what it sends, where it sends, the required environment flag, and the sibling to use for replies. It does not mention sending files, but the 'text message' scope already implies `send_file` is for non-text media.

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 four parameters are already well documented. The description's 'text message' phrasing aligns with the `message` parameter but adds little beyond what the schema provides. Baseline of 3 is appropriate since the schema carries the parameter-semantic weight.

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 ('send') with a clear resource ('text message') and target scope ('Telegram chat, group, channel, or user'). It also differentiates itself from the sibling `reply_to_message` by explicitly directing replying use cases away, making the tool's role 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 provides concrete usage context: it is a mutation, requires TELEGRAM_SEND_ENABLED=true, and explicitly tells the agent to prefer `reply_to_message` when replying to an existing message. This gives clear when-to-use and when-not-to-use 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 states that the tool 'synchronizes ... into the local ... database', which is a write operation, but the annotations include readOnlyHint=true. This is a direct contradiction: readOnlyHint typically means the tool does not modify state. The description also fails to add other behavioral context beyond what annotations already provide, but the contradiction alone forces a score of 1 per the rubric.

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 with zero fluff. The first sentence states the core purpose, the second provides usage context and alternatives. Information is front-loaded and every word earns its place.

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

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

The description covers purpose, when to use, and alternatives. An output schema exists to describe return values, and annotations cover safety. The only gap is the contradiction with readOnlyHint, which makes the description slightly less reliable but does not leave out necessary call details. For a well-specified tool, this is nearly 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 coverage is 100%, so the schema fully documents all four parameters. The description adds no parameter-specific meaning beyond what is already in the schema, 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 uses a specific verb ('synchronize'), names the resource ('remote Telegram chat messages') and the target ('local SQLite/FTS5 offline cache database'), and explicitly differentiates from siblings by naming search_cached_messages and check_cache_health. This 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?

It gives explicit usage context ('Use before performing offline text searches or when populating local message archives') and names two alternatives with their purposes, effectively telling the agent when not to use this tool. This is textbook 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds a valuable operational requirement: TELEGRAM_SEND_ENABLED=true must be set. This goes beyond what the schema or annotations provide. No contradiction with annotations was found.

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 only three short sentences: purpose first, then the prerequisite, then the alternative tool. 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 tool with two required parameters, full schema coverage, and an output schema, the description is largely sufficient. It covers the operation, the required environment flag, and the sibling alternative. The scope phrase 'chat or supergroup' is slightly narrower than the schema's broader chat_id description, but this is 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 description coverage is 100%, with detailed descriptions for chat_id, message_id, and account. The description's phrases 'specific message' and 'chat or supergroup' loosely mirror the schema but add no new parameter-level meaning, 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 ('Unpin') and a specific resource ('a specific message from a chat or supergroup'), clearly distinguishing it from sibling tools like pin_message. The direct mention of pin_message as the inverse also reinforces what this tool does and does not do.

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 a clear context for use: removing a pinned message, and points to pin_message as the alternative operation when the goal is to pin instead. It also states the operational prerequisite TELEGRAM_SEND_ENABLED=true, which is useful guidance, though it does not enumerate exclusions or failure conditions.

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