Lemma Telepath

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds the meaningful behavioral constraint that titles are unique, which explains the non-idempotent hint and implies a failure path on collision. It stops short of stating the error behavior or required permissions, so 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?

Front-loads the core action, then uniqueness/routing, then body and tag semantics, with no redundant sentences. Every sentence carries distinct 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?

Covers purpose, collision handling, body format, linking syntax, and tag intent for a three-parameter create tool with no output schema. The main gap is the return shape (e.g., created note id), but safety is already covered by annotations, so the definition is otherwise call-ready.

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 three parameters are already documented, including markdown formatting and [[links]] in body. The description adds only the rationale that tags aid later retrieval, which is marginal beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Save a new note'), and explicitly routes the update case to the sibling kb_update_note. An agent can distinguish this from kb_update_note, kb_get_note, and kb_list_notes 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 an explicit alternative and the condition that selects it: 'Titles are unique; if one exists, use kb_update_note instead.' This is exactly the when-to-use / when-not-to-use routing that makes a description 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is largely covered; the description adds the useful irreversibility note ("Permanently", "cannot be undone"). It still says nothing about what happens when no note matches, when both id and title are supplied, or whether any confirmation step exists.

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

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

One sentence, front-loaded with the verb and resource, and the destructive warning is appended without padding. 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?

For a destructive two-parameter tool whose annotations already flag destructiveness, the description covers the operation, the lookup keys, and irreversibility. Remaining gaps (no-match behavior, handling of both keys, confirmation requirements) are minor given there is no output schema to explain.

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 both parameters are optional with no required fields, so the schema does the heavy lifting. The phrase "by id or exact title" does imply an either/or selection, which is marginal added meaning over the schema, matching 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 (delete) and resource (note in the knowledge base) plus the two lookup keys, so it is unambiguous against kb_create_note, kb_get_note, and kb_update_note. It does not explicitly name a sibling or contrast itself with one, keeping it 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?

"by id or exact title" tells the agent which lookup keys are accepted, and "cannot be undone" signals this is the irreversible path, but there is no explicit when-to-use guidance or routing away from kb_update_note for soft edits. Usage is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description earns credit by disclosing the actual return payload including the link graph and backlinks. It stops short of stating what happens when no note matches or when id and title disagree.

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 clauses, front-loaded with the core action and then the return contents, with zero filler. Every phrase carries information an agent can use.

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 correctly carries the burden of describing what comes back (body, tags, links, backlinks) and how to address the note. Only edge behavior — not-found handling and id/title precedence — is left unstated for a tool whose required-parameter count is zero.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' and 'title' including the 'exact title, if you do not have the id' caveat. The description restates the id-or-exact-title addressing rule without adding precedence or fallback semantics, 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?

The description gives a specific verb and resource ('Read one note in full') and even enumerates the payload: body, tags, outbound [[Title]] links, and backlinks. That is enough to separate it from kb_list_notes/kb_search_notes by implication, but it never names those siblings or states the contrast 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?

It tells the agent how to address the note ('by id or by exact title') but never says when to reach for this tool instead of kb_search_notes or kb_list_notes. Usage is inferable — fetch a single known note — but not stated, and there are no exclusions or prerequisites.

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 the safety profile is covered. The description adds the ordering guarantee ('newest first'), which is genuine value beyond the annotations, but says nothing about pagination or result limits despite the limit parameter.

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 action and ordering front-loaded before the optional filter. Appropriately sized for the tool's simplicity.

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

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

For a simple read-only list tool with annotations covering safety and no output schema, the description is largely adequate. The unaddressed limit/pagination gap and lack of sibling differentiation keep it at minimum viability.

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 only 50%: 'tag' is documented in the schema and merely restated in the description, while 'limit' is undocumented in both schema and description, including no mention of its 1-200 bounds. The description adds no parameter meaning beyond what the schema already 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?

Specific verb+resource ('List notes') with a stated ordering ('newest first'), so an agent knows exactly what it returns. However, it does not differentiate itself from the close sibling kb_search_notes, leaving the boundary to inference.

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 'Optionally only those with a given tag' hints at the tag-filter use case, but there is no guidance on when to use this versus kb_search_notes or kb_get_note. No exclusions or alternatives are named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld=false, non-destructive), and the description adds behavior the annotations do not: the last word is prefix-matched, results can be tag-restricted, and 'nothing leaves the server' discloses locality. It does not cover result ordering or pagination, which is a minor gap.

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?

