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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, covering the mutation/safety profile. The description adds 'you can edit' as an eligibility constraint and notes the success return is 'edit result dict', but doesn't explain what gets replaced or permission requirements beyond 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, front-loaded with purpose. However, the second sentence mixes a return value note with a documentation URL, which is slightly disjointed. No wasted words, but structure could be cleaner.

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 annotations covering behavioral traits and a full schema plus output schema, the description needn't explain return values or parameters. However, it lacks guidance on permission requirements for editing and doesn't differentiate from siblings like send_message, leaving a gap for an edit-specific tool.

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

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

Schema description coverage is 100%, so all parameters including chat_id, message_id, message, and parse_mode are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already 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?

States a specific verb (Replace text) and resource (existing message) with a scope constraint ('you can edit in this chat'). Distinguishes from send_message by making clear it targets an existing message, though it doesn't name siblings 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 'you can edit' implies a permission/ownership constraint but doesn't explain when to use this versus alternatives like send_message. No explicit when-to-use or when-not-to-use guidance is provided.

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 openWorldHint=true. The description adds context on how search behavior changes based on parameters (global vs local) and mentions the success output shape, which is consistent with the annotations.

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

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

The description is a single dense paragraph but every sentence adds value. It could be more structured (e.g., bullet points), but it is reasonably concise for the complexity.

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 7 parameters, 0 required, and an output schema, the description covers the main search modes and return value. It references external documentation for full details, which is acceptable given the 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%, so baseline is 3. The description adds meaningful explanations for parameters like query (required for global search), folder (technical distinction), and date filters, providing context 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 clearly states that the tool finds users/groups/channels by name, username, or phone, and distinguishes between global search and dialog-based search, which is 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 provides guidance on when to use global search vs dialog/folder search, noting that query is required for global search and that min_date, max_date, or folder can be used otherwise. However, it does not explicitly compare with sibling tools like search_messages_globally or get_chats.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context about successful returns ('info dict') and forum topic inclusion up to topics_limit, but it does not go much beyond the basic contract.

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

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

The description is compact and front-loaded with the core purpose, followed by return behavior and a documentation link. It wastes little space, though the 'Success: info dict' fragment is slightly terse.

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 annotations covering safety and an output schema covering return structure, the description is largely complete for a simple read tool. The main gap is the absence of usage guidance versus sibling tools.

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 fully documented in the schema. The description repeats that topics_limit affects forum chats but adds no syntax, format, or edge-case detail 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 gives a clear verb ('Load') and resource ('profile and metadata for one user, bot, group, or channel'), making the scope of one specific chat understandable. It does not explicitly name or differentiate from siblings like find_chats, but the singular focus distinguishes it implicitly.

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

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

There is no guidance on when to use this tool versus alternatives such as find_chats or get_messages. The description states what it loads but offers no conditions, exclusions, or alternative routing.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and openWorldHint, the description adds critical operational limits (max 6 images per call, originals over 5 MB skipped) and specifies exact return behavior for each media type. This goes well beyond the safety and idempotency hints provided by annotations.

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

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

The description is front-loaded with the primary purpose and return format, then efficiently covers edge cases and limits in two dense sentences. No extraneous information; every clause earns its place, and the documentation link is appropriately placed at the end.

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

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

Given the tool's complexity (media handling, size limits, multiple return formats), the description covers all necessary behavioral details: inline base64 return, fallback for non-images, voice/video routing, and per-call limits. No output schema is needed because the description fully explains what to expect in the response.

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 thoroughly (chat_id formats, message_ids mutual exclusivity with query/reply_to_id). The description adds no additional parameter syntax or format details, making the baseline score of 3 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 and resource ('Fetch photos/images from specific messages'), specifies the return format ('INLINE as native image content (base64)'), and enumerates fallback behavior for non-image, voice, and round video. This distinguishes it from siblings like get_messages and get_yandex_disk_content.

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

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

