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

Despite destructiveHint:true already signaling danger, the description adds crucial behavioral context: the first step does not delete, deletion is irreversible, chat and message_id are revalidated, mismatches are rejected, and the message becomes readable with deleted:true afterward. This goes well 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?

The description is compact and information-dense: every sentence contributes either workflow, safety, or post-condition detail. The two-step behavior is front-loaded, and there is no redundant filler.

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

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

The description is complete for a destructive tool with no output schema: it explains the preview payload, the confirmation mechanism, irreversibility, ownership restriction, and the resulting message state. An agent has enough information to invoke both steps correctly and understand failure conditions.

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 already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantic context by explaining the two-phase flow, the role of confirm_token from the preview, and the validation of chat/message_id on the confirm step, which supplements the schema descriptions.

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 deletes the user's own message using a two-step confirmation workflow, and explicitly notes that deleting another user's message is rejected. This distinguishes it from sibling tools like edit_message and send_message with a specific verb, resource, and 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?

The description explains exactly when to use the tool and how to sequence calls: first without confirm to get a preview, then with confirm:true and the token to actually delete. It clearly excludes deleting other users' messages, though it does not explicitly contrast with alternatives like edit_message.

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 provide only false hints (not readOnly, not idempotent, not destructive). The description adds the download path and return value but lacks details on overwrite behavior, error handling, or side effects beyond saving the file.

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

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

Single sentence that front-loads the action and includes essential detail (download path). No unnecessary words.

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 no output schema, the description reports the return value (local path). It covers the core functionality but omits edge cases like missing file or permission issues.

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, so the description does not need to add much. It does not elaborate on parameters, 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?

Description uses specific verb 'скачивает' (downloads) and resource 'вложение' (attachment) with explicit destination folder. It clearly states what the tool does and is distinct from sibling tools, none of which perform downloads.

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 implicitly tells when to use (when you have a file_id) and there are no alternative download tools among siblings. However, it does not explicitly state prerequisites or contrast with other tools.

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

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

Annotations only say destructiveHint=true, but the description discloses far more: the draft step is non-mutating, the confirm step is irreversible, chat/message_id/new_text/mentions are cross-validated at confirm and discrepancies rejected, foreign-message edits are server-rejected, and the edited message reads back with a non-empty LastEditTimestamp. This meaningfully extends what the annotations already provide, and there is no contradiction with destructiveHint=true.

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 dense sentences arranged as cause-and-effect: draft behavior, confirm behavior with irreversibility and validation, then post-edit state. It is front-loaded with the most critical fact (two-step process, draft does not edit), and every clause earns its place — nothing repeats 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?