Four short sentences, each carrying distinct information (what it searches, prefix rule, tag filter, locality, empty-query fallback), with the core purpose front-loaded and 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 no output schema and a partially documented input schema, the description supplies the search semantics an agent needs to call it correctly. It is nearly complete, though it omits how results are ordered and whether the limit defaults to anything.

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 67%; the description compensates by explaining the prefix-match rule for the query's last word and restating the empty-query semantics that the schema also documents. The 'limit' parameter is left unexplained in both places, which keeps this below a 5.

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 ('Full-text search over your personal knowledge base'), which is enough to separate it from kb_get_note and kb_create_note. It does not explicitly contrast itself with the closer sibling kb_list_notes, 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?

It gives a concrete usage rule — an empty query lists recent notes — which tells the agent how this tool behaves at its boundary and implicitly when it overlaps with kb_list_notes. It never explicitly names an alternative tool or a when-not condition, so it is clear context without exclusions.

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

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

Annotations already flag destructiveHint=true and non-idempotent, so the bar is lower; the description still adds the key behavioral detail that an omitted append replaces the existing body, plus the partial-update contract ('pass only what changes'). It does not warn about the dual role of title (identifier vs new value) or behavior on ambiguous title matches.

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 action, then addressing, then the one non-obvious flag. The 'add this to my notes' phrase earns its place by making the append path immediately recognizable.

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 5-parameter, zero-required, destructive mutation tool with no output schema, the description covers action, addressing, partial-update semantics and the append/replace branch. The remaining unknowns (ambiguous title resolution, field-preservation on omitted tags/title) are minor.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning by clarifying that id or exact title are alternative addressing keys and by spelling out the append-vs-replace outcome for body. It leaves the title parameter's dual purpose (find it vs rename it) unresolved.

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 ('Change an existing note'), which clearly separates it from kb_create_note, kb_delete_note and the read-only siblings without naming them. It is not a tautology, but it never explicitly routes against the closest alternatives (create vs update, get vs update).

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 real operational guidance: address by id or exact title, pass only what changes, and use append=true for the 'add this to my notes' path versus replacement otherwise. No explicit when-not-to-use or sibling routing, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a useful behavioral nuance — this is a different conversation that can share the same chat_id, kept separate deliberately — but says nothing about return shape, ordering, or pagination 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?

A single dense sentence that front-loads the identity of the resource and then the exclusions. It is efficient with no filler, though the nested 'kept separate because it is a different conversation with the same chat_id' clause is slightly convoluted.

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, so the description carries the burden of return expectations, and it only implies 'messages' without describing fields, ordering, or how limit interacts with paging. For a one-parameter read tool the conceptual explanation is solid, but the retrieval mechanics 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?

The single parameter (limit, 1-100) has 0% schema description coverage and is never mentioned in the description, so neither structured data nor prose explains its meaning, default, or effect. With coverage this low the description is expected to compensate and it does not.

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

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

The description states a specific resource and scope: messages sent straight to the bot's own account, explicitly distinct from the owner's Business connection. It names the two sibling tools (telegram_get_messages, telegram_search_messages) that do NOT cover this case, so an agent can distinguish it without opening a schema.

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

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

It clearly signals the routing condition by stating this chat is a separate conversation not covered by telegram_get_messages or telegram_search_messages, which effectively tells the agent when to pick this tool. It stops short of an explicit trigger phrase (e.g. 'use when the user asks about DMs sent to the bot'), and it doesn't name the other bot-DM siblings (telegram_bot_dm_reply/react) as related actions.

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 (destructiveHint=true, idempotentHint=true, openWorldHint=true), and the description adds genuinely new behavior: the other person is notified, only standard Telegram emoji are accepted, and omitting emoji removes the reaction. The notification side effect is exactly the kind of consequence an agent needs before acting.

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?

Four sentences, all information-bearing, with the scope constraint front-loaded before the caveats. Slightly dense, but nothing is redundant with 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 mutation tool with no output schema, the description covers scope, side effects, parameter edge cases, and a user-confirmation safeguard. An agent has everything needed to call it correctly and safely.

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. The description adds a constraint not in the schema — only standard reaction emoji are accepted — and reinforces the omit-to-remove semantics for `emoji`, going modestly beyond the structured fields.

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 (react) and resource (a message in the bot's OWN DM), and immediately scopes it against the main archive and other chat types. An agent can distinguish it from telegram_set_reaction or telegram_bot_dm_reply without opening a schema.

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

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

Gives clear context: only chats returned by telegram_bot_direct_messages, explicitly not groups and not 1:1 business chats, plus a 'confirm with the user first' instruction. It never names the sibling tool to use for the excluded chat types (e.g. telegram_set_reaction), so the routing guidance is one step short of fully explicit.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the recipient sees and is notified, so confirmation is required, and that the chat_id overlaps with a different conversation. It stops short of rate limits or delivery failure behavior, so 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?

Front-loaded with the core action and scope, and each sentence carries weight (the chat_id trap, the sibling routing, the confirmation requirement). Slightly dense but no wasted 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?

For a two-parameter messaging tool with no output schema and full annotation coverage, everything an agent needs is present: what it does, which sibling to prefer, the chat_id ambiguity, and the user-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 coverage is 100%, so the baseline is 3, but the description adds meaning by clarifying that chat_id comes from telegram_bot_direct_messages and that the same chat_id denotes a different conversation than the business chat — resolving a real ambiguity the schema cannot.

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

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

The description states a specific verb (Reply) and resource (the bot's OWN direct chat / bot DM line), and explicitly distinguishes it from telegram_send_message and the business chat. An agent can identify the tool 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?

It gives explicit routing: 'use this for the bot's DM line, and telegram_send_message for your business chats,' and adds a precondition ('confirm the message with the user first'). Both the when and the alternative are named.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the mutation profile is covered. The description adds real value beyond that: the edit is recipient-visible and Telegram marks the message as edited, which tells the agent the change is externally observable and irreversible in appearance. It does not discuss permission requirements or failure modes.

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

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

Three short sentences, front-loaded with the core action and then the constraint, with no filler or redundancy. Every sentence carries a distinct fact.

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

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

No output schema exists, and the annotations plus description together cover the safety profile and the observable effect of the edit, which is sufficient for a three-parameter mutation tool. Minor gaps remain around what happens on invalid or too-old message IDs, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% with three well-documented parameters, so the schema carries the parameter burden and the baseline is 3. The description reinforces the ownership constraint on message_id ('the user's own already-sent messages') but adds no format, length, or ID-resolution detail beyond the schema.

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

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

States a specific verb and resource ('Rewrite one of the user's own already-sent messages') and immediately scopes it to the user's own sent messages, which cleanly separates it from telegram_send_message (new messages) and telegram_get_messages (reads). An agent can identify the operation and its boundary without opening the schema.

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

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

'Incoming messages cannot be edited' is an explicit when-not condition, which is genuinely useful routing information. However, it never names an alternative (e.g., send a new message or reply via telegram_bot_dm_reply) for the case where editing is not possible, so the guidance stops short of full 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: substring and case-insensitive matching across any alphabet, so partial names work. It does not discuss ambiguity when multiple candidates match, but it adds real operational context 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?

Two sentences plus a short imperative, front-loaded with the core purpose and matching semantics. Every clause carries information; nothing is redundant with the title or schema.

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 helpfully states the return value (chat_id) and that it feeds into telegram_get_messages. It is slightly incomplete about what happens with multiple matches given the limit parameter, but otherwise sufficient for a simple lookup tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning by clarifying that partial/substring names are acceptable and that any of the identifier forms can be used interchangeably. It says nothing extra about the `limit` parameter, but the schema documents that fully.

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 precise verb+resource (resolve a person to their chat_id) and enumerates the accepted identifier forms (first name, last name, @username, numeric id). This is clearly distinguishable from sibling tools like telegram_list_chats, which enumerate chats rather than resolve a person.

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 ordering guidance: 'Call this before telegram_get_messages,' which tells the agent when this tool belongs in a workflow. It does not name a when-not condition or an alternative resolver, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/non-destructive/idempotent, yet the description adds substantial behavioral context beyond them: the exact shape of returned content (cells, paragraphs, rows), the tab-separated row format with '## name' sheet headings, what a media file returns, and the 20 MB bot-serving limit. This is exactly the kind of disclosure annotations cannot supply.

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

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

Front-loaded with the core action, then branches cleanly into text formats, media formats, and the size constraint. Every sentence contributes actionable information; nothing is 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 output schema, the description carries the return-value burden and does so: it explains text output, spreadsheet layout, pagination feedback, media metadata, and the hard 20 MB failure condition. An agent has everything needed to invoke and interpret it.

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

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

Schema description coverage is 100%, so the parameters are already documented; the description adds only the paging/format context around large files rather than per-parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Read a file someone sent') and immediately gives the resource scope without opening a schema. It also implicitly separates itself from sibling tools like telegram_get_photo/telegram_show_photo by noting that media yields metadata rather than text.

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

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

Gives concrete selection criteria: 'Use the chat_id and message_id of a message whose message_type is not \'text\''. It also clarifies the split between textual and non-textual attachments. It does not explicitly name the sibling to use for images, but the context is clear enough for correct selection.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description still adds substantive behavior: chronological ordering, the presence of is_forwarded/forward_origin fields, and the semantic distinction that 'from' on a forward is the forwarder, not the original author. The explicit warning against inferring a hidden author's identity is genuinely useful anti-hallucination context beyond any structured field.

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

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

Front-loaded with the core purpose and ordering, then the prerequisite, then the forward-handling caveats. The trailing sentences about authorship are longer than typical but each prevents a concrete misinterpretation of returned data, so they earn their space. No redundant restatement of the name.

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 burden of explaining the returned message shape, and it does so for the tricky parts (is_forwarded, forward_origin, from semantics). For a 4-parameter read tool this is nearly complete; the main omission is explicit paging behavior for 'before', though the schema covers that parameter's meaning.

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/since/before/chat_id are already fully documented in the schema and the baseline is 3. The description only adds that chat_id comes from telegram_find_chat and that results are oldest-first; it does not clarify the since/before paging semantics beyond what the schema states.

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 ('Message history of one conversation') plus the ordering ('oldest first so it reads as a transcript'). It routes to telegram_find_chat for chat_id, but never differentiates itself from the close siblings telegram_recent_messages and telegram_search_messages, which also return messages. Clear purpose, incomplete sibling discrimination.

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 actionable prerequisite ('Resolve a person's name to chat_id with telegram_find_chat first') and a caution about interpreting forwards. However, it offers no guidance on when to choose this over telegram_recent_messages or telegram_search_messages, so the when-to-use decision for a full-history read vs. a recent/search read is left implicit.

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 safety is covered. The description adds real behavior beyond that: the tool returns a link that should be included in the reply, and the input must be a photo-type message. It stops short of describing image format/size limits or failure modes, so it is not a full 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?

Four short sentences, each with a distinct job: purpose, input precondition, sibling for the multi-photo case, and the required link-in-reply behavior. The main purpose is front-loaded and there is 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?

No output schema exists, yet the description still discloses the salient return value (a link to include in the reply) and the input precondition. For a two-parameter read tool with full annotation coverage, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the two parameters are already documented and the baseline is 3. The description adds a genuine semantic constraint the schema lacks: the message_id must refer to a message whose message_type is 'photo', which is meaningful selection criteria.

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 ("Look at a Telegram photo") plus the concrete goals it enables (describe, OCR, answer questions). It also explicitly distinguishes itself from two siblings, telegram_get_photos and telegram_show_photo, so the agent can route without opening a schema.

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

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

Gives the exact selection condition (a message whose message_type is 'photo'), names the alternative for multiple photos (telegram_get_photos), and names the alternative for mere display (telegram_show_photo). When-to-use and when-not-to-use are both covered explicitly.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive traits, but the description adds real behavioral context the annotations cannot: the shared size budget across photos, client image-block dropping behavior, and that each photo returns a link. It stops short of describing failure modes when a message_id is not a photo.

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

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

Front-loaded with the core purpose and the sibling comparison before any detail; every sentence carries information, though the closing instruction about including links in the reply is slightly incidental.

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 telling the agent what comes back (photos plus a link each) and how to use it, and the two required parameters are covered. 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?

Schema coverage is 100%, so baseline is 3, but the description adds a genuine constraint beyond the schema: the message_ids must correspond to messages whose message_type is 'photo', which the schema's 'photo messages' phrasing only implies.

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 ('Look at several photos from one chat') plus the batching scope ('in a single call'), which cleanly separates it from the singular telegram_get_photo sibling.

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

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

Explicitly says 'Prefer this over calling telegram_get_photo repeatedly' and gives the reason (shared size budget, six cost about one; clients that drop separate image blocks keep these), so both the when and the why are present.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context. It does: it discloses the scope (Business conversations only), the sort order (newest activity first), and the returned fields, which is meaningful added value with no output schema. It stops short of mentioning pagination or how to page beyond the limit.

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

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

Two sentences, zero filler, with the scope and ordering constraint front-loaded before the return-value summary. Every clause 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?

For a simple list tool with annotations carrying the safety profile and no output schema, the description supplies scope, ordering, and return fields, which is close to complete. Only pagination/truncation behavior when limit is capped is left 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% and the single 'limit' parameter already documents its meaning and default of 20 in the schema. 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?

The description states a specific verb and resource ('List ... Telegram Business conversations') and adds scope plus ordering ('newest activity first'), which lets an agent distinguish it from telegram_recent_messages. It does not explicitly name or rule out the sibling telegram_find_chat, so sibling 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?

There is no guidance on when to use this tool versus telegram_find_chat (name-based lookup) or telegram_recent_messages. The agent must infer that this is the enumeration tool from the verb 'List' alone, and no exclusions or prerequisites 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 idempotentHint=true and destructiveHint=false, so the bar is lower. The description nonetheless adds genuinely useful context: the read state change applies retroactively to all earlier messages, it targets the newest message by default, and 'Nothing is sent' disambiguates it from sibling messaging tools. It stops short of noting any rate limits or permission requirements.

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

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

Three short sentences, front-loaded with the effect and followed by the default behavior and the negative guarantee. 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?

For a two-parameter, non-destructive state tool with full schema coverage and no output schema, the description covers effect, scope, and default adequately. Only minor gaps remain (permissions, error behavior on an unknown chat_id).

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates the message_id default ('Defaults to the newest message') but adds no format or edge-case detail beyond the schema, 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 ('clear the unread badge on a conversation by marking ... as read') and precisely defines the scope ('a message, and everything before it'). This distinguishes it cleanly from sibling write tools like telegram_send_message and telegram_edit_message.

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

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

The description implies its use case (clearing unread state) but never states when to prefer it over alternatives or any prerequisites such as needing a resolved chat_id. Usage is inferable but not spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely non-obvious semantic context: what is_forwarded/forward_origin mean, that 'from' identifies the forwarder rather than the author, and an explicit anti-inference warning. It does not discuss pagination or result-size behavior, so not a full 5.

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

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

Front-loads the core scope in the first sentence and the usage cue in the second. The final two sentences on forward semantics are important but slightly repetitive ('is_forwarded and forward_origin' then restating the from/author distinction), so it is efficient but not maximally tight.

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 burden of explaining the return fields it names (is_forwarded, forward_origin, from) and does so well, including an interpretation caveat. What remains uncovered is pagination/ordering guarantees and limits, but the essentials for correct interpretation 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%, with both limit and since fully documented in the schema (including accepted formats for since). The description adds nothing about 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+resource+scope: 'Most recent messages across all Telegram Business chats, newest first.' The 'across all chats' scope distinguishes it from the per-chat telegram_get_messages and the query-driven telegram_search_messages without needing to open a schema.

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

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

Gives a clear usage cue ('Use it for what came in today style questions'), which tells the agent when this tool fits. It stops short of naming alternatives or exclusions, so the agent must infer that per-chat or search tools exist 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 already cover readOnly/idempotent/non-destructive, but the description goes well beyond them: it explains the prefix-match rule on the last word, the semantics of is_forwarded/forward_origin, and the crucial caveat that 'from' on a forward is the forwarder, not the original author. It even warns against inferring hidden authorship from missing origin data — high-value 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?

Front-loaded with the core search behavior, then the forwarding caveat. Every sentence carries information, though the forwarding discussion is dense and could be slightly tightened.

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

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

No output schema exists, and the description compensates by naming the returned fields (is_forwarded, forward_origin, from) and their interpretation. For a read-only search tool with full schema coverage, nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the last-word prefix-matching behavior of the query parameter and the optionality of chat/time restrictions. It does not elaborate on limit or the accepted time formats, which the schema already handles.

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 (full-text search over archived message text and captions) and immediately narrows scope with prefix-matching and optional chat/time-window restriction. This clearly separates it from sibling listing tools like telegram_get_messages and telegram_recent_messages.

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 when this tool applies — free-text lookup with optional chat or time-window narrowing — which tells an agent when search is appropriate versus retrieving recent messages. It stops short of explicitly naming an alternative or stating when-not to use it, so it lands just below the top band.

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 destructive/openWorld/non-idempotent, but the description adds traits those hints cannot convey: the group-vs-private identity switch ('In a group there is no business connection, so it is sent as the bot'), the zero-cost/no-size-limit forwarding behavior, and the live-vs-imported file-id limitation. This is genuinely additive 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?

Front-loads the action and the irreversibility warning, then uses two tight bullets to separate the source paths. Every sentence carries information; the length is justified by the tool's multiple modes and eight parameters.

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, so the description must carry behavioral burden — and it does: confirmation requirement, source-selection rules, group identity caveat, and forwarding limitations. Nothing an agent needs to invoke this 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 is 3; the description rises above it by explaining the mutually exclusive url vs from_chat_id+from_message_id semantics and their cost/limit implications. The remaining parameters (caption, as_document, thread/reply ids) get no extra meaning beyond the schema, so it is not a full 5.

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) plus the full resource set (photo, document, video, audio, voice message) and the target (real person or group from the user's Telegram). This distinguishes it cleanly from telegram_send_message (text) and telegram_get_file/get_photo 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 explicit when-to-use guidance for the two source paths ('Give exactly one source', with the forwarding path vs the url path and their trade-offs), and a clear exclusion ('Works only for messages the collector saw live; imported history has no file id'). It does not, however, route the agent against sibling send tools, so it stops short of full 5-level 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 declare destructive/non-idempotent/openWorld, but the description adds context annotations cannot capture: the action is irreversible and immediately visible to the recipient, only archived chats are eligible, and there is a hard 24-hour business-reply window that cannot be reopened except by the recipient messaging first. These are exactly the behavioral traits an agent needs before calling.

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 and irreversibility, and every sentence contributes something (confirmation, archive constraint, 24-hour window). It is on the denser side, but no sentence is filler, so only minor trimming would be possible.

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

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

For a mutation tool with no output schema, the description covers the full picture: what it does, that it cannot be undone, what preconditions must hold, and the specific failure window. Nothing an agent needs before calling 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% and it documents all three parameters (text, chat_id, reply_to_message_id) with meaning, so the schema carries the load. The description only implicitly points at chat_id via the telegram_find_chat reference and adds no syntax or format detail beyond the schema, 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 ('Send a message to a real person from the user's own Telegram account') and immediately distinguishes itself from the bot-based siblings by scoping to the user's personal account. An agent can differentiate it from telegram_send_media and telegram_bot_direct_messages 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?

Explicit when-prerequisites are given: confirm wording and recipient with the user, and resolve the person with telegram_find_chat first. It also names the failure condition (24-hour window) that governs whether the call can succeed at all. This is about as complete as usage guidance gets.

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 substantial context beyond annotations: the reaction is attributed to the bot, the recipient is notified, omitting emoji removes an existing reaction, the message must already be in the archive, and out-of-scope calls are refused server-side. Annotations (destructiveHint, idempotentHint) are consistent with this, and the description explains the removal/refusal semantics they only hint at.

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

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

Front-loaded with the core action and side-effect warning, then scope caveats. It is dense and each sentence carries operational information, though the emoji list and the two-paragraph exclusion detail make it longer than strictly necessary.

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

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

Complete for a 4-parameter mutation tool with no output schema: it covers side effects, emoji constraints, removal semantics, archive precondition, and scope boundaries. An agent has everything needed to call it correctly or route elsewhere.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds an allowlist of accepted reaction emoji and states that invalid emoji are rejected by Telegram rather than the server, plus the omit-to-remove behavior for `emoji`. It does not explain the `big` animation parameter, which remains schema-only.

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 (put an emoji reaction on a message in a group the bot belongs to) and immediately clarifies the actor is the bot, not the user. It distinguishes itself from telegram_bot_dm_react by naming that sibling explicitly for the DM-inbox case.

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

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

Gives explicit when-to-use context (confirm with the user first because the recipient is notified) and clear when-not cases: 1:1 business chats, and the bot's DM inbox which is routed to telegram_bot_dm_react. The exclusions are named with their alternatives rather than 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real value beyond that: it discloses the key capability limit (the model cannot see the image itself) and the rendering caveat that not every client draws the picture, so the returned link must be surfaced as clickable.

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, zero filler, and the primary purpose plus the critical sibling distinction are front-loaded before the operational 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?

Output schema exists, so return values need no explanation; the description still flags the returned link's use. Purpose, alternative routing, precondition, and rendering caveat together cover everything needed to invoke this 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 baseline is 3. The description goes beyond the schema by constraining which message is valid — the chat_id/message_id must reference a message whose message_type is 'photo' — which the schema does not state.

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 ('Display a Telegram photo to the user as a picture in the conversation') and immediately distinguishes itself from the look-alike sibling telegram_get_photo. An agent can pick this over telegram_get_photo without opening either schema.

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

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

Explicitly names the alternative and the condition that selects it: 'This does not let you see the image — to describe it or read anything in it, use telegram_get_photo.' It also states the precondition that the target message must have message_type 'photo'.

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