It explains the core use case ('so web clients can read screenshots without fetching a URL') and routes non-image requests appropriately, directing to get_messages field `transcription` for voice/round video. It does not explicitly name get_messages or get_yandex_disk_content as alternatives for other file types, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, lowering the burden, but the description still adds real behavioral content: the mutual-exclusion constraint on input modes, the @username shortcut that avoids a lookup call, and the success shape (messages, has_more, total_count, discussion). Pagination semantics beyond the has_more flag are not elaborated.

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

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

Front-loaded with the core action and organized as scope, modes, shortcuts, constraints, and return shape. The synonym list ('conversation, dialog, or DM') and the trailing doc link add bulk, but nearly every sentence carries operational information.

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

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

For a 10-parameter tool with an output schema, the description covers purpose, mode selection, the exclusivity constraint, the username shortcut, and the return shape, so an agent has everything needed to call it correctly. Return-value detail is a bonus rather than a necessity given the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description genuinely adds over it: it explains the @username-as-chat_id shortcut, illustrates the date window with a use case ('what was written this morning'), and restates the message_ids/query/reply_to_id exclusivity that the schema only states per-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?

States a specific verb and resource ('Read chat history') and immediately enumerates the four distinct modes (browse latest, search text, fetch by ids, load replies), which separates it from the sibling search_messages_globally ('within this chat only'). An agent can identify the tool and its scope without opening the schema.

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

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

Gives concrete mode-selection guidance ('Browse the latest messages, search text inside the chat, fetch by ids, or load replies') and an explicit exclusion rule ('Do not combine message_ids with query or reply_to_id'). It does not explicitly name search_messages_globally as the alternative for cross-chat search, so routing for the global case 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 declare readOnly, openWorld and idempotent, but the description adds genuinely new behavior: recursion into subfolders, inline base64 image return, the note+preview-URL fallback for non-images, and a hard 'max 12 images per call' limit. Those operational constraints are exactly the kind of detail agents cannot infer from structured fields.

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

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

Front-loaded with the action and resource, then return behavior, then the trigger condition, then the one hard limit, then a docs link. Every clause adds information; nothing is padding.

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?

No output schema exists, and the description steps in to describe return values (inline images, fallback note + URL) and the per-call image cap. What is missing is any treatment of the `path` parameter and error behavior for invalid/private links, so it falls just short of fully self-contained.

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 full burden for the two parameters. It never explains the required public_url format beyond the implied host names, and the `path` parameter is completely unaddressed (subfolder recursion is mentioned, but not how to target one via path). Minimal compensation for a real coverage gap.

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

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

Specific verb ('Open') plus resource ('public Yandex.Disk link, folder or file') and an explicit statement of what comes back (images inline as base64, non-images as note + URL). This cleanly separates it from siblings like get_media_content, which handle Telegram-hosted media rather than public Yandex.Disk links.

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 concrete trigger: a chat message containing a disk.yandex / yadi.sk link that the user wants to inspect. That is clear when-to-use guidance, but it never names an alternative tool or states when NOT to use it (e.g., for Telegram-native attachments the agent should pick a sibling).

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 and idempotentHint. The description adds behavioral context: 'Global search ignores include_total_count' and mentions success format. No contradictions.

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 plus a documentation link. Front-loaded with purpose; every sentence adds value. 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?

Given 8 parameters and global scope, the description covers core functionality, success response, and a doc link. Output schema exists, so return values are covered. Could mention batching behavior, but schema covers 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?

Schema covers all 8 parameters with descriptions (100% coverage). Description adds minimal extra: comma-separated OR-style and ignoring include_total_count. 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 clearly states it searches all Telegram chats at once, distinguishing it from siblings like `get_messages` which is scoped to one chat. The verb 'search' and resource 'messages globally' are specific.

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

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

