Lemma Telepath

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

Goes well past the annotations: it discloses that linked tasks are kept, the daily creation allowance is not restored, an already-sent message is not recalled, in-progress delivery cannot be guaranteed cancelled, and repeated cancellation is safe. Those are exactly the edge cases an agent needs before a destructive call.

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 a distinct fact (source of id, task preservation, allowance, delivery limits, idempotency) with no repetition. Slightly dense but nothing wasted.

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

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

For a one-parameter mutation tool with no output schema, it covers safety, side effects, allowance implications and idempotency. An agent has everything required to call it correctly and to warn the user about limitations.

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 schema already clarifies that the id is the reminder id and not the numeric task id. The description only adds the provenance ('from list_reminders'), so the baseline of 3 is right.

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 ('Cancel a specific reminder') and scopes it to a single reminder identified by id, which cleanly separates it from list_reminders and create_reminder. An agent can select it 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?

Says to use it 'at the user's request, using its id from list_reminders,' which both names the trigger and routes the agent to the sibling that supplies the id. It lacks an explicit when-not-to-use statement, keeping it just below the top score.

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 flag mutation and non-idempotency; the description adds substantial behavior the annotations cannot convey: the shared daily creation allowance, the specific `entitlement_required` failure with no scheduling, the "scheduled is not delivered" distinction, and that existing reminders survive plan termination. These are exactly the side-effect and failure-mode facts 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 recipient scope, then boundaries, then failure behavior. Seven short sentences with no filler, though the allowance, entitlement, and plan-expiry points could be merged into fewer clauses without loss.

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 mutating tool with no output schema, the description covers what an agent needs: authorization precondition, ambiguity handling, dedupe expectations, quota failure signal, and the confirmation contract. Nothing material about invoking 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 description coverage is 100%, so every parameter including the `request_id` retry key is already documented in structured data. The description reinforces the ambiguity-clarification expectation for text/time/timezone but 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 (schedule a reminder message), the actor (Telepath bot) and the recipient scope (authenticated account owner only). It also explicitly distinguishes the tool from a close sibling ("Does not create a Notes task"), so an agent can separate it from kb_create_note 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?

Gives an explicit gating condition ("only when requested or accepted by that user") plus two negative boundaries (no Notes task, no other recipient). It also tells the agent how to proceed under ambiguity ("Clarify the reminder text, time and timezone when ambiguous") and how to report outcomes ("Confirm scheduling only after success").

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 mutation, destructive, non-idempotent and open-world behavior, so the bar is lower, yet the description still adds non-obvious facts: titles are unique so duplicates fail rather than overwrite, reminders dispatch a real Telegram DM to the account owner, and 'entitlement_required' signals the save did not happen. It stops short of stating what a successful save returns or whether storing a reminder is irreversible once scheduled.

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?

Five short sentences, front-loaded with the core action and the duplicate-title exception. A couple of clauses echo the schema's own parameter descriptions, which is mild redundancy but not bloat.

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 six-parameter mutation tool with no output schema, it covers the important traps: uniqueness collision, reminder authorization, shared quota, and a failure sentinel. The main omission is what a successful creation returns (e.g., a note identifier) so the agent can chain into kb_update_note or kb_get_note.

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 alone documents body/[[links]], tags and the type enum, and the description largely restates the markdown-link and tags points. Its marginal additions (shared creation allowance, entitlement_required) are behavioral rather than parameter-level detail.

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?

Opens with a specific verb and resource ('Save a new note to your knowledge base') and immediately differentiates itself from the sibling kb_update_note by the uniqueness rule. An agent can tell exactly which tool handles new-note creation.

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

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

Explicitly states the branch condition ('Titles are unique; if one exists, use kb_update_note instead') and names the sibling to use in that case. It also gates the reminder feature on user authorization, so the agent knows both when to use this tool and when to defer or ask.

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

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

The annotations already declare destructiveHint=true, but the description adds meaningful context: the deletion is permanent and cannot be undone. It also discloses an additional side effect, namely that deleting a task cancels its pending reminder, which is valuable beyond the annotations.

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

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

The description is three short sentences with no wasted text. The irreversible nature and deletion target are front-loaded, and the side effect is appended where it is most useful.

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 destructive tool with full schema coverage and annotations, the description covers the key facts: permanence, lookup by id or exact title, and the reminder side effect. It could be slightly more complete by explicitly stating that exactly one identifier should be provided, but the core context is 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 are already documented by the input schema. The description reinforces that id or exact title is used, but it does not clarify edge cases such as what happens if both or neither are supplied, which matters because neither parameter is required.

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: permanently delete a note from the knowledge base. It also clarifies that the note can be identified by id or exact title, which distinguishes it from read/update siblings.

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 makes the delete operation clear and explains the two lookup modes, but it does not explicitly say when to use this versus kb_update_note or kb_get_note, nor does it discuss exclusions or prerequisites. Usage is implied by the destructive nature rather than explicitly guided.

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?

Goes well beyond the annotations: it discloses that omitted body is destroyed/replaced unless append=true, that reminders are one-shot Telegram DMs requiring user authorization, that new schedules consume the standalone creation allowance and may return entitlement_required, and that completing or retyping a task cancels its pending reminder. This is exactly the destructive and side-effect context destructiveHint=true only hints 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?

Five tightly packed sentences, front-loaded with the core action and addressee before the append, reminder, and task caveats. Dense but every sentence carries operational information; only the "natural 'add this to my notes' path" phrasing is decorative.

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 an 8-parameter, zero-required, nested-reminder mutation with no output schema, the description covers the destructive default, the reminder lifecycle, and entitlement failure mode. Minor gaps remain: no guidance on failure/ambiguity handling (e.g., duplicate titles) or what a successful update returns, though the latter is arguably outside its scope.

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 real meaning: the append/replace dichotomy for body, id-vs-exact-title addressing, and the null-cancels / omitted-preserves distinction plus reminder cancellation on task completion. It stops short of covering tag replacement semantics or required reminder fields, 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 and resource ("Change an existing note") and immediately specifies addressing by id or exact title, which distinguishes it from kb_create_note and kb_get_note. It also names the task/reminder interaction, so the agent can tell this mutation apart from create_reminder and cancel_reminder.

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 explains append=true as the "add this to my notes" path versus default body replacement, and routes standalone reminders to create_reminder. It does not explicitly say when to prefer kb_create_note for new notes or how to disambiguate a title that matches multiple notes, but context is otherwise clear.

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

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

The description adds substantial behavior beyond the annotations: no messages are sent, the tool is unaffected by plan or creation allowance, cancelled/completed reminders are excluded by default, and the delivery statuses carry precise semantics ('scheduled is not delivered', 'delivered means Telegram accepted the message, not that the owner read it', 'uncertain must not be treated as delivered'). That last point is exactly the kind of interpretation rule an agent cannot infer from readOnlyHint/idempotentHint.

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 resource and returned fields, and each sentence carries information (scope, side-effect freedom, availability, default filtering, status semantics). The status-semantics sentence is dense and names values without naming the parameter they belong to, which costs a bit of scanability.

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 compensates by naming the returned fields and the meaning of each delivery status, which is the main thing an agent needs to interpret results. The main gap is that pagination via limit/offset and total-count behavior are not described for what is a list endpoint.

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

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

Schema description coverage is 0%, so the description must compensate: it does explain three enum values (scheduled, delivered, uncertain) and the default exclusion of cancelled and done, which effectively documents the status parameter. It says nothing about limit or offset, leaving pagination semantics entirely to inference from the bare numeric bounds.

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 ('List the account owner's standalone and task reminders') and names the fields returned (text, scheduled time, delivery status), which no sibling tool does. It does not explicitly contrast itself with cancel_reminder or create_reminder, but the read-only listing scope differentiates it well enough in practice.

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 default excludes cancelled and completed reminders' implies that a status filter is needed to see those, and 'available regardless of the plan or creation allowance' tells the agent it won't be blocked. However, there is no explicit routing guidance (e.g. 'use cancel_reminder to cancel', or which status value to pass to include completed items), so usage is only implied.

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

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

Annotations already declare readOnlyHint=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 cover destructive/idempotent/non-read-only, yet the description adds the pending-only restriction and the two failure modes (stale revision, delivery already started) that force a list refresh. It stops short of stating permissions required or the result of a cancel on an already-cancelled id, but it clearly exceeds the annotation baseline.

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, scope stated first, exclusions and the recovery action after; no filler or repetition of the title.

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 mutation with no output schema and three required parameters, the description supplies the essential guardrails (pending-only, staleness handling). Minor gaps remain around what the response looks like and whether authorization or workspace constraints apply.

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% and already documents revision and request_id semantics. The description only indirectly illuminates revision via the 'refresh the list if revision changed' hint and says nothing about the id pattern or request_id retry behavior, so it adds modest value over 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 ('Cancel one pending ... scheduled message') with an explicit scope limit ('one', 'pending'), and the second sentence separates it from deletion tools that act on already-delivered 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 a clear when-not ('Does not delete a message already sent to Telegram') and an implied prerequisite step ('Refresh the list if revision changed'), but never names an alternative sibling such as telegram_reschedule_message for changing delivery time instead of cancelling.

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 well beyond annotations, disclosing quota tiers, the voice_choice_required and voice_limit_exhausted return states, request_id reuse semantics for retries, and the no-resend-on-uncertain-delivery rule. This is exactly the behavioral context an agent needs before a destructive, idempotent open-world send.

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?

Information-dense with little filler, but poorly front-loaded: voice-specific mechanics dominate the opening and the actual general purpose appears only in the second half. The rules around request_id/confirmed are also restated, adding length without new value.

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 an 11-parameter, nested-object, destructive send tool with no output schema, the description covers quota, confirmation flow, retry safety, voice preferences, album constraints, and failure recovery. Nothing material to correct invocation appears to be 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 already 82%, and the description adds real meaning: voice must be an explicitly user-chosen value, save_voice stores only on explicit user request, request_id must be stable and reused on retry, and speech_text is mutually exclusive with media/album. The mutual-exclusivity and preference-persistence rules are not obvious from the schema alone.

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 the tool publishes text, media, or a generated AI voice to a connected channel and broadcasts to an audience rather than a private recipient, which distinguishes it from the DM siblings. However, the description leads with voice-generation details before stating the general purpose, so the core 'what it does' is buried and arrives mid-paragraph.

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 strong operational guidance: show full content, obtain explicit confirmation, call once, no scheduling, use read/search tools to inspect posts, and never auto-resend on uncertain delivery. It differentiates from private recipient tools but never names the close siblings telegram_send_message or telegram_send_media, leaving that routing 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, idempotentHint=true and openWorldHint=true; the description goes further by disclosing the dual deletion (Telegram post plus archived copy), the 48-hour Telegram-side limit, permission requirements, and the observability gap for deletions by other admins. It stops short of describing failure modes or what a partial success looks like, which keeps it from 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?

Five short sentences, each carrying distinct operational information: the action, the confirmation prerequisite, permissions, the time limit, and the sibling it is not. The destructive action and the confirmation requirement are 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?

For a destructive, no-output-schema tool with fully documented parameters, the description covers safety prerequisites, external API limits, side effects on the archive, and known observability limits. An agent has everything needed to decide whether to call it and what to warn the user about.

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 channel_id, message_id, request_id and confirmed are already fully documented in the schema. The description's 'confirm the exact channel and post first' echoes the confirmed/request_id semantics but adds no format or edge-case detail beyond the schema. 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 ('Permanently delete one post from Telegram') plus the secondary effect on the archived copy. It explicitly separates itself from telegram_forget, which only removes archived data, so an agent can distinguish it from the sibling write/edit tools 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 a precondition ('Confirm the exact channel and post first'), required authorization (channel ownership plus bot Delete messages permission), a hard external constraint (48-hour window), and a named alternative for the archived-only case. This is explicit when/when-not guidance with an alternative 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?

Goes well beyond the annotations: states that omitted fields are preserved, that an empty buttons array removes buttons, and that channel ownership plus bot 'Edit messages' permission are required. These are the exact mutation semantics and authorization facts the destructiveHint/idempotentHint flags cannot convey.

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, front-loaded with the action, then safety workflow, then mutation semantics, then scope exclusion. No filler or repetition of the title.

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, nested-schema mutation with no output schema, it covers what changes, what's preserved, permissions, and scope limits. It could note the retry semantics around request_id, though the schema description already handles that.

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 75%, so the schema already documents most parameters; the description still adds real meaning with the preserve-by-default rule for omitted fields and the empty-array removal semantics for buttons. Channel_id, request_id and confirmed are left entirely to their schema descriptions.

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

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

Names a specific verb ('Overwrite') plus the exact editable surfaces (text, caption, media, link buttons) scoped to 'one archived channel post'. The closing clause 'Not for comments or private chats' explicitly separates it from 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?

Gives a clear precondition workflow ('Read it first and confirm the exact replacement and channel') and a negative boundary ('Not for comments or private chats'), which is what routes an agent away from the DM/comment edit sibling. It stops short of naming the alternative tool for those cases.

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

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

Beyond the read-only and idempotent annotations, the description discloses search scope (Session up to 1000 recent dialogs vs. archive-only), case-insensitive matching, that post links resolve to the chat rather than the post, and extensive error/miss handling expectations. It clearly separates errors from zero matches and warns against inferring access denial.

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

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

The definition is front-loaded with a strong two-sentence purpose and usage core, but it then expands into a very long support and setup manual. Much of the later content concerns user-facing remediation rather than helping an agent select or invoke the tool, so many sentences do not earn their place in this definition.

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

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

Given the open-world search behavior, the description is thorough about scope limits, Session versus archive behavior, no-match interpretation, and error handling. However, with no output schema, it does not describe the shape of returned candidates, leaving a gap for an agent that needs to interpret results.

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

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

Schema coverage is 100%, so the schema already documents query, limit, and chat_type. The description adds some nuance about chat_type filtering and search behavior, but it does not meaningfully expand parameter semantics 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?

The first sentence states a specific verb and resource: find a person, group, or channel by partial name, @username, public link, or numeric chat ID. It clearly distinguishes this lookup tool from actions like joining channels or global fuzzy search, and from management via /channels.

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

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

The description explicitly covers when to use Session versus archive-only search, says to clarify ambiguous matches, recommends using a known chat_id directly, and states that it does not join channels or perform global fuzzy search. It also routes owned-channel management to /channels.

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 mark this readOnlyHint=false, idempotent, non-destructive and open-world; the description justifies the non-read-only flag by disclosing that transcribe consumes minutes while reusing a ready transcript is free, and that pending work persists so the agent should check back rather than poll. It also states the 20 MB bot limit and the tab-separated/per-sheet return format. The only gap is it does not describe what a pending or error response actually looks like.

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

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

Front-loads purpose, then prerequisite, then the exclusion, then return-shape detail — a sensible ordering with no filler sentences. It is on the long side (roughly ten sentences) and could compress the media/transcript sentences, but each one carries distinct operational information.

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

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

With no output schema, the description carries the return-value burden and does so: cells, paragraphs and rows for documents, tab-separated rows with '## name' sheet headings, link plus metadata for media, and a paging signal for large spreadsheets. It also closes the loop on the asynchronous transcript case, so nothing an agent needs to call 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, but the description adds real semantics on top: transcribe is scoped to explicit user requests and gated on no transcript existing, and offset_lines is explained as a paging mechanism because a big spreadsheet does not fit in one response. max_chars and include_text are left entirely to their schema text.

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?

Opens with a specific verb and resource ('read a document shared in Telegram') scoped to answering questions about its contents. It explicitly carves out what it is not ('does not search for files by name'), which separates it from telegram_search_messages and the photo siblings.

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 prerequisite chain ('First locate the message with telegram_get_messages or telegram_search_messages to obtain chat_id and message_id'), a targeting rule ('a message whose message_type is not 'text''), and a hard constraint on transcribe ('only on an explicit user request'). It also names the failure case (over 20 MB cannot be fetched) so the agent knows when to stop rather than retry.

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), yet the description still adds substantial behavioral context: reading does not mark messages read or send a reply, archive caps at 200 versus Session at 50, effective_limit must be honored, and archive history is limited to saved/imported messages. It also discloses forward-provenance semantics (from is the forwarder, not the original author) and the archive-vs-Session distinction. It loses a point only because the error/empty-result discussion drifts into recovery policy rather than defining what the tool itself does.

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

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

The core operating instructions are front-loaded, but the description balloons into roughly a thousand words that blend tool behavior with error taxonomy, onboarding scripts, bot commands, and conversational phrasing rules. Several passages duplicate guidance that belongs in sibling tools (find_chat recovery) or in a system prompt, and the volume makes the essential paging logic harder to extract.

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?

Very thorough for operating this tool correctly across sources, and no output schema exists so return-value explanation is warranted. However, the definition spends a large share of its budget on setup/connection recovery paths for other tools, leaving the essential paging and since/before semantics buried rather than absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that since is an inclusive time window while before is for paging back, that one page is not full history, that limit is silently capped per source and effective_limit should be consulted, and that calendar-day requests must be converted to ISO 8601 boundaries with correct UTC offsets rather than literal 'today'/'yesterday'.

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?

Opens with a concrete verb+resource pair ('Read or summarize one Telegram conversation or channel') and states what the return payload contains (message text/captions plus voice/video transcripts, not just links). It is clearly differentiated from siblings such as telegram_search_messages and telegram_recent_messages by asserting one-chat scope and by naming telegram_find_chat as the required resolver.

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 tells the agent to resolve the chat with telegram_find_chat first, when to use since versus before for paging, and when to stop paging ('enough context, the requested start is reached, or paging returns no messages or makes no progress'). It also states the negative case ('Do not automatically scan the entire history') and routes alternative needs to /import or Session, which 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?

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?

Beyond the readOnly/idempotent annotations, the description discloses the bounded-list behavior, per-source limits (archive 200, Session 50), no-pagination semantics, null meaning, archive-only counts, and how to interpret empty results via empty_reason/setup_required/history_notice. It also clarifies that operational errors are not empty results, which prevents a harmful reconnect inference.

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

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

The description is front-loaded with purpose, then return fields, then limits, then interpretation guidance, and most sentences carry distinct operational value. It is dense and long with several run-on clauses, but little is redundant given the number of edge cases it must preempt.

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 list tool with no output schema, the description names the returned fields, the coverage metadata to inspect, limit behavior per source, and empty-result interpretation. An agent has everything needed to call it and interpret the result without guessing about pagination or missing chats.

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 both limit and chat_type are already documented in the schema, including the group-includes-supergroups note and the no-next-page warning. The description reinforces the limit ceilings and filter meaning but adds little syntactic or semantic 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?

The description states a specific verb and resource (browse the user's Telegram chats) and immediately scopes the contents (private chats, groups, channels) with what is returned. It explicitly distinguishes itself from the closest siblings, telegram_find_chat and telegram_recent_messages, and clarifies it is not a user directory.

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 telegram_find_chat for a named person/group/channel and telegram_recent_messages for catch-up across chats, and it names the case this tool is not for. It also warns that repeating the call does not page, so an agent knows not to loop for more results.

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/non-destructive, so the description's value is in the extras it supplies: returned timezone and effective quota, the null-means-unlimited convention, the durable id+revision handle needed for follow-up mutations, and the operational meaning of the "uncertain" state. Remaining gaps are ordering/pagination rather than safety or side effects.

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 generally dense, but the quota sentence ("limit=null and remaining=null mean a personal unlimited scheduling allowance") introduces terms (Transports, Telepath, quota) that are never grounded and collide with the identically named input parameter, costing clarity per word.

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 a fair job sketching the return surface (delivery states, timezone, quota, id/revision) and the exclusion of Telegram-native scheduled messages. It still omits default page size, ordering, and whether cancellation of a delivered message is possible, which matters for a list-then-mutate workflow.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It explains the status values "scheduled" and "uncertain," but leaves the limit parameter (1-100) completely undefined and the "limit=null and remaining=null" sentence is ambiguous — it reads as a quota field in the response, not the integer input parameter, which risks misreading.

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 ("List Telepath scheduled messages and delivery states for this account") and explicitly delimits scope with "This list does not include messages scheduled independently in Telegram," which cleanly separates it from the sibling schedule_message/cancel_scheduled_message operations. An agent can identify the tool without opening the schema.

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

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

Gives concrete usage conditions: "Filter status=scheduled for pending messages," "Pending messages can be changed or cancelled using id and revision," and "Uncertain means inspect the destination before any new send." It does not name the sibling tool to use for editing/cancelling, so the routing is implied rather than 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 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 read-only, idempotent and open-world traits, but the description adds substantive behavior the annotations cannot: sampling limits, the archive-versus-Session caps, no pagination, no advancement on repeated calls, inclusive since semantics, and the meaning of zero results versus setup_required/history_notice. What it lacks is any sense of latency or cost, and the dense caveat stream is hard to parse, but the disclosure is well beyond the annotation baseline.

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

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

The first sentence is well front-loaded, but the remainder is a long run of undifferentiated sentences mixing coverage limits, timezone policy, retry policy and forward-authorship caveats with no grouping or emphasis. Most sentences carry an instruction, so little is pure waste, yet the volume makes key constraints easy to miss.

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 present, the description carries the return-value burden and does so: it names the fields to read (source, coverage, partial, effective_limit, session_limit) and explains is_forwarded/forward_origin semantics. Combined with explicit coverage caveats and failure-versus-empty distinctions, an agent has what it needs to call and interpret 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 parameters are already documented, yet the description adds real meaning: since is inclusive (yesterday includes today), local midnight must be passed with the correct offset, and calendar days must be distinguished from rolling 24h windows. That is semantics an agent would otherwise get wrong, though limit is only echoed rather than enriched.

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 opening sentence names a specific retrieval task (a catch-up across the user's available Telegram chats) and illustrates it with two example questions. It explicitly contrasts the scope with telegram_get_messages, telegram_find_chat and single-conversation lookups, so an agent can separate it from its siblings without reading their schemas.

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

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

It states when to use this tool (broad catch-up, 'what did I miss'), when not to (precise historical intervals, one named conversation) and names the alternative tools to use instead. It also gives a decision rule for the since window and warns against looping retries, which is unusually actionable 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds the substantive part: only pending messages are affected, destination and sender are immutable, omitted fields are preserved, and timezone falls back to the message's saved value. It does not say what happens when the frozen destination/sender is passed or what a stale revision produces, which is the main residual gap for a destructive mutation.

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?

Five short sentences, front-loaded with the mutation scope, then prerequisites, then immutability, then partial-update semantics. Nothing is filler; the only mild duplication is the approval sentence overlapping the confirmed parameter description.

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

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

For a 7-parameter destructive mutation with annotations but no output schema, the description covers the non-obvious behavior an agent needs: partial update, timezone inheritance, revision freshness, and fixed destination/sender. Conflict/error handling for a stale revision is the one omission that would matter in practice.

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 86%, so the baseline is 3 and the schema already explains at, text, timezone, revision, confirmed and request_id well. The description adds genuine PATCH semantics ("Omitted text or time stays unchanged") and the timezone inheritance default, but nothing beyond the schema for revision conflict behavior or the id format.

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?

"Change time and/or exact text of a pending scheduled message" gives a specific verb plus resource and bounds the editable surface, which separates it in practice from telegram_edit_message (already-sent messages) and telegram_schedule_message (creates). It does not name a sibling explicitly, so an agent must infer the boundary from the word "pending".

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

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

It states prerequisites ("Read the current revision first") and approval requirements ("Obtain approval for the revised text and local date/time"), which tells the agent how to sequence the call rather than just what it does. It stops short of naming explicit alternatives such as cancel_scheduled_message for removal or list_scheduled_messages as the source of the revision.

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 well beyond the annotations (readOnly=false, idempotent=true, openWorld=true) by disclosing pending-message quotas per plan tier and that they are shared across transports, that delivery/cancellation frees a slot, that expiry preserves existing schedules, that delivery is normally within 15 seconds and fails past 15 minutes late, and that uncertain deliveries are not auto-retried. That is exactly the operational context an agent needs before committing a scheduled write.

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 the destination/transport/timezone ordering, and nearly every sentence carries a distinct constraint (quota, timing, failure, no-retry). It is dense to the point of being a single unbroken block; slight trimming of the quota enumeration would improve scanability 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 7-parameter, 6-required mutation tool with no output schema, the description covers transport selection, confirmation requirements, timezone reuse, quota accounting, delivery timing, and failure semantics. Nothing an agent needs to call it correctly or interpret a refusal appears to be 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 71%, and the description compensates for the two undocumented fields: transport is explained by precondition (bot_api needs a connected group or owned channel plus posting permission; session uses the account's actual permissions), and timezone handling is spelled out. chat_id still gets only an indirect 'resolve the destination first' rather than a pointer to telegram_find_chat/channels, so it falls just short of full coverage.

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 with scope: 'Schedule one plain text message to a group or channel.' It also explicitly separates itself from the reminder siblings with 'These are scheduled sends, not personal reminders or recurring tasks,' so an agent can distinguish it from create_reminder and telegram_send_message 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 ordered preconditions (resolve destination, explicitly pick bot_api vs session, ask for timezone if unestablished) and names the setup routes (/channels, /session in @lemma_telepath_bot). It also states the exclusion case, so when-to-use and when-not-to-use are both covered.

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

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses backend-dependent coverage differences (Archive vs Connected Session), that attachment bytes and filenames are not searched, cursor expiry after 15 minutes and on restart, that results reflect live changing data, and the response fields to inspect (effective_limit, source, coverage, partial, has_more, empty_reason). It also explains the forwarding semantics of from vs forward_origin, which is non-obvious behavior an agent would otherwise misread.

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

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

The critical information (what it searches, archive vs Session, pagination) is front-loaded, but the description runs to roughly 450 words of dense prose mixing selection guidance, error policy, reconnect instructions and authorship caveats. Much of the recovery/support/escalation material would fit better in error payloads, and the lack of any structure makes it hard to scan.

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 naming the response fields that govern correct follow-up (coverage, partial, has_more, next_cursor, empty_reason, chat_found, history_notice, setup_required) and by explaining what each continuation signal means. For a six-parameter search tool with two backends and cursor pagination, nothing an agent needs to call it correctly appears to be 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 real semantics: all terms are required with prefix matching on the last word, since is inclusive and before exclusive, calendar days should be passed as inclusive-midnight/exclusive-next-midnight ISO intervals, and cursors must never be constructed or edited. That meaningfully extends what the schema itself conveys.

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 opening sentence names a specific verb and resource ('Find a topic, decision, link or mention in available Telegram messages') and immediately scopes what is searched: text, captions and saved transcripts. It also differentiates itself from the nearest sibling by naming telegram_get_messages for conversation summaries and telegram_find_chat for chat resolution.

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 routing rules are given: use telegram_get_messages for a conversation summary, resolve a chat with telegram_find_chat and pass chat_id, and use a few distinctive words rather than a natural-language question. It also states when to stop paging (enough context, has_more=false, cursor failure) and what to do for empty results or missing archive history.

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?

Well beyond the annotations, it discloses that sending is instantly visible and irreversible, that missing voice choice returns voice_choice_required without using quota or generating, that voice_limit_exhausted returns a reset date, that free tier is 3 lifetime voices, and that uncertain delivery requires inspecting the chat first. It also specifies asymmetric identity behavior (private business chats as user, groups as bot) and the request_id retry contract.

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

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

Purpose and the critical constraints are front-loaded, and the bulleted source list is scannable. It is dense but most sentences carry non-redundant operational rules (quota tiers, voice_choice_required loop); a few quota details and the 'Markdown is converted' style asides could be trimmed without loss.

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 13-parameter mutation tool with no output schema, it covers the hard parts: mode exclusivity, confirmation gating, idempotency via request_id, error states and their required follow-ups. What it lacks is any statement of what a successful call returns (message id, remaining allowance shape) despite telling the agent to report remaining allowance, leaving the success path inferred.

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 policy meaning the schema does not: the exclusivity between speech_text, from_chat_id + from_message_id and url, the 800-character cap, the voice-selection rule (only user-specified, never guess), and that save_voice can be changed later. Remaining parameters (caption, message_thread_id, reply_to_message_id, as_document) are not elaborated in prose, which keeps it from 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?

The opening sentence names a specific verb and resource ('Generate an AI voice message ... and send it to Telegram in one call') and the second block enumerates the three mutually exclusive send modes. An agent can immediately tell this apart from telegram_send_message, telegram_create_post and the read-only telegram_get_file siblings.

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 explicitly states when this tool is wrong ('Use telegram_create_post for connected channels'), how to pick a chat ('Send to a resolved private chat or group'), and the rule for choosing a source ('Choose exactly one source'). It also gives a conditional path ('If no preference exists ... ask the user to choose a voice') that tells the agent exactly what to do next.

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?

Far beyond the annotations it adds the real operational semantics: sender identity varies by destination (account for Business replies, bot for groups, channel for inbox), a stable request_id turns a retry into a receipt check rather than a resend, status=sent means Telegram acceptance only, and archived=false means delivered-but-unsaved so it must not be resent. It also documents error_code/next_step/retry_after_seconds and the BUSINESS_PEER_INVALID ambiguity, none of which the annotations convey.

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

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

The content is nearly all substantive, but it arrives as an undifferentiated wall of sentences mixing transport selection, error handling, retry policy and threading rules, with no grouping or front-loaded purpose statement. A few points (transport stability, request_id reuse) are restated from the schema and could be consolidated for easier scanability.

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, non-idempotent outbound-send tool with no output schema, the description covers a remarkable amount: idempotency/receipt semantics, delivery-vs-read distinction, archived persistence failure, the Business 24-hour window and its false-negative traps, and channel-inbox threading. The one notable omission is what a successful response payload looks like beyond status and archived flags.

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

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

Schema coverage is 100%, so the schema already defines all seven parameters; the description nevertheless adds routing meaning the schema cannot express – transport selects the sender identity and window constraints, reply_to_message_id must reference the customer's archived message for channel inboxes (and must not be replaced by message_thread_id), and message_thread_id is only for known forum topics/group quotes in that destination.

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 verb and resource are identifiable ('Send confirmed text' to a Telegram chat), and the negative routing to telegram_create_post makes clear this is for messages/replies rather than channel posts. However, the core purpose never appears as a clean, front-loaded statement – it is embedded among scoping rules about channel comments and transports, so the agent must assemble it from fragments.

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-to-use and when-not-to-use: 'Never use this tool to publish channel posts; use telegram_create_post', resolve unknown chats with telegram_find_chat, and choose transport=bot_api vs session deliberately with the tradeoff stated. It also names the preconditions (known archive chat, private Business reply access, 24-hour incoming window) that determine whether this tool can be used at all.

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 safety (readOnly=false, idempotent=true, destructive=false), and the description adds real value beyond them: the ownership precondition, the bot 'Edit messages' permission requirement, and the guarantee that other posts' pin state is untouched. It doesn't say what the response looks like or what happens if the post is already in the requested state, keeping it below 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?

Three short sentences, front-loaded with the action and immediately followed by the safety confirmation, scope limit, and permission requirement. No filler and nothing redundant.

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

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

With five required params, high schema coverage, and no output schema, the description covers preconditions and scope adequately. Minor gap: it doesn't clarify whether the confirmation requirement is enforced by the server or is a caller discipline, or what failure modes (no permission, message not found) look like.

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 80%, so channel_id, message_id, request_id, and confirmed are already well documented in the schema. The description's 'channel, post and desired pinned state' maps loosely onto channel_id/message_id/pinned but adds no format or validation detail 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?

Names a specific verb pair (pin/unpin), the exact resource (one specific channel post), and explicitly bounds scope with 'Never unpins all posts'. This clearly separates it from siblings such as telegram_delete_post, telegram_edit_post, and telegram_create_post.

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 the channel, post and desired pinned state first' gives a pre-call checklist, which implies the usage context but doesn't state when to choose this over an alternative or when not to call it. No sibling or alternative is named for 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?

Beyond annotations, it discloses that the reaction is the bot's, that the recipient sees it and is notified, that only Telegram standard reaction emoji are accepted and the server merely relays Telegram's refusal, that the message must already be in the archive, and that business 1:1 chats are refused locally rather than failing obscurely. These are meaningful behavioral details for a destructive, open-world mutation.

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

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

The content is dense and mostly earns its place, especially the emoji list and the exclusions. However, the description opens with an 'Also supports...' caveat before stating the main purpose, and the long final sentence about out-of-scope chats could be 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?

For a four-parameter tool with an output schema absent but full schema coverage and annotations present, the description covers scope, emoji constraints, removal behavior, user confirmation, archive requirements, and the two excluded chat types. 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 baseline would be 3, but the description adds real semantic value: the allowed emoji set is constrained in prose despite no enum in the schema, and omitting emoji is explained as removal. It also clarifies the chat and archive constraints on chat_id, though it does not explain the 'big' parameter.

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

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

The description states a specific verb and resource ('Put an emoji reaction on a message in a group the bot belongs to') and extends it to connected channels. It also explicitly distinguishes this tool from telegram_bot_dm_react and from business 1:1 chats, so an agent can select it without inspecting sibling schemas.

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

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

It gives explicit when-to-use conditions (group the bot belongs to, connected channel posts after ownership verification) and explicit when-not-to-use cases (1:1 business chats, bot DM inbox, which routes to telegram_bot_dm_react). It also tells the agent to confirm the message and emoji with the user first, and explains that omitting emoji removes an existing reaction.

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.