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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds real value beyond that: it declares the operation is irreversible ('Cannot be undone') and imposes a user-confirmation requirement, plus the permission precondition for deletion.

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

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

A single sentence that front-loads the action, then the permission scope, then the irreversibility warning. No filler 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?

With an output schema present, return values need not be explained. The description covers the two things an agent actually needs before calling a destructive tool: the permission condition and the irreversibility/confirmation requirement.

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 both parameters carry their own descriptions (chat_id formats, message_id). The tool description adds no parameter-level syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a message') and then narrows the scope to 'a chat where the bot may delete it (its own messages, or as admin)', which distinguishes it from siblings like bot_edit_message or bot_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?

Gives a clear precondition for use — the bot must own the message or be an admin — and adds the procedural guardrail 'confirm with the user first'. It does not name an alternative tool or state when deletion should be avoided, 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?

Adds real behavior beyond the annotations: a 20 MB size cap and an explicit non-overwrite policy with -1/-2 suffixing. The suffix rule is worth knowing because repeated calls yield new distinct files, which sits in mild tension with the idempotentHint=true annotation, though the read/write profile still broadly matches readOnlyHint.

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

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

Two short sentences, front-loaded with the action and destination, with the size limit and overwrite rule as the only supplementary facts. Nothing is redundant.

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 return value needn't be explained further, and the description still names the local-path return. Size cap, overwrite behavior, destination default and the file_id requirement are all covered, leaving nothing an agent needs 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% — file_id's accepted message types and folder's default path are both documented in the schema. The description adds the 20 MB constraint but no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Download a file someone sent the bot to this computer') plus the return value ('return its local path'). Clearly distinct from the sibling bot_send_file, which pushes files out rather than pulling them in.

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 is only implied: the agent must infer it needs a file_id obtained from a received message. There is no explicit 'use when' statement, no mention of prerequisites (e.g. the message must still be retrievable), and no routing to siblings for the reverse direction.

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, idempotentHint=false, and readOnlyHint=false, so safety is covered structurally. The description adds value beyond them by framing the edit as a real-world mutation ('Changes a real message') and imposing a user-confirmation workflow, though it omits failure modes like editing a message too old to change.

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 and constraint, then the action warning. Nothing is padded and every sentence carries 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description covers purpose, mutation semantics, and a confirmation safeguard; only edge cases (non-bot messages, age limits, notification side effects) are left unstated.

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 all three parameters are documented in-schema (chat_id accepts numeric id or @username, message_id must be a bot-sent text message, text is the new body). The description adds no syntax or format detail beyond that, 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?

States a specific verb (replace text), resource (a message), and a scope constraint (one the bot sent earlier). This cleanly distinguishes it from bot_send_message, bot_delete_message, and message-reading siblings without opening any 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 clear context for invocation ('a message the bot sent earlier') plus an explicit pre-call requirement to confirm with the user. It stops short of naming alternatives (e.g., prefer bot_send_message when the original shouldn't change), so it is not fully explicit 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and open-world behavior, so the safety profile is covered. The description adds a genuinely useful nuance beyond that: 'as seen by the bot' signals that the returned metadata is scoped to what the bot can perceive, which is not expressible in annotations and matters for a bot-facing lookup.

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

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

A single tight sentence with no filler, and the verb and resource are front-loaded before the field list. 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 present, the description need not explain return formats, and the single parameter is fully documented. It covers what is fetched and the bot-relative perspective, though it omits any guidance on failure cases (e.g. chat not found, bot not a member).

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

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

Schema coverage is 100% and the chat_id description already explains both accepted forms (numeric id sourced from bot_get_new_messages/bot_list_chats, or a '@username' handle). The tool description adds nothing further about the parameter, so the baseline of 3 for a fully-documented schema is correct.

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 specific verb and resource ('Get a chat's type, title or name, username and description') and even enumerates the returned fields, so the agent knows exactly what it retrieves. It does not, however, name or contrast itself against close siblings like bot_list_chats or bot_read_chat, which is the only thing keeping it from a 5.

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

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

There is no explicit statement of when to use this tool versus bot_list_chats, bot_read_chat, or bot_search_messages. The only routing hint ('number from bot_get_new_messages or bot_list_chats') lives in the schema's chat_id description, not in the tool description, so usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context the annotations lack: the dependency on the BALE_BOT_TOKEN environment variable as the auth source, which tells the agent failure here likely means a credential problem.

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

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

Two short sentences with no redundancy: the first says what it returns, the second says when to call it. Fully front-loaded with nothing wasted.

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-value explanation is unnecessary, and annotations cover the safety/idempotency profile. For a zero-parameter identity probe the description supplies everything an agent needs 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?

Zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify, and it correctly adds none.

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 concrete verb-plus-resource ('Check BALE_BOT_TOKEN and show the bot's id, username and name') and enumerates exactly what is returned. An agent can tell this is an identity/health probe rather than a messaging or chat-reading tool.

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

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

'Use first to confirm the bot works' gives explicit sequencing guidance relative to the sibling bot_* tools. It stops short of naming a specific alternative or stating when-not to use it, but the placement advice is actionable.

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 says the call will 'mark them read', which mutates server-side read state, yet the annotations declare readOnlyHint=true (and idempotentHint=true). This directly contradicts the annotation: a get-that-writes is not a read-only tool. Aside from that, the description does add genuinely useful context (failure mode when a webhook is set, message shape, prompt-injection warning), but the contradiction is disqualifying.

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 purpose and side effect in the first sentence, then message shape, then a security note, then the failure condition. Every sentence carries information an agent needs; no 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?

With an output schema present and 100% schema coverage, the description is nearly complete: it covers purpose, scope, message structure, alternatives, failure mode and injection risk. The one gap is that the mutation implied by 'mark them read' is not reconciled with the read-only annotation.

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 is a single optional parameter (limit) and schema coverage is 100%, so the schema already carries the meaning, bounds and default. The description adds no parameter detail, so the baseline 3 for fully-documented parameters is correct.

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

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

States a specific verb and resource (get messages sent to the bot) plus the scope (since last check, all chats, oldest first). An agent can immediately distinguish this from siblings like bot_search_messages, bot_read_chat and bot_wait_for_reply.

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 clear context for use and names two sibling alternatives with the condition that selects them (bot_download_file for media, bot_get_webhook_info when a webhook is set). It does not explicitly contrast against bot_search_messages or bot_wait_for_reply, so routing is good but not exhaustive.

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 destructiveHint=false, so safety is covered. The description usefully adds the diagnostic semantics of an empty url, but says nothing about cost, rate limits, or freshness of the reported data.

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

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

A single front-loaded sentence that lists the three returned facts with no filler. 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 present and zero parameters, the description need not explain return values and is largely sufficient for this diagnostic tool. It only falls short of 5 by leaving the call-triggering condition implicit.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics to add and none are missing.

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+resource: it reports webhook status, pending updates, and last error. The name and description together make it distinguishable from the message/chat siblings, though it never explicitly differentiates itself from them.

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

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

The parenthetical '(url empty = the reading tools work)' implies the diagnostic use case, but there is no explicit when-to-call guidance, no prerequisites, and no named alternative. Usage must be inferred.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the sort order and the fact that unread count and last message are included, which is mild extra context, but it says nothing about pagination behavior or how the limit interacts with the result set.

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

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

Two short sentences, zero waste, with the core listing behavior front-loaded ahead of the usage hint.

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 annotated read tool with an output schema already covering return values and a fully documented single parameter, the description is essentially complete. It stops short of a 5 only because it is silent on pagination/large-result 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?

Only one parameter (limit) and schema description coverage is 100% ('Max chats.' plus min/max/default), so the schema carries the meaning. The description adds no constraint or format detail about limit, making this the baseline 3.

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 (chats this bot has talked in), plus ordering (newest first) and returned fields (unread count, last message). It is distinguishable from bot_get_chat (single chat) and bot_search_messages, though it never names a sibling explicitly, so it lands just short of a 5.

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

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

'Use to find chat ids' implies the use case but offers no when-not guidance and no explicit routing to alternatives like bot_get_chat or bot_search_messages. Usage is suggested rather than 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?

The description explicitly says the tool will 'mark the chat read', a state-changing side effect, while the annotations declare readOnlyHint=true (no environment modification). The local-store disclosure is genuinely useful, but the stated write behavior directly conflicts with the declared read-only contract, which is the dominant factor.

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 the action and ordering; the second sentence supplies data-provenance context that earns its place. Slightly more prose than strictly needed for such a short tool.

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

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

An output schema exists, so return values need not be described, and the description covers data provenance and the read-marking side effect. The only gap is the misalignment of that side effect with the declared read-only annotation.

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 both chat_id and limit fully documented in the schema, so the baseline is 3. The description adds no parameter-level detail (e.g., what counts as 'recent' versus limit) 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 and resource ('Show a chat's recent messages'), plus ordering ('oldest first') and directionality ('both directions'). It implicitly separates itself from siblings like bot_get_new_messages (incoming only) and bot_search_messages, but never names an alternative explicitly, so it falls short of a 5.

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

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

The description conveys the context (chat history, local store) but gives no explicit when-to-use/when-not or alternative routing guidance among the many sibling chat/message tools. Usage is only implied.

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 covered. The description adds genuinely non-obvious behavior: results are ordered newest first, and the index normalizes Arabic/Persian yeh/kaf variants, Persian vs Latin digits, and ZWNJ presence, so the agent knows matching is fuzzy rather than exact.

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, front-loaded with the core action and ordering, followed by the matching-semantics caveat. No filler, though the Unicode sentence is dense and could be trimmed slightly.

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 values need not be explained, and the description covers ordering and match normalization. It stops short of stating that omitting chat_id searches across all chats, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so limit, query, and chat_id are already documented. The description adds only that matching happens by text, without explaining the default all-chats scope when chat_id is omitted or the ordering/limit interaction. 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 (stored messages) with a scope qualifier ('newest first'). It is clear what the tool does, though it does not explicitly distinguish itself from the sibling bot_get_new_messages, leaving the agent to infer that this searches the historical store rather than polling for new arrivals.

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 'stored messages' implies a historical search use case versus live retrieval, but no when/when-not guidance or named alternative (e.g. bot_get_new_messages) is given. Usage is only implied.

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, openWorldHint=true and idempotentHint=false. The description reinforces this usefully with "Sends a real message," conveying an irreversible real-world side effect, plus the confirmation requirement — context the annotations do not express.

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 filler: the action and supported kinds lead, the side-effect disclosure follows, and the safety precondition closes. 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 the size/format constraints live in the schema. The description covers the action, its real-world consequence, and the confirmation prerequisite; only explicit sibling routing is absent.

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 chat_id, kind, source and caption are already fully documented in the schema (including the 50 MB limit and the URL/local-path options). The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb (send) and resource (photo/document/video/audio/voice file), enumerating the supported kinds so the agent knows exactly what payloads are valid. It distinguishes itself implicitly from bot_send_message (text) and bot_download_file (opposite direction), but never names a sibling explicitly.

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

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

"Confirm recipient and file with the user before calling" is a clear precondition that gives usable operational context. It does not, however, say when to prefer this over bot_send_message or other siblings, so routing guidance 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 flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: text is rendered as Markdown, delivery fails unless the recipient has started the bot, and there is a human-confirmation expectation before sending. It stops short of describing failure modes or delivery semantics in detail.

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 tight sentences, front-loaded with the core action and the user-confirmation warning, with the workflow and precondition detail following. Every sentence carries actionable information with no 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?

With an output schema present, return-value documentation is unnecessary, and the description covers what the schema and annotations cannot: Markdown rendering of the message body, the /start precondition, the confirmation requirement, and the button/wait_for_reply workflow. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3. The description adds meaning beyond the schema by explaining that all text is formatted as Markdown, which affects how the 'text' argument should be authored, and by clarifying the message_id handoff used with reply_to_message_id and bot_wait_for_reply.

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 ('Send a text message from the bot') and immediately clarifies it is a real, externally visible send. This cleanly separates it from siblings like bot_send_file, bot_edit_message, and bot_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?

Gives explicit preconditions (the recipient must have sent /start, or the bot must be in the group/channel) and an explicit routing rule to the alternative: to get an answer, send the message then call bot_wait_for_reply with the returned message_id. It also warns to confirm recipient and text with the user before calling.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses the important side effect that returned messages are 'marked read', plus the timeout contract ('returns timed_out=true and no messages'). Note the mild tension: marking messages read is a server-state mutation while readOnlyHint=true; the description at least surfaces it rather than hiding it.

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, each load-bearing: what it waits for, when to use it, and what the timeout/retry behavior looks like. The core behavior is front-loaded with no preamble.

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 blocking-wait tool with full schema coverage, an output schema, and rich annotations, the description covers everything an agent needs: trigger, sequencing with bot_send_message, timeout result shape, and the re-call pattern.

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 chat_id, timeout_seconds and after_message_id are already fully documented in the schema, including the subtle 'button press on it counts' semantics. The description adds no additional parameter meaning, 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 gives a concrete verb+resource+behavior: it waits until someone writes or presses a button, then returns the new messages. That is far more specific than the title. It does not, however, explicitly contrast itself with the sibling bot_get_new_messages, which is the tool an agent is most likely to confuse it with.

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 states the trigger clearly ('Use after bot_send_message to hold a conversation or ask the user for approval') and explains the retry pattern ('call again to keep waiting'). There is no explicit when-not guidance (e.g. use polling instead when you cannot block), but the context is unambiguous.

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