The description explicitly says 'not scoped to one chat' and lists optional filters, implying when to use this tool for global search. However, it does not explicitly name alternative tools or state when not to use, though sibling names provide context.

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

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

Annotations already declare openWorldHint and destructiveHint, so the safety profile is partially covered. The description adds a real behavioral constraint the schema lacks (~30 MB attachment cap) and states the success shape ('send result dict'), but says nothing about Telegram rate limits, auth/permission requirements, or the reversibility of a sent message.

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

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

Front-loads the core action and outcome in the first sentence, then one focused sentence on attachment sourcing, then a doc link. It is efficiently sized, though the data-URI explanation partially duplicates the schema's own files description.

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, return-value explanation is unnecessary, and the description still adds the success shape and attachment constraints. It is largely complete for a send tool, with minor gaps around message-size limits and the absence of any routing cue versus the other send_* siblings.

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 every parameter is already documented in the schema, which sets the baseline at 3. The description restates the files data-URI form and adds the size ceiling, but contributes little beyond what the schema entries already say for chat_id, message, parse_mode, and reply_to_id.

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?

Names a specific verb+resource ('Send text and optional attachments to a chat') and covers the scope of the operation. It does not, however, differentiate itself from nearby siblings like send_rich_message, send_message_to_phone, or edit_message, so the agent must infer which send variant applies.

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 in-context guidance for one parameter ('use the data URI form to send a file the caller has in memory... without needing a public link'), which implies when that path is appropriate. It never says when to prefer this tool over send_rich_message or send_message_to_phone, and offers no prerequisites 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?

Annotations already mark destructiveHint and openWorldHint. The description adds context that creation and removal of temporary contacts may occur, and explains the return fields (contact_was_new, contact_was_removed). This goes beyond the annotations, providing useful behavioral insight.

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-loading the core action and side effects, then explaining the return value. No unnecessary words, and it includes a link to full documentation, making it 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 description covers the main behavior, side effects, and return structure. Given the output schema exists, it adequately informs the agent. Missing are error scenarios or prerequisites (e.g., phone must be on Telegram, already in schema). Overall, mostly complete with a doc link.

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 parameter descriptions. The description adds some contextual meaning (e.g., 'may create a temporary contact' relates to first_name, last_name, remove_if_new) but does not significantly improve understanding 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 clearly states the tool sends to a phone number, may create a temporary contact, and sends text or files. The name and description distinguish it from sibling 'send_message' which likely sends to a chat, not a phone number.

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 usage via the name and actions, but lacks explicit guidance on when to use this tool versus alternatives like 'send_message' or 'search_messages_globally'. No when-not or context exclusions are provided.

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

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

Annotations only declare openWorldHint and destructiveHint, so the description carries most of the burden. It contributes the non-obvious fact that sending is done by a separately configured bot, that chat_id must be shared with that bot, and the success response shape ({sent, id, chat_id, type}). It does not explain failure modes or rate limits, so it falls short of a 5.

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

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

Front-loads the core purpose and the send_message alternative, then tacks on the bot constraint, success shape, and docs link. Dense but every clause earns its place; only the trailing documentation URL is dispensable.

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 the explicit success shape is a bonus rather than a necessity, and the description still covers the key operational constraint (bot-shared chat). The only gap is a mild conflict with the schema, which lists 'me' for Saved Messages while the description warns against 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?

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint not present in the schema: the bot-shared-chat requirement for chat_id. This meaningfully narrows how the parameter may be used, going beyond the schema's own 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?

Names a specific verb+resource (send markdown as a Telegram Rich Message) and explicitly differentiates from the sibling send_message, even naming the API (Bot API 10.1 sendRichMessage). An agent can tell it apart from send_message 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 states when to prefer this over send_message (content containing markdown tables, headings, or structured report layout) and adds a routing constraint that chat_id must be a chat shared with the separately configured bot. This is precisely the when/when-not/alternative guidance the dimension asks for.

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