For a complex six-parameter tool with no output schema, the description covers the whole call sequence, irreversibility, mismatch rejection, the own-message restriction, and the observable post-edit state (new text plus LastEditTimestamp). Small gaps remain: the confirm step's return value and error shapes are not described, and the draft preview's exact structure is only partially sketched — though the schema's detailed parameter documentation partially compensates.

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 descriptions are already unusually rich — mentions documents the draft/confirm resolution and ordering rules, confirm explains the boolean switch, and confirm_token ties to the draft. The description contributes flow-level context (draft first, then confirm with token) but adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource+scope constraint: 'Правка своего сообщения' (editing one's own message), and immediately explains the two-step draft/confirm mechanism. This distinguishes it from sibling tools like send_message, delete_message, and pin_message without needing to open their 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 usage context is explicit: a mandatory two-step sequence where 'без confirm возвращает превью ... и НЕ правит' but 'с confirm:true и confirm_token из превью правит'. It also states an exclusion — 'Правку чужого сообщения отклоняет сервер' — signaling not to use it on messages the agent didn't author. It falls short of explicitly naming alternatives (e.g., send_message for new messages), so it earns a 4 rather than 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=true, so the read-only nature is covered. The description adds that the tool returns a page of messages with cursor pagination, which is useful but does not disclose additional behavioral traits like rate limits or sorting order.

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 sentence that immediately states the core functionality (get chat history with pagination). No wasted words.

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

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

There is no output schema, and the description does not explain the return format (e.g., message fields, cursor structure). Given the complexity of parameters (date range, cursor), the description is incomplete for an agent to fully understand the tool's behavior.

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 all parameters have descriptions in the schema. The tool description does not add new meaning beyond the schema; it only mentions pagination. 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 clearly states it retrieves a page of messages from a specific chat with cursor pagination. The verb 'get' and resource 'history' are specific, and the pagination detail distinguishes it from siblings like get_message (single message) and search (query-based).

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 for retrieving chat messages with pagination but does not explicitly state when to use this tool versus alternatives like get_thread or search. No 'when not to use' guidance is provided, though the context of cursor pagination hints at its purpose.

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. Description adds that it returns enriched message with detailed reactions/read receipts and that with_reactions triggers additional calls, providing useful behavioral context 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 convey all essential information efficiently without fluff, with critical details 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?

No output schema exists, but description mentions return of enriched message and reactions. However, it does not explain the structure of enriched message or reactions, leaving some ambiguity despite covering usage.

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. Description adds context about alternative usage (join link) and explains message_id as timestamp in microseconds, but parameter descriptions in schema are already adequate.

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

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

Description clearly states the tool retrieves a single message by two alternative methods (chat+message_id or join link) and specifies it does not load history, distinguishing it from sibling tools like get_history and get_message_context.

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?

Implies when to use (single message retrieval without history) and provides two identification methods, but does not explicitly state when not to use or compare with siblings beyond noting history exclusion.

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

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

The annotations already indicate readOnlyHint=true, so the safety profile is known. The description adds that the tool uses a timestamp in microseconds as the marker and returns a window of messages with configurable before/after counts, which goes beyond the annotation. 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?

The description is a single, clear sentence that efficiently conveys the core functionality. No extraneous information; it is front-loaded with the key concept.

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 explains the input parameters well but does not describe the output format or what fields the returned messages contain. Since there is no output schema, more detail on the return structure would improve completeness for an 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 coverage is 100% with each parameter described. The description provides a high-level overview but does not add significant new details 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?

The description clearly states the tool retrieves a window of messages around a specified message_id, with N messages before and after. It uses specific verb ('get') and resource ('message context'), and distinguishes from siblings like get_message (single message) and get_history (possibly whole history).

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 the use case: when you need context around a specific message. However, it does not explicitly say when to use this vs alternatives (e.g., get_history for broader range, get_message for single). No when-not or alternative 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?

Detailed explanation of anonymous poll behavior (voters_hidden: true) and error case 'not_a_poll'. Annotations already declare readOnlyHint=true, and description adds valuable behavioral context.

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?

Description is somewhat lengthy but every sentence adds value, front-loading purpose. Could be slightly more concise.

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

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

No output schema, but description fully enumerates return fields and explains behavior for anonymous polls. Complete for a read-only tool with clear input.

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

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

Schema coverage is 100% and description adds meaning: chat can be a ChatId or search query, message_id is a timestamp in microseconds as a string. Adds value beyond 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?

Description clearly states 'Reads a poll by chat + message_id' and lists all return fields. Distinguishes from siblings like get_message or vote_in_poll by being specific to polls.

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?

States 'без confirm' (without confirmation) indicating a read operation. Implicitly contrasts with vote_in_poll but lacks explicit '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 adds behavioral context beyond annotations, such as the empty thread case (empty:true) and that the first message is sent via send_message. This complements the readOnlyHint annotation without 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?

The description is concise but dense, mixing key usage info with a tangential note about send_message. It could be better structured and front-loaded with the core purpose.

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?

Since there is no output schema, the description should explain the return structure. It only mentions empty:true for empty threads, leaving pagination, message fields, and other details unspecified, which is inadequate for a retrieval 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?

With 100% schema description coverage, the baseline is 3. The description adds minimal extra meaning by clarifying the two addressing modes, but does not deepen understanding beyond what the schema provides.

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 retrieves thread messages as a micro-chat and explains two addressing modes (thread_id or chat+message_id). It differentiates from siblings like get_message or get_history, but could be more explicit about contrasts.

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 for fetching thread messages but does not provide explicit guidance on when to use this tool versus alternatives like get_message_context or get_history. No when-not or exclusion criteria are given.

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

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

Annotations already declare idempotent and non-destructive. Description adds context about easy rollback and no confirmation needed, which complements the annotations without 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?

Two concise sentences with key information front-loaded: action, parameter, and important nuances (rollback, no confirm). No wasted words.

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 simple tool with one parameter, no output schema, and ample annotations, the description covers purpose, usage, behavior, and parameter completely. No gaps.

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

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

Schema coverage is 100% and schema describes thread_id as 'ChatId треда (дериватив get_thread)'. Description repeats the parameter usage but adds no new semantics beyond what schema provides.

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

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

Clearly states the tool subscribes/joins a thread by thread_id, distinguishes from creating or sending messages, and differentiates from sibling tools like leave_thread and get_thread.

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 mentions when to use (thread_id), what it is not (creation/sending), and notes easy rollback via leave_thread. Lacks explicit comparison with all siblings but provides sufficient 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 idempotentHint=true and destructiveHint=false. The description adds that no confirmation is needed and nothing is destroyed, which is consistent but not significantly 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?

The description is a single concise sentence that immediately conveys the action and key constraints. No wasted words.

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 has a single parameter, no output schema, and annotations provide safety profile, the description covers purpose and behavioral traits sufficiently.

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 a clear description for thread_id. The tool description does not add additional parameter semantics 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 verb (leave/unsubscribe) and the resource (thread), with reference to a specification section. It distinguishes from sibling tools like join_to_thread.

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

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

The description says it does not destroy anything and does not require confirmation, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.

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?

No contradiction with readOnlyHint annotation. Adds behavioral detail about excluding message text by default for privacy, which is beyond what annotations provide.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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?

Describes metadata returned (last message, unread flag) but lacks full output structure details. Given no output schema, more explicit fields would help completeness.

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%, but the description adds context for include_last_message_text (privacy rationale) and implies defaults for limit. This adds value 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 it lists chats with metadata and sort order. It distinguishes from siblings by specifying the resource and scope, but doesn't explicitly contrast with tools like search or get_history.

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?

Explains default behavior (no last message text) and when to enable include_last_message_text. Lacks explicit when-not-to-use or alternatives among siblings.

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 indicate readOnlyHint=true, and description adds significant context: always returns complete actor lists, uses two WS calls (UserReactions + UserReads/Mode:1), and is more expensive. No contradictions, full transparency.

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?

Description is a single paragraph with no wasted words; each sentence adds value (purpose, differentiation, cost). Front-loaded with intent. Clear and efficient.

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 4 parameters, read-only annotation, and no output schema, description covers purpose, distinction from siblings, and behavioral details (complete list, two calls). Could briefly mention return structure, but overall adequately complete for agent use.

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 baseline is 3. Description does not add parameter-level details beyond schema; mentions output behavior (actors_complete:true) but not parameters. No extra semantic value.

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

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

Description clearly states the tool lists reactions and reads for a message, with specific verb+resource. It explicitly distinguishes from siblings like get_history/get_message_context/get_thread by noting completeness, earning a 5.

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

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

The description explicitly tells when to use this tool (for complete list) versus alternatives (which may truncate). It also notes higher cost (two WS calls), providing clear 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 say it is a non-read-only, idempotent, non-destructive action; the description adds meaningful behavior beyond that: one-call confirmation-free execution, fetching the last history page when message_id is omitted, and the verified SeenMarker effect that resets unread state. 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?

The description is compact (three sentences) and front-loaded with the core action. The third sentence on SeenMarker verification is useful but slightly implementation-detail heavy; overall every sentence contributes.

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 3-parameter tool with no output schema, the description covers the action, optional behavior, safety profile, and side effects (history fetch, unread reset). Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents chat, seqno, and message_id. The description only restates the message_id optional behavior and adds no new parameter syntax or resolution detail, so the 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 opens with a specific verb and resource: 'Отмечает чат прочитанным' (marks chat as read). The 'ОДНИМ вызовом' qualifier and the SeenMarker semantic detail clearly distinguish the action from sibling tools like get_history or 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?

There is no direct sibling that marks chats read, so the description instead gives practical usage context: it is safe ('без confirm (безобидно)') and explains the two modes — with or without message_id. This is clear context, though it stops short of explicit 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?

The description discloses that the operation is reversible ('easy to roll back') and that the semantics are verified. Annotations already indicate the tool is not read-only, idempotent, or destructive, and the description adds value by confirming the single-call behavior and the conditional pin/unpin logic.

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 very concise, consisting of two short sentences that contain no redundant information. Every word adds value, and the structure is front-loaded with the main action.

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 low parameter count, full schema coverage, and presence of annotations, the description provides sufficient context for an agent to correctly select and invoke the tool. The behavior for both cases is clearly explained.

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 descriptions for both parameters. The description adds meaning by explaining that providing message_id pins the message and omitting it unpins, which goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states the action (pin or unpin a message) and the resource (message) with a specific verb. It distinguishes from sibling tools as no other sibling performs pinning. The Russian language may be a barrier for non-Russian agents, but given the tool name and title are English, it's assumed the agent understands.

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 guidance on when to use the tool: to pin or unpin a message in a single call. It explains the behavior based on the presence of message_id. However, it does not explicitly mention when not to use it or suggest alternatives, though no direct competitors exist among siblings.

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

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

Annotations already declare readOnlyHint=true, so the description need not repeat that this is non-destructive. It adds meaningful behavioral detail beyond annotations by specifying that found messages are enriched with reads, mentions, reactions, thread, forwarded, and from_me, and that found users include a chat_id for addressing. No contradiction with the read-only annotation.

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

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

The description consists of two sentences, front-loading the core search scope before adding enrichment details. Every clause contributes useful information, though the phrase 'через HTTP registry' is a minor technical detail that could be omitted without losing value. Overall it is tight and structured well.

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

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

With no output schema, the description compensates by explaining the enrichment fields returned for messages and the chat_id for users, giving the agent important expectations for results. It does not fully describe the overall response shape or how results are grouped across messages, users, and chats, but the reference to read tools plus the schema-covered parameters make it reasonably complete for 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%, with all three parameters (query, limit, entities) already documented in the schema. The tool description does not add further parameter-level meaning; its extra details address output behavior, not parameter interpretation. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

The description opens with 'Поиск по сообщениям, пользователям и чатам', which names a specific verb and three distinct resources, making the tool's purpose unmistakable. It also distinguishes itself from read tools by noting results are enriched 'так же, как в read-инструментах', which differentiates it from siblings like get_message and get_history.

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?

Usage context is implied rather than explicit: it searches across messages, users, and chats, which suggests it is for discovery when IDs may be unknown. However, there is no direct statement about when to prefer search over get_message, list_chats, or get_history, nor any when-not guidance. The reference to read tools implies a relationship but does not spell out the decision rule.

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

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

Discloses all important behavioral traits: initial call returns draft without uploading bytes, confirm call uploads and sends irreversibly; verification of chat and file against confirmed values; type determination by extension; post-send behavior (reading message and downloading attachment). No contradiction with annotations (destructiveHint=false is consistent with creating a 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?

Single paragraph in Russian is information-dense but well-organized. Every sentence adds new information. Could be slightly improved with bullet points or clearer separation of steps, but it remains efficient and 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?

Given the tool's complexity (two-step, irreversible, verification), the description covers all necessary aspects: workflow, constraints (no voice/gallery), and post-send retrieval. No output schema, but description compensates by explaining how to download the attachment after sending.

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 4 parameters with descriptions. The description adds significant value by explaining the two-step workflow for confirm and confirm_token, clarifying that path is absolute, and linking parameters to the behavioral steps. It goes beyond what schema alone provides.

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

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

Description clearly states it sends files/images in a two-step process, distinct from siblings like send_message (text) and download_attachment (retrieval). It specifies the verb (send) and resource (file or image) with precise scope (two-step, irreversible).

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?

Describes when to use (sending files/images) and the two-step workflow. It explicitly mentions that voice/gallery types are not sent (only reading). However, it does not explicitly state when not to use this tool in favor of a sibling, though the distinction is clear from 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?

Beyond annotations, the description discloses critical behavioral traits: the preview step does NOT send, sending is irreversible, and chat/text are re-verified against the confirmed values at the confirm step, with mismatches rejected. This is richer than the annotations alone and helps an agent understand side effects and safety.

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 dense sentences with front-loaded behavioral scope: the two-step mechanism, the non-sending draft step, and the irreversible confirm step. Every sentence carries essential information with no redundancy, making it efficient for an agent to parse.

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

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

Given the complex two-step flow and no output schema, the description adequately explains the draft/confirm contract and the need to return confirm_token from the draft. It does not describe the full draft response structure or error conditions, but the rich parameter schema compensates. Minor gap in return-value detail makes it slightly below 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%, and the schema already documents all seven parameters in detail, including mention resolution rules, fingerprinting, and confirm_token requirements. The description adds workflow-level context but no per-parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

Description states a specific verb and resource: 'Отправка текстового сообщения' (sending a text message). It further specifies the two-step draft/confirm behavior, which clearly distinguishes this tool from sibling send_file and other message tools. An agent can tell what it does and how it differs from a plain send.

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 workflow guidance: first call without confirm to get a draft that is not sent, then call with confirm:true and confirm_token to send. It does not explicitly name alternatives or exclusion conditions relative to siblings, but the 'text message' scope and two-step confirmation make the intended usage 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?

Discloses validation before sending, reversibility, and that remove:true removes previously set reaction. Annotations provide no behavioral details, so description adds significant 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?

Three sentences, front-loaded with key action. Slightly dense but no wasted words.

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 mutation tool with no output schema, description covers validation, reversibility, and core behavior. Adequate for 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%, but description adds context: type is integer id (not emoji) from reactions field, and remove removes a previously set reaction by same tool.

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

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

Description clearly states the tool sets or removes reactions in one call. Title and name align. Distinguishes from sibling tools like list_reactions.

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?

Implicitly describes usage (set/remove reaction) but lacks explicit guidance on when to use vs alternatives or when not to use.

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 goes well beyond the sparse annotations (all false), detailing the irreversibility of voting, replacement semantics, draft-confirm mechanism, and that canceling to zero is not supported. Annotations only indicate non-read-only, non-idempotent, non-destructive, so the description adds critical behavioral context.

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 coherent paragraph with minimal waste. It front-loads the key mechanism and each sentence adds behavioral information. Slightly dense but effective.

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 workflow and key constraints (irreversibility, replace behavior, two-step process). It lacks explicit return value details and error conditions, but given no output schema, it provides sufficient context for usage. The reference to checking myChoices via get_poll helps close the loop.

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?

All 5 parameters are described in the schema (100% coverage), but the description adds extra meaning: choices must be a full set, confirm token origin, and verification at confirm step. This adds moderate value beyond the schema's descriptions.

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 is for voting in a poll via a two-step draft->confirm process. It uses specific verbs and distinguishes the mechanism from simple voting. The name and title align, and the description explains the unique behavior of replacing votes and the confirm token.

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 implicitly tells when to use the tool (to vote in a poll) and describes the two-step flow, but it does not explicitly state when to use this tool versus alternatives like get_poll. No exclusions or alternatives are mentioned, though the sibling context suggests get_poll for reading results.

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