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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partially covered. The description still adds meaningful context beyond them: that the operation is irreversible and gated on bot ownership or admin rights.

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 compact clauses: the operation and scope first, then the irreversible-and-confirm warning. No filler, and the highest-risk information (irreversibility) is surfaced early.

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 two-parameter destructive tool with no output schema and rich annotations, the description covers scope, irreversibility, and a user-confirmation requirement. It does not cover failure behavior when the bot lacks delete rights, which is a minor gap.

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

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

Schema description coverage is 100%, with both chat_id and message_id documented in the schema, including the pointer to bot_list_chats. The description adds no parameter-level 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 (delete) and resource (message) plus the scope qualifier 'the bot may delete (its own, or as admin)', which no sibling tool covers — this is the only destructive message tool in the set.

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

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

The description gives clear context for when the tool applies (bot's own messages, or admin privileges) and an explicit precondition ('confirm with the user first'), but names no alternative tool for cases where the bot lacks permission.

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 the write-but-non-destructive, non-idempotent, open-world profile, and the description adds genuinely new context: a 20 MB size ceiling and the never-overwrite (-1, -2, ...) naming rule, which explains why idempotentHint is false. It does not mention failure behavior or whether the target folder is auto-created, so it falls short of a 5.

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

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

Two tight sentences with zero filler; the core action and size limit lead, with the overwrite rule as a useful secondary detail.

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

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

For a simple two-parameter tool with no output schema, the description covers the action, the size limit, the return value (local path), and overwrite behavior. It omits error/failure handling and folder-creation semantics, which keeps it just short of 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% – both file_id and folder (with its default) are documented in the schema. The description adds no syntax, format, or constraints for either parameter, 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 (download), resource (a file someone sent the bot), scope constraint (max 20 MB), and the return value (its local path). This cleanly separates it from bot_send_file and the other bot_* siblings without ambiguity.

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 'a file someone sent the bot' implies the precondition that file_id must come from a received message, and the schema reinforces this. However, no alternative tool is named and there is no when-not guidance (e.g., how to obtain the file_id, what to do for files the bot sends).

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the mutation profile is covered. The description adds a genuine extra: a user-confirmation requirement and the constraint that only bot-sent messages can be edited. It omits anything about the old text being lost or platform edit limits.

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, purpose front-loaded, no filler. 'Changes a real message' partially restates what the destructive annotation already conveys, but 'confirm with the user first' earns its place.

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

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

For a three-parameter mutation with full schema coverage and no output schema, the description covers purpose, scope, and the safety caution. Missing only edge-case behavior such as what happens to the replaced text or failure conditions, which is a minor gap.

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

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

Schema description coverage is 100% and each of the three parameters is documented in-schema, including the chat_id cross-reference to bot_list_chats. The description adds no format or constraint detail beyond what the schema already provides, 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 (replace) and resource (text of a message the bot sent earlier), with a scope constraint that rules out editing user-authored messages. It implicitly distinguishes itself from bot_send_message and bot_delete_message, but never names an alternative explicitly.

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

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

The only guidance is a caution to confirm with the user first; there is no statement of when to edit versus delete or re-send, nor prerequisites such as needing a message_id the bot previously produced. Usage must be inferred from the purpose sentence.

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 structurally. The description adds what data is fetched but says nothing about failure behavior (e.g. invalid chat_id), permissions, or rate limits, so it modestly clears the lowered bar without enriching 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?

A single front-loaded sentence that names the resource and its return fields with zero filler. Nothing could be removed without losing information.

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

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

For a one-parameter read tool with no output schema, the description helpfully enumerates the returned fields, partially compensating for the missing return schema. The absence of any error/not-found behavior keeps it short of fully complete.

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

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

Schema coverage is 100% and the single chat_id parameter is documented in the schema with accepted forms (numeric id or '@channel' username). The description adds no syntax or format meaning 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 (Get) and resource (chat) and enumerates the fields it returns (type, title/name, username, description). It is clearly distinct from list-oriented siblings like bot_list_chats, but the description never names or contrasts an alternative explicitly.

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

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

There is no when-to-use, when-not-to-use, or alternative routing guidance in the description. The only usage hint ('See bot_list_chats' for id form) lives in the input schema, not the description.

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 establish readOnly, idempotent, non-destructive behavior, so the bar is low, and the description still adds real context beyond them: it names the credential it inspects (BALE_BOT_TOKEN) and enumerates the fields returned (id, username, name). Since no output schema exists, disclosing the return fields is genuinely useful. It stops short of saying what happens if the token is missing or invalid.

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 short sentence with zero filler, front-loading the operation and immediately naming both the credential checked and the values returned. Nothing could be cut without losing information.

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

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

For a trivial, no-parameter identity lookup with no output schema, the description covers the essentials: what it reads, what it returns, and the implicit auth dependency. The only meaningful omission is error behavior when the token is absent or invalid.

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 there is nothing for the description to disambiguate; the baseline for a no-arg tool is 4. Schema coverage is 100% regardless of content.

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

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

The description states a concrete verb (check/show) and resource (the bot's own identity: id, username, name), which cleanly separates it from siblings like bot_get_webhook_info or bot_get_chat. It is clear, though it never explicitly names an alternative tool, so sibling differentiation is more implicit than stated.

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: checking BALE_BOT_TOKEN suggests a credential/identity verification context (e.g., confirming the bot is configured correctly before using other tools). There is no explicit when-to-use framing, no exclusions, and no pointer to any alternative.

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?

Goes beyond annotations by disclosing why readOnlyHint=false: the call marks messages read, an irreversible state change. It also surfaces a non-obvious failure precondition (webhook configured) and the delivery order, none of which the annotations express. No contradiction with readOnlyHint=false / destructiveHint=false.

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

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

Front-loaded with purpose, scope, ordering and side effect in one sentence, then response fields, then the failure condition. No filler; each sentence carries distinct information an agent needs.

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 enumerating the response fields (chat_id, from, kind, text, file_id, unread_left) and pointing to bot_download_file for media. Given a 1-param, no-required-param tool, nothing needed to invoke it correctly is missing.

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

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

One parameter with 100% schema description coverage plus a documented default and range, so the schema already carries the meaning. The description does not mention 'limit' or explain truncation behavior beyond 'unread_left counts the rest', which is baseline-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?

States a specific verb+resource with scope and semantics: 'Get messages people sent the bot since the last check, from all chats, oldest first, and mark them read.' The polling scope ('since the last check') and ordering distinguish it clearly from siblings like bot_search_messages and bot_read_chat.

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

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

Implies the polling use case ('since the last check') and gives a concrete precondition — 'Fails while a webhook is set (see bot_get_webhook_info)' — which routes the agent to a sibling for diagnostics. It does not explicitly contrast with bot_search_messages or bot_read_chat, so the when-not is only partial.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine value beyond them by disclosing the returned fields and, crucially, the interpretation rule for the url field (empty = reading tools work), which no annotation conveys. It stops short of covering pending-update or error semantics, so it is not a 5.

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

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

A single sentence, front-loaded with the core purpose and parenthesizing the interpretation hint. Every clause earns its place with zero 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 no parameters, no output schema, and annotations covering the safety profile, the description carries the return-value burden and does list the three things returned. It is complete enough to call the tool correctly, though the meaning of 'pending updates' and expected recovery on 'last error' are left 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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and no parameter text is needed.

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

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

The description names a specific verb+resource (show webhook status) and enumerates exactly what is returned: whether a webhook is set, pending updates, and the last error. The parenthetical 'url empty = the reading tools work' links this tool to the sibling read tools (bot_read_chat, bot_get_new_messages), so an agent can tell why this call matters alongside 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?

Usage is implied rather than stated: the note that an empty url means 'the reading tools work' hints this is a diagnostic to run before relying on read tools, but there is no explicit 'use this when messages are missing' or when-not guidance. An agent can infer the diagnostic context but must do the inference itself.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real value beyond them by disclosing sort order ('newest first') and the payload shape (unread count, last message). It says nothing about pagination or rate limits, keeping it out of 5 territory.

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 resource and scope, followed immediately by the practical purpose. Nothing is redundant or padded.

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 usefully names the returned fields and ordering so an agent knows what comes back. The only gap is ordering/pagination nuance around the limit parameter, which is minor for a simple listing 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 one parameter at 100% schema description coverage, the schema already documents 'limit' including its 1-500 range and default. The description adds no format or behavior detail for that parameter, 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?

States a specific verb (List) and resource (chats this bot has talked in), and names the returned fields (unread count, last message), which separates it from bot_get_chat and bot_search_messages. It never explicitly contrasts itself with a sibling, so it stops 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?

Gives one concrete use case ('Use to find chat ids'), which implies when the tool is useful, but offers no exclusions and does not point to bot_get_chat or bot_search_messages as alternatives for narrower lookups.

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 declare readOnlyHint=false, which the description justifies by disclosing the 'mark the chat read' side effect, and it further clarifies data provenance ('Bale itself keeps no history'), explaining why results come from the local store. This adds genuine context beyond the annotation flags, though it omits ordering guarantees for the read-marking side effect and any error behavior.

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

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

Two short sentences with the primary action front-loaded, followed by the provenance caveat. Nothing is wasted and no filler is present.

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 two-param read tool with no output schema, the description covers the action, ordering, side effect, and data source well. It could still note the default limit or the message shape returned, but the essentials are present.

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

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

Schema description coverage is 100%, so both parameters (chat_id, limit with default 20/max 500) are already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, 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+resource ('Show a chat's recent messages... and mark the chat read') with ordering (oldest first) and a source constraint (local store). It distinguishes itself from bot_get_new_messages by emphasizing 'recent' and 'local store', but never names a sibling, so the differentiation is implicit rather than explicit.

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

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

Usage is only implied through the 'local store' provenance note, which hints at a distinction from live-fetch siblings like bot_get_new_messages or bot_wait_for_reply. There is no explicit when-to-use/when-not or named alternative, leaving the agent to infer 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 only carry generic hints (openWorldHint=true, readOnlyHint=false, destructive=false), so the description earns credit for disclosing real behavior: newest-first ordering, Persian/Arabic yeh/kaf/digit/ZWNJ normalization equivalence, and the '...(+N chars)' truncation marker with a pointer to bot_read_chat for full text. These are non-obvious traits an agent could not derive from the schema.

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

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

Two tight sentences with zero filler; the core purpose is front-loaded and the normalization/truncation caveats follow as needed detail. Every clause carries information an agent needs.

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 does the important work of explaining result ordering, matching rules, and truncation behavior. It leaves the default all-chats scope (chat_id default null) and limit/pagination behavior to the schema, which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the 3 baseline applies, but the description adds genuine meaning beyond it: it explains what max_chars produces in the output (a '...(+N chars)' marker) and clarifies that query matching is normalization-aware, which the schema's bare "Text to find." does not convey.

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 ("Search stored messages by text") plus the result ordering ("newest first"), and names a sibling (bot_read_chat) as the alternative for untruncated text. It does not explicitly distinguish itself from bot_get_new_messages, so sibling differentiation is partial rather than complete.

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 implied ("search stored messages") and one routing rule is given for the truncation case (use bot_read_chat for full text). There is no explicit statement of when to prefer this over bot_get_new_messages or bot_list_chats, so guidance remains inferential.

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, so the risk profile is largely covered structurally. The description does add two useful pieces of context beyond that: the mandatory user confirmation step and the filesystem sandbox (BALE_MCP_SEND_DIRS, defaulting to the download folder only). It does not disclose that a retry will re-send the file given non-idempotency, which for a destructive external action is a notable omission.

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 the purpose front-loaded, followed by the safety instruction and then the filesystem constraint. No filler, and each sentence carries distinct, actionable 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?

There is no output schema, and the description never says what comes back on success (e.g. a message id the agent could later use with bot_edit_message or bot_delete_message). For a non-idempotent destructive send, that plus the absence of any failure/retry note leaves a real gap, though the confirmation rule and path sandbox cover the most dangerous aspects.

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

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

Schema description coverage is 100%, so all four parameters — including the kind enum, the source URL-or-path union, the caption length limit and the chat_id/@channel form — are already documented in the schema itself. The description adds only the default value of BALE_MCP_SEND_DIRS and repeats the file-type list, so baseline 3 is appropriate.

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

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

The description gives a specific verb (send) plus the resource (photo/document/video/audio/voice file) and explicitly says 'from the bot', so the agent knows this performs an outbound upload rather than a text reply. It never names bot_send_message or bot_download_file as the contrasting siblings, so differentiation is implied rather than stated.

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 first' is a genuine procedural guideline, and the BALE_MCP_SEND_DIRS note tells the agent when a local path is acceptable. However, there is no guidance on when to pick this over bot_send_message for text content, nor any statement about when not to use it — routing 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is partly covered. The description adds genuine context beyond them: a user-confirmation instruction ('Confirm recipient and text with the user first'), the Markdown formatting contract, and the prerequisite that the recipient must have started the bot. It omits rate limits and does not explicitly say the send is irreversible, but the confirmation warning is the operationally important part.

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

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

Front-loaded with the action in the first sentence, then prerequisites and follow-up. Dense but nearly every clause carries operational information; the final sentence packs two distinct instructions (buttons, then bot_wait_for_reply) into one line, which is slightly compressed but not wasteful.

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 usefully mentions the returned message_id and how to consume it, and it covers prerequisites, formatting, and a confirmation caution. An agent has enough to call the tool correctly; only edge cases such as failure/error behavior are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by explaining the purpose of the buttons parameter (asking a question with fixed choices) and by noting that the call returns a message_id used for bot_wait_for_reply, which links the parameters to a workflow the schema cannot express.

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 real text message from the bot') and implicitly separates itself from siblings bot_send_file (files) and bot_edit_message (modifying existing messages). The word 'real' signals the message is actually dispatched to an external chat, which matches the openWorld annotation.

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 prerequisite ('The user must have sent the bot /start first, or the bot is in the group/channel') and an explicit workflow for the question case, routing the agent onward to bot_wait_for_reply with the returned message_id. It does not, however, state when to prefer bot_edit_message or bot_send_file instead, so the alternative-selection guidance is partial.

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 signal readOnlyHint=false and idempotentHint=false, but the description adds the reason: returned messages are "marked read," a side effect an agent must know about. It also discloses the timeout contract (timed_out=true, no messages), which annotations alone do not convey. No contradiction with the non-read-only, non-idempotent hints.

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: the first defines the action and side effect, the second gives the call-site and retry rule. No filler and the core behavior is front-loaded.

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

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

With no output schema, the description carries the return-value burden and does so partially: it explains the timeout case but not the shape of the returned messages. For a blocking tool with rich annotations and full param coverage, this is nearly complete but not exhaustive.

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 fully documented in the schema. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the work.

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: it waits for chat activity (message or button press) and returns new messages. The blocking/waiting nature clearly separates it from polling-style siblings like bot_get_new_messages, though it never names that 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?

"Use after bot_send_message" gives a concrete trigger, and "call again to keep waiting" defines the retry loop for the timeout case. It stops short of saying when to prefer this over bot_get_new_messages or bot_read_chat.

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