telegram-mcp

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

Annotations already declare this as a non-read-only, open-world operation, and the description only restates the save-contact behavior. It does not disclose permission requirements, duplicate-contact behavior, whether phone is needed, or what happens on success.

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 efficient sentence with the core action and identifier forms front-loaded. There is no redundant or filler text.

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 four parameters and no output schema, the description is too sparse. It leaves required parameter semantics, side effects, and failure/duplicate behavior undocumented.

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% for four parameters. The description usefully clarifies that 'user' accepts an @username or user id, but it does not explain the required 'firstName' or the optional 'phone' and 'lastName' parameters.

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 ('Save ... as a contact') and clarifies that the user can be identified by @username or user id. It is clear against most siblings, but it does not explicitly distinguish itself from nearby contact/user tools such as get_contacts, delete_contacts, or search_users.

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 explains the acceptable user identifier formats but gives no guidance on when to use this tool versus alternatives like search_users, get_contacts, or send_contact. No prerequisites, duplicate-handling conditions, or exclusions are stated.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=false, so the mutation and local-scope nature are partly covered structurally. The description usefully reinforces 'Local to the account' (no effect on other participants) and implies reversibility via 'or back to the main list,' but it omits idempotency, behavior when the chat is already archived, and error/permission cases.

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, front-loaded sentences with no filler; the purpose leads and the scoping caveat follows. The folder-id sentence is compact but introduces a confusing concept that does not correspond to any actual parameter.

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 mutation with no output schema, the description covers purpose and the archived/not-archived intent, but leaves the required `chat` identifier format and failure/idempotency behavior undocumented. Adequate but with a clear gap around the mandatory parameter.

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 0% for both parameters. The description spends its only parameter-like detail on a 'folder id' (0 vs 1) that does not exist in the schema, only loosely mapping onto the `archived` boolean, and says nothing about the required `chat` parameter (id vs username vs title). This leaves the required parameter completely unspecified.

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 ('Move a chat into the Archived folder or back to the main list'), which is unambiguous and clearly distinct from siblings like telegram_mute_chat, telegram_pin_chat, or telegram_delete_chat. It stops short of explicitly naming alternatives, but the resource itself is unique enough that an agent can route correctly.

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 when to use it (archiving/unarchiving) and adds the scoping note 'Local to the account,' but offers no explicit when-not conditions, prerequisites, or comparison to alternatives such as telegram_folders. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so safety is covered; the description adds genuinely useful behavior: append-on-every-call, timestamp/args/outcome fields, and secret redaction at write time. It omits pagination and limit behavior, keeping it short of a 5.

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

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

Three dense sentences, front-loaded with the core action and scope, followed by the record contents and filters. No filler, no 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?

With no output schema, the description usefully describes what each log entry contains and how filtering works. The only missing piece an agent needs to call it correctly is the limit/pagination semantics, which is minor for an optional read tool.

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

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

Schema description coverage is 0%, so the description must compensate. It documents two of three parameters well (tool name filter, outcome enum values), but never mentions 'limit' or its default of 50 and max of 500, leaving a real gap.

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

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

States a specific verb and resource ('Read this server's own call log') with scope and ordering ('newest first'), and explicitly contrasts with the Telegram-facing siblings ('nothing is read from Telegram'). An agent can distinguish it from telegram_audit_summary and the rest of the catalog without inspecting 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?

Gives clear context for when this applies (inspecting this server's own call history) and lists the optional narrowing filters with the accepted outcome values. It does not explicitly name the sibling alternative (telegram_audit_summary) or state when-not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the source is the local audit log and the return shape is counts by tool and outcome plus first/last call, which helps an agent reason about what it will get back. It stops short of stating any retention/coverage window for the log.

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

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

Two sentences, zero filler. The output content is front-loaded in the first sentence and the use case follows immediately, so an agent can decide relevance after one line.

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 no parameters, the description carries the burden of describing the return value, and it does so reasonably well (counts per tool, per outcome, first/last call). The one gap is that it never says how much history the local audit log covers, which an agent gauging the summary's significance would want to know.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. The description correctly implies the summary is unscoped, and nothing in the text misrepresents the empty schema.

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

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

The description names a specific verb and resource ('Counts per tool and per outcome from the local audit log') and goes further to specify the exact aggregation output, including the first and last recorded call. This is far more precise than the title and lets an agent know it is a roll-up view rather than a raw listing.

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

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

'Use it to see what an agent has actually done to the account, without paging through entries' states a clear use case and implicitly contrasts with entry-by-entry browsing. It does not name the sibling telegram_audit_log as the alternative for detail, so the when-not condition 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 declare readOnlyHint=false and openWorldHint=true, so the mutation and external-visibility profile is already covered. The description adds real behavioral value beyond that: the concrete effect ('cannot message you or see your profile') and the fact that the action is reversible.

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, then effect, then reversal. Every sentence earns its place with no redundancy.

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

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

For a two-parameter tool with no output schema and adequate annotations, the description covers the action, effect, and reversibility. The only meaningful gap is the accepted format for identifying the user.

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 parameter meaning. It explains the 'unblock' flag clearly (true reverses the block), which the bare boolean schema does not, but it never clarifies the 'user' parameter format (username vs. ID) despite that being the required argument.

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

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

States a specific verb+resource ('Block or unblock a user') and clarifies the toggle direction. It is inherently distinguishable from siblings like telegram_kick_member or telegram_delete_contacts, though it does not explicitly name any alternative to contrast against.

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

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

Usage is implied by the reversal instruction ('Pass unblock=true to reverse it'), which gives operational context. However, there is no explicit guidance on when to block versus kicking a member or deleting a contact, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds useful behavioral context beyond that: what each entry contains (rights and custom rank) and the fact that it uses a dedicated server-side filter rather than enumerating members.

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

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

Two tight sentences with the purpose front-loaded and the efficiency note second; nothing is wasted or 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?

For a read-only list tool with annotations covering safety and no output schema, describing the return contents is a plus. However, the total absence of parameter documentation leaves the caller guessing how to address the chat, which is a real gap for a tool whose only required argument is that identifier.

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% with two parameters, so the description must carry the burden and does not. It never explains the required 'chat' identifier format (username vs numeric ID) nor the 'limit' parameter's default of 50 and max of 200.

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

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

States a specific verb (List) and resource (admins of a group or channel), plus the returned detail (rights held, custom rank). The 'dedicated admin filter, so it does not page through every member' clause implicitly distinguishes it from the sibling telegram_chat_members, which returns all members.

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 efficiency clause ('does not page through every member') hints that this is the preferred path over listing all members, but no sibling is named and there are no explicit when-to-use or when-not-to-use conditions.

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 and openWorldHint=true, so the safety profile is covered. The description adds value by listing the returned fields, but says nothing about auth requirements, failure behavior for invalid identifiers, or whether member count is expensive to compute.

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

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

A single front-loaded sentence with no wasted words; the verb and resource lead and the field list follows. Efficient, though it omits the input detail that would make the sentence earn more of its place.

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

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

With no output schema, the description usefully enumerates return fields, which is appropriate. However, it leaves the required input format unexplained and gives no routing context among many chat-related siblings, so it is only minimally complete for this tool.

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

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

Schema description coverage is 0% for the single required 'chat' parameter, so the description carries the full burden — yet it never explains what 'chat' accepts (numeric id, @username, phone, invite link). It merely restates the resource, adding no input-format meaning beyond the bare 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 (Fetch) and resource (info for a chat/user/channel) and enumerates the returned fields, so the agent knows exactly what it gets back. It is clear, though it doesn't explicitly differentiate itself from siblings like telegram_full_user or telegram_chat_members.

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

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

There is no when-to-use guidance and no alternatives named. With close siblings such as telegram_full_user, telegram_chat_members, and telegram_list_chats in the namespace, the agent gets no help deciding when this tool is the right choice.

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 and openWorldHint=true, so the safe-read profile is covered. The description adds the meaningful 'if permitted' caveat (a permission requirement beyond the annotations) and the return fields, but says nothing about pagination or how limit affects results.

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

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

Two tight sentences with the core action front-loaded and the return shape immediately following. No filler, though the parenthetical caveat is slightly buried rather than integrated into the sentence flow.

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 read-only listing tool with no output schema, describing the returned fields (id, name, username, role) is the right instinct. However the permission precondition stays hand-wavy and the limit/pagination behavior is entirely absent, leaving gaps for an agent invoking a paged 500-item list.

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% and neither parameter is documented by the schema, so the description must compensate. It does not: 'chat' is only implied by the group/channel phrasing, and 'limit' (default 100, max 500) is never explained or bounded.

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 participants of a group/channel') and adds the returned fields, so the agent knows exactly what it retrieves. It does not name the closest sibling telegram_chat_admins, so the boundary between 'all members' and 'admins only' is left implicit.

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

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

The only usage signal is the parenthetical '(if permitted)', which hints at a permission precondition but is vague about when listing works. There is no guidance on when to choose this over telegram_chat_admins or telegram_common_chats, and no exclusions given.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true. The description adds valuable context beyond annotations: default revoke=false deletes only your own copy, revoke=true removes messages for everyone and requires rights to do so, and it returns a message count from Telegram. This covers permission needs, deletion scope, and return 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?

The description is three concise sentences, front-loaded with purpose then behavior. Every sentence adds information, though the final sentence about the return value is slightly awkwardly phrased. No unnecessary 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 3-parameter mutation tool with no output schema, the description covers deletion scope, permission requirements, and return value. However, it omits explanation of the maxId parameter and does not clarify how this differs from telegram_delete_messages, leaving gaps for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate. It explains the revoke parameter well (default false, true removes for everyone, needs rights), but leaves the maxId parameter completely undocumented and only implicitly covers 'chat'. Partial compensation warrants a low score.

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 clear verb and resource: 'Delete messages from a chat.' However, it does not differentiate this tool from sibling telegram_delete_messages, which appears to delete individual messages rather than clear an entire chat history. The tool name suggests scope, but the description alone is slightly ambiguous.

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

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

The description explains the revoke parameter's effect but gives no guidance on when to use this tool versus alternatives like telegram_delete_messages or telegram_delete_chat. No when-to-use or when-not-to-use conditions are provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the mutual-membership scope but says nothing about pagination, ordering, or whether the target user must be a known contact, so it sits at the annotated 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?

A single front-loaded sentence that states the resource, scope, and relationship in one clause. No filler or redundancy.

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

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

For a simple read-only list tool with no output schema and annotations covering safety, the description is adequate on purpose but leaves the parameter formats undocumented. An agent can identify the tool but may guess wrong on the 'user' identifier format.

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% for two parameters, so the description must compensate and does not. It does not clarify whether 'user' takes a username, ID, or phone number, nor does it explain the 'limit' cap or default 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?

Specific verb ('list') plus a precisely scoped resource ('groups and channels this account has in common with another user'). This is clearly distinguishable from telegram_list_chats by the 'in common with another user' qualifier, though the description never names that sibling explicitly.

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

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

No when-to-use or when-not-to-use guidance. The phrase 'in common with another user' implies the use case but the description offers no prerequisites, no alternatives, and no conditions for choosing this over telegram_list_chats or telegram_full_user.

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=false and openWorldHint=true, so the description is not obligated to restate that this is a write. It adds only that the result is a 'broadcast channel' and says nothing about ownership, who can post, visibility, or what happens on failure — context the annotations do not provide.

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

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

A single front-loaded sentence with no filler. Nothing is wasted, but there is also little structure beyond that one clause.

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 mutation tool with no output schema, the description covers the inputs but omits what the caller gets back (e.g., a channel ID) and any authorization or rate-limit context. It is minimally adequate rather than complete.

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

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

Schema coverage is 0%, so the description must compensate. It does map both parameters ('title' and optional 'description', i.e. about), which is better than nothing, but it gives no length limits, format hints, or the naming mismatch between 'about' and 'description'.

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 ('Create a broadcast channel') and qualifies the channel type as broadcast, which separates it from telegram_create_group. It does not, however, explicitly name the sibling it differs from, so it falls short of a 5.

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

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

There is no guidance on when to use this versus telegram_create_group or the other chat-management tools, and no prerequisites (e.g., permission or account requirements) are mentioned. Usage is only implied by the verb 'Create'.

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=false and openWorldHint=true, so the write/network profile is covered. The description adds nothing beyond that: it does not say whether the creating account becomes admin, what permissions are required, or what happens if a user in the list is invalid.

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

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

A single front-loaded sentence with no filler; the verb, resource, and inputs all appear immediately.

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?

Adequate for a two-parameter mutation with no output schema, but thin for a write operation that creates persistent server-side state. Missing failure modes, permission requirements, and the effect on the caller's admin role.

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 both parameters — and it does, clarifying that 'users' accepts @username or numeric id and that a title is required. It does not state limits on user count or whether users must be contacts, but it closes the main gap.

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 (create) and resource (group chat), and mentions the two inputs. It implicitly distinguishes itself from telegram_create_channel by saying 'group chat', but never names the channel sibling to make the boundary explicit.

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

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

No guidance on when to create a group versus creating a channel (telegram_create_channel) or joining one (telegram_join_chat), and no prerequisites or preconditions are stated. The agent must infer usage from the name alone.

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

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

Annotations already flag destructiveHint=true, but the description goes further by disclosing that deletion is permanent, that chat history is destroyed, that the chat ceases to exist for all members (not just this account), and that the operation is restricted to the creator. That permission constraint and irreversibility disclosure exceed what annotations provide.

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

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

Three tight sentences: the destructive action first, then the sibling comparison, then the permission constraint. Every clause adds distinct decision-relevant information with 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 one-parameter destructive tool, the description covers irreversibility, scope of effect, and authorization. The only real gap is the missing format guidance for the 'chat' argument, which the bare schema does not fill in.

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?

Single parameter 'chat' with 0% schema description coverage, so the schema contributes nothing about accepted formats (username, numeric id, or invite link). The description never clarifies what the identifier should look like, leaving the one required parameter underspecified despite its simplicity.

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

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

States a specific verb (delete), resource (group or channel), and scope (permanent, including history, for the account owner). It explicitly distinguishes itself from telegram_leave_chat and frames itself as the counterpart of telegram_create_group/telegram_create_channel, so an agent can pick it without opening other 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?

Gives explicit when/when-not routing: it names telegram_leave_chat as the weaker alternative for leaving only, and states the prerequisite that only the creator can delete ('Telegram refuses otherwise'). No inference required to choose between delete, leave, or create.

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 mark this as not read-only and open-world, so the mutation type is known. The description adds useful behavioral context by explaining that the account 'stays subscribed to nothing new' and 'only forgets the saved contact entry,' which clarifies the scope of deletion beyond simple mutation hints.

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

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

The description is three short sentences with the core action front-loaded. The final sentence explains scope without unnecessary repetition or 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 one-parameter mutation tool with no output schema, the definition covers the important semantic boundaries: what is removed, what is not changed, and that multiple identifiers are allowed. It could be slightly stronger if it explicitly stated irreversibility or expected confirmation behavior, 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 coverage is 100%, so the single parameter is already documented. The description still adds meaning by listing accepted identifier formats ('@username, user id, or numeric id') and confirming that several contacts may be passed at once, which goes slightly beyond the schema's brief parameter note.

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 ('Remove saved contacts') and explicitly distinguishes the tool from its inverse, telegram_add_contact. It also clarifies that multiple contacts may be removed in one call, so an agent can identify the operation 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?

It gives clear context by naming the inverse operation and noting batch removal, which helps route between adding and deleting contacts. However, it does not explicitly address when to use this instead of related actions like telegram_block_user, nor does it state when this tool should not be used.

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 important behavioral context beyond annotations: the action is local-only and does not affect Telegram, and it may optionally delete the referenced file. It does not explicitly state whether file deletion is irreversible, which is a relevant side-effect detail for a destructive local operation.

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 compact sentences with no filler. The core action, local-only scope, and primary use case are front-loaded and easy 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?

For a simple two-parameter local bookkeeping tool with no output schema, the description covers what the tool does, what it does not do, and the main scenario for using it. Nothing essential is missing for correct tool selection.

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 description explains the semantic role of both parameters: id identifies the record, and the second option controls deletion of the referenced file. However, it does not highlight the schema default of deleteFile=true, which is important because omitting the parameter still deletes the file.

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: removing one record from the local downloads index by id, optionally deleting the referenced file. It clearly distinguishes this from Telegram-side deletion and references the related sibling telegram_list_downloads.

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

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

It gives an explicit usage condition: prune records whose file is already gone, identified via telegram_list_downloads reporting exists:false. It also clarifies when-not use by stating this is local bookkeeping only and nothing is deleted on Telegram.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the write/destructive nature is covered structurally. The description adds real context beyond that: revoke=true scopes the deletion to everyone and is limited to '(your messages)'. It still leaves revoke=false behavior (delete-for-me-only) and irreversibility unstated.

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

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

Two tight sentences with no filler, and the core action plus the revoke switch are front-loaded. It is efficient, though the extreme terseness is part of why several parameter and behavioral gaps persist.

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, open-world tool with three parameters at 0% schema coverage and no output schema, the description is only partly sufficient. It never states that deletion is irreversible, what revoke=false does, or what identifier formats 'chat' accepts; annotations cover the safety hint but not these operational details.

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 load. It clarifies messageIds as message ids and gives semantics for revoke, but the 'chat' string parameter's accepted format (@username, numeric id, phone) is undocumented in both schema and description, and the default revoke=true is only implied.

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+resource ('Delete one or more messages in a chat by id'), which an agent can distinguish from siblings like telegram_clear_history, telegram_delete_chat, and telegram_delete_contacts. It does not, however, explicitly state how it differs from clear_history (bulk chat wipe) or delete_chat (whole-conversation removal).

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

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

Usage is implied: target individual message ids rather than an entire chat. It gives no explicit when-to-use / when-not-to-use guidance versus the closely related telegram_clear_history or telegram_delete_chat, and states no prerequisites (e.g., needing to own the message or be an admin).

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 contains rich behavioral details, but it explicitly calls this a 'read-only health check' while also stating that session file permissions are 'auto-repaired to 0600'. That auto-repair is a write/side effect and contradicts the readOnlyHint=true annotation.

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

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

The description is compact and front-loaded: it starts with the read-only health-check purpose, then lists checks, return shape, failure semantics, and secrecy guarantees. Every sentence supplies useful information for calling or interpreting the tool.

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

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

With no output schema, the description fully carries the return contract: { healthy, checks[], account }. It also explains how missing/unauthorized sessions are surfaced, how updates are treated, and that sensitive values are never returned.

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

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

The tool takes zero parameters, so there is no parameter semantics burden. The schema is empty and fully consistent with the description, which appropriately says nothing about inputs.

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

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

The description names a specific verb+resource (read-only health check) and enumerates exactly what is checked: config, installed version, state dir, session presence, session file permissions, and live authorization. It also states the return shape, so an agent can distinguish this diagnostic tool from message/chat operations and login tools.

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 clear remediation guidance: a missing or unauthorized session is a failed check and telegram_login_start should be called to fix it. It also clarifies that an available update is informational and never fails the check. It does not explicitly say when to use this versus telegram_status, but the diagnostic purpose is 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?

Adds real context beyond the annotations: it discloses the destination directory, the return shape (local path + size), and the TELEGRAM_MAX_DOWNLOAD_BYTES env cap including the 0 = unlimited edge case. However it doesn't cover overwrite behavior for existing files, what happens when the cap is exceeded, or auth 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 core action, then the return value, then the env cap detail. No waste.

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 stating the return values. Still incomplete for a write-to-disk tool: file naming/overwrite rules, error cases, and parameter meanings are 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 0%, so all three parameters (chat, messageId, optional fileName) rely on the description, which says nothing about them. Only a weak implication that fileName relates to the attachment's saved name.

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: downloading a message attachment to the local media directory. It is clearly distinguishable from siblings like telegram_list_downloads and telegram_delete_download, though it never names them.

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

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

No guidance on when to use this versus list_downloads/delete_download, nor on prerequisites such as the message actually having an attachment. Usage must be inferred entirely from the name.

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 declare readOnlyHint=false and openWorldHint=true; the description adds real behavioral context beyond that: admin permission requirement with the failure mode (Telegram refuses), and idempotent-ish partial update semantics where omitted fields are untouched. It does not describe the response payload, but that is minor for this tool.

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, front-loaded with what it changes, then permissions, then update semantics, then limits. Every sentence carries actionable information with 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?

Covers purpose, permissions, partial-update semantics, and field constraints, which is sufficient for a 3-parameter mutation with no output schema. Only the 'chat' identifier format (username vs numeric id) is unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: title bounded at 1-128 chars and about bounded at up to 255, matching the schema's minLength/maxLength. The 'chat' identifier parameter is left implicit, which is the only real gap.

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 a group/channel title and/or description.' This is clearly distinguishable from sibling mutations like telegram_set_chat_photo, telegram_edit_message, or telegram_update_profile, which target different resources.

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 ('Needs admin rights; Telegram refuses otherwise') and states partial-update behavior ('Omit a field to leave it untouched'). It does not name an explicit alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the mutation nature is already known. The description adds the genuinely useful constraint that only your own messages can be edited, but says nothing about edit windows, error behavior, or whether non-text content can be edited.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity is partly under-specification rather than disciplined economy.

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, thin annotations, and zero schema-level parameter documentation, the description leaves too much open: no success/error semantics, no edit-eligibility rules, and no parameter format hints. An agent would need outside knowledge to call it reliably.

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% for all three required parameters, so the description must compensate. "By message id" clarifies messageId and "in a chat" scopes chat, but the accepted chat identifier formats (id vs @username) and the 4096-character text limit documented in the schema are not surfaced here.

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 ("Edit ... messages") plus a scoping constraint ("one of your own") that separates it from send_message and delete_messages. It does not name siblings explicitly, but the operation is unmistakable.

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?

No when-to-use guidance, no condition distinguishing editing from re-sending or deleting a message, and no mention of alternatives such as telegram_delete_messages or telegram_send_message. The only implied rule is message ownership.

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 only readOnlyHint=false and openWorldHint=true; the description supplies the extra behavior an agent needs: output lands in the export directory, the path is returned, results are newest-first, and there is a hard 1000-message ceiling. It does not say whether the file is overwritten on repeat calls or whether the export directory is configurable.

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 destination, with no filler. The brevity is close to terse given three undocumented parameters, but every sentence earns its place.

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

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

No output schema exists, and the description correctly compensates by stating the return value (the file path). However, for a filesystem-writing tool it never explains the export directory location, overwrite behavior, or how the format enum affects the produced file, leaving gaps an agent would have to discover by trial.

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 carries the full burden. It covers the limit cap ("max 1000") but omits the default of 200, says nothing about how to address the required chat parameter, and describes the output as "a JSON file" while the schema's format enum also permits jsonl and txt — effectively under-describing or mis-signalling that 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?

States a specific verb and resource: dump a chat's history to a JSON file and return the path. The file-export framing implicitly separates it from telegram_get_history and telegram_search_messages, though it never names those siblings explicitly, so the differentiation is left 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?

"Useful for archiving or handing a full conversation to another tool" gives a use context, but there is no when-not guidance and no named alternative (e.g., use telegram_get_history for inline reading, or telegram_search_messages for targeted lookup). Adequate but leaves the routing decision to the agent.

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 mark readOnlyHint=false and openWorldHint=true, so the description carries most of the load and does it well: admin rights requirement, that revoking kills the old link, and that revoke=true issues a fresh link so the chat remains joinable. That is genuine consequence disclosure 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?

Three short sentences with the primary read behavior front-loaded, followed by the revoke consequence and the prerequisite. There is no filler; every clause carries operational meaning.

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 2-parameter, no-output-schema mutation tool, the definition covers the mutation consequence, the auth prerequisite, and what is returned on revoke. It omits any hint of the error/denied path or whether the returned link is the only payload, but nothing essential 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 0%, so the schema documents neither parameter. The description compensates fully for `revoke` (true = revoke old link and return the replacement) but says nothing extra about `chat` beyond the possessive 'a chat's', leaving that parameter's format to inference.

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

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

States a specific verb (get/revoke) and resource (invite link) plus the dual-mode behavior in one sentence. No sibling tool handles invite links, so it is trivially distinguishable from the rest of the telegram_* family.

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 condition that switches behavior (revoke=true) and the prerequisite (admin rights), which is the key when-to-use signal. It does not name a competing alternative, but no sibling overlaps enough to require one.

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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: it explains the returned structure (peers included and excluded) and the important edge case that a folder with no explicit peers is rule-based, which affects how results should be interpreted.

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

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

Two sentences, no waste, with the core purpose front-loaded and the interpretive nuance placed second. Every sentence earns its place.

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

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

With no output schema, the description usefully conveys the return structure and the rule-based case. It does not cover ordering, empty-folder handling, or whether counts are included, but for a zero-parameter read tool the coverage is close to complete.

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

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

The tool takes zero parameters, so the schema imposes no semantic burden. The description adds nothing about parameters because there are none to describe; baseline 4 applies.

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

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

States a specific verb (List) and resource (the account's chat folders) and immediately clarifies what each entry contains (included/excluded peers). It is clearly distinct from siblings like telegram_list_chats, though it does not explicitly name any alternative.

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?

No guidance on when to use this tool versus telegram_list_chats or the many other chat/messaging tools. The second sentence explains output interpretation, not when-to-invoke context, so an agent gets no routing help.

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=false and openWorldHint=true, so the agent knows this mutates state and can reach external chats. The description adds no further behavioral context such as whether source messages are preserved, permission requirements, or what happens with invalid ids.

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

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

A single front-loaded sentence with no filler. Every word contributes to the action and scope, making it efficient for a simple forwarding tool.

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

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

The core operation is clear, but with no output schema, no parameter descriptions, and minimal annotations, the definition omits chat identifier formats, multiple-id semantics, and expected outcomes. It is adequate for a simple mutation but not fully complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It maps the concepts reasonably ('by id' for messageIds, 'from one chat to another' for fromChat/toChat) but does not explain accepted chat identifier formats or that messageIds is an array of positive integers.

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 ('Forward messages') and clarifies the mechanism ('by id from one chat to another'). This clearly distinguishes it from send_message, edit_message, and delete_messages, though it does not explicitly name an alternative 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?

Forwarding existing messages by id implies the use case versus sending or editing, but the description gives no explicit when-to-use guidance, prerequisites, or exclusions. The intended action is inferable but not fully 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 declare readOnlyHint and openWorldHint, so safety is covered. The description adds real value beyond them: it defines the field scope ('all non-secret fields') and explains why a field may be absent (phone numbers only appear when the other party's privacy settings share them), which prevents misreading a missing value as an error.

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 what is returned, then the default-vs-explicit parameter behavior, then the privacy caveat. No filler and nothing buried.

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 single-parameter read tool with no output schema, the description covers what is returned, the default target, and the main data-availability caveat. The remaining gap is the identifier format for 'user', which an agent needs in order to call it correctly on a non-default account.

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% for the single 'user' parameter, so the description carries the burden. It adds the important default behavior (authorized account when omitted) but never specifies the accepted identifier format (username, ID, phone), leaving ambiguity given the sibling telegram_search_users.

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

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

States a specific verb+resource: it returns the complete User object for one account, and clarifies scope ('all non-secret fields Telegram exposes'). It distinguishes itself from the default-account behavior of telegram_me by noting the authorized account is the default and another user can be targeted, though it never names telegram_me directly.

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 conditional for the parameter ('pass user to look at somebody else') but never states when to prefer this over telegram_me, telegram_search_users, or telegram_get_contacts, all of which plausibly return overlapping user data. Usage is implied rather than routed.

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 and openWorldHint=true, covering the safety profile. The description adds the returned-field list but says nothing about pagination or ordering despite a limit parameter, and nothing about rate limits or how many contacts are typically returned. Beyond the annotations it contributes little behavioral context.

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

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

One short sentence with the resource and return fields front-loaded; no filler or repetition. It is efficient, though arguably too terse to earn a 5 given the undocumented limit parameter.

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

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

No output schema exists, and the description usefully enumerates the returned fields, which is the main thing an agent needs. However, the limit parameter and pagination behavior are left unexplained, and with no annotations covering parameters, that gap leaves the definition only minimally complete.

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

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

Schema description coverage is 0% and the single parameter (limit, 1-1000, default 100) is undocumented in both schema and description. The description does not mention the limit or its pagination role, so it fails to compensate for the coverage gap.

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

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

States a specific verb (List) and resource (saved contacts) plus the returned fields (id, name, username, phone), so the agent knows exactly what comes back. It is distinguishable from telegram_search_users, but the description never names that sibling or explicitly contrasts saved contacts with searched users.

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

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

There is no when-to-use guidance, no prerequisites (e.g. logged-in session), and no alternative named. An agent choosing between this and telegram_search_users or telegram_list_blocked gets no routing help.

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 and openWorldHint, so safety is covered. The description adds real behavioral detail beyond that: newest-first ordering, a hard cap of 100, the hasMore/nextOffsetId paging contract, and the rule that a short page with hasMore:false means exhaustion. It omits rate limits and any auth/permission caveats, 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?

Four tight sentences, front-loaded with the action and the identifier format, then paging mechanics, then the termination condition. No filler and no repetition of the title or name.

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

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

There is no output schema, yet the description specifies the return contract an agent needs (hasMore, nextOffsetId, short-page-means-done). Combined with the 0% schema coverage on inputs, this covers everything required to call and iterate the tool 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 description coverage is 0%, so the description must carry the load and largely does: it defines accepted `chat` formats (@username, numeric id, 'me') and explains that `offsetId` is fed back from the previous response's nextOffsetId. The `limit` parameter's default and range are left to the schema, so a 4 rather than 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 ("Read recent messages from a chat") and scopes it to recent history, which separates it from a full export. It does not name or differentiate against close siblings like telegram_search_messages, telegram_get_message, or telegram_export_history, so the agent must infer the boundary itself.

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

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

Usage is implied rather than stated: the tool reads recent messages and can page backwards, which is enough to infer a bulk-recent-read use case. There is no explicit when-to-use vs. search_messages/export_history guidance and no prerequisites (e.g. needing a logged-in session or chat membership) called 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing further: it does not say what happens for a deleted or inaccessible message, whether the call affects read state, or what the response contains.

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

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

One short, front-loaded sentence with no filler. It is efficient, though its brevity edges toward under-specification rather than tightness.

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 read with annotations covering safety and no output schema, the minimum is present. However, with 0% parameter description coverage the agent is left guessing about chat identifier format and message id semantics, so it is only marginally complete.

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

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

Schema description coverage is 0% for both required parameters. The phrase 'by id from a chat' loosely maps to messageId and chat, but gives no format guidance (numeric id vs username vs t.me link, message id vs id within a chat), which is exactly the gap the description should fill at this coverage level.

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 (fetch), resource (message), scope (one, by id) and source (a chat). This cleanly separates it from bulk siblings like telegram_get_history or telegram_search_messages, though it never names those alternatives.

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?

No indication of when to prefer this over telegram_get_history, telegram_search_messages, telegram_pinned_messages, or telegram_search_global, and no prerequisites (e.g. must already know the message id) are stated. The agent must infer the use case from the name alone.

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 tell the agent this is a write operation in an open world; the description adds the return contract (ids invited plus those refused), which is genuinely useful given there is no output schema. It still omits error/permission conditions such as privacy-restricted targets, existing members, or rate limits.

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

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

Three short sentences, zero padding, and the scope/precondition is front-loaded before the identifier-resolution and return details. Every sentence earns its place.

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

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

For a two-parameter mutation tool with no output schema and minimal annotations, the description covers purpose, identifier formats, and the return shape. Missing only failure-mode detail (why a user would be 'refused') and permission nuance, which are secondary for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the load. It does clarify that 'users' accepts @username or numeric id, which is real added meaning, but says nothing about the 1–20 item bound or what identifier format 'chat' accepts.

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

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

States a specific verb+resource ('invite one or more users into a group/channel') plus the governing scope condition ('this account administers'). That scope phrase implicitly separates it from telegram_join_chat (self-join), telegram_add_contact (contacts), and telegram_kick_member/promote_admin, so an agent can route correctly without opening schemas.

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

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

The 'group/channel this account administers' clause gives a clear precondition for use. It does not name an alternative tool or state when-not to use it (e.g. arriving via invite link versus direct add), so it stops short of explicit 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 readOnlyHint=false (a state-changing, non-reversible membership mutation) and openWorldHint=true, so the agent knows it touches the outside world. The description adds the 'public' restriction and input form but says nothing about failure behavior (invalid link, already joined, rate limits) or what the call returns.

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

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

One short sentence with the verb front-loaded and the accepted input formats packed into the same clause. No redundancy or 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 one-parameter mutation with no output schema, the definition covers the essentials but leaves out meaningfully relevant context: whether the join is idempotent, what happens on invalid/expired links, and whether a chat identifier is returned for follow-up calls.

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 0% and the single 'target' property is documented only as a bare string with minLength 1. The description compensates well by stating the accepted value forms ('@username or invite link'), which is exactly the semantic an agent needs to construct the argument.

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 (join) and resource (public channel/group), and the qualifier 'public' plus '@username or invite link' distinguishes it meaningfully from telegram_leave_chat. It does not explicitly name a sibling to avoid, but the action is unambiguous.

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 @username or invite link' implies the accepted inputs and the scope is limited to public channels/groups, which is useful context. However, it gives no exclusions (e.g., private groups requiring an invite, already-a-member cases) and does not point to any alternative tool.

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 declare readOnlyHint=false and openWorldHint=true. The description adds useful context that history is preserved and explains ban vs unban reversibility. It omits the admin/permission requirement and any rate-limit or destructive-side-effect detail, so it is decent but incomplete for a mutation tool.

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 with the core action front-loaded and zero filler. The only minor flaw is the misleading 'kick=true' clause embedded in otherwise efficient prose.

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 and no annotation coverage of destructive behavior, the description covers the ban/unban semantics and history retention but omits permission requirements, self-kick restrictions, and confirmation/irreversibility details. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does: 'unban' is explained, but the description references a 'kick=true' parameter that does not exist in the schema, which will confuse an agent. 'chat' and 'user' are left to name inference 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 a specific verb and resource: 'Remove a member from a group or channel,' which is clearly distinct from self-oriented siblings like telegram_leave_chat. It does not explicitly name or differentiate from other member-management tools such as telegram_block_user or telegram_promote_admin, keeping it at a 4.

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 clarifies the ban/unban choice in-line ('kick=true bans them (default), unban=true lifts the ban so they may rejoin'), which implies usage. However it never states when to prefer this over telegram_block_user or telegram_leave_chat, nor any prerequisites, so guidance is only implied.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds the accepted identifier format but does not disclose consequences such as loss of membership or whether rejoin is required; with annotations carrying the main behavioral burden, a 3 is appropriate.

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 a single front-loaded sentence with no filler. Every phrase contributes to identifying the action and accepted identifier.

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 one-parameter mutation whose safety semantics are covered by annotations and which has no output schema, the description is nearly complete. Minor omissions like confirmation behavior or post-leave effects keep it from a 5.

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 so by explaining that the sole required parameter 'chat' accepts an id or @username, which is meaningful beyond the raw schema type.

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 (Leave) and resource (group/channel) and clarifies the identifier may be an id or @username. It does not explicitly distinguish this from siblings like telegram_delete_chat or telegram_kick_member, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as telegram_delete_chat or telegram_join_chat, and no preconditions or exclusions are mentioned. The intended action is implied by the name and description, but usage guidance is absent.

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 and openWorldHint=true, so the safety profile is covered. The description adds value by enumerating the returned fields (id, name, username, blocked-at) in the absence of an output schema, but says nothing about pagination behavior, ordering, or the limit cap of 100.

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

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

A single front-loaded sentence with no filler; the parenthetical return-field list earns its place because no output schema exists. Nothing could be removed without losing information.

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

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

For a simple read-only list tool with annotations covering safety, the description tells the agent what it does and what it returns. The only real gap is pagination/ordering semantics for limit and offset, which is minor but would matter for large block lists.

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% for two parameters (limit, offset), so the description is expected to compensate and does not mention either. The schema's own defaults and bounds (max 100, min 1) provide structural hints, but paging semantics are undocumented anywhere.

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

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

States a specific verb ('List') and a precisely scoped resource ('the users this account has blocked'), which is clearly distinct from siblings like telegram_block_user, telegram_get_contacts, and telegram_search_users. An agent can identify the tool's role 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?

No when-to-use guidance, no mention of the counterpart telegram_block_user for unblocking, and no statement of when this is preferable to telegram_get_contacts or telegram_search_users. The description offers no routing context 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a real behavioral trait beyond annotations: the allowlist/policy scoping and the fact that the default returns everything the account can see. It still says nothing about pagination, ordering, or why the limit caps at 500, so it is adequate rather than rich.

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 with the core resource definition front-loaded and the flag behavior following. No filler, though the last sentence slightly restates the includeAll default already implied by the second.

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

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

There is no output schema, and the description does not explain the return shape or pagination behavior; combined with the undocumented limit and archived parameters, an agent has enough to call the tool but not to call it optimally.

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 and only explains includeAll. The other two parameters, limit (default 50, max 500) and archived, get no semantic explanation anywhere, leaving meaningful gaps for an agent tuning the call.

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 dialogs') and enumerates what counts as a dialog (DMs, groups, channels), so an agent knows exactly what is returned. It does not distinguish itself from siblings like telegram_common_chats or telegram_folders, but the core purpose is unambiguous.

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 does give conditional guidance for the includeAll flag ('Set includeAll=false to only return allowlisted chats when a policy is configured'), which is genuine when-to-use advice. However, it offers no guidance on choosing this tool over sibling listings such as telegram_common_chats or telegram_search_users.

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 and openWorldHint=false, so the safety profile is covered. The description usefully discloses the return payload (paths, sizes, source message), which matters since there is no output schema, but it says nothing about result volume, ordering, or how the implicit limit interacts with the listing.

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

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

A single front-loaded sentence that names the resource first and parenthesizes the returned fields, with no filler. It is efficient, though very terse given the tool's one undocumented parameter.

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 appropriately enumerates the returned fields, which is the most valuable part. However it omits pagination/limit behavior and any hint about where downloads are scoped, leaving gaps an agent would need before calling it confidently.

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

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

There is a single 'limit' parameter with 0% schema description coverage; the schema only supplies defaults and bounds (1-500, default 50). The description never mentions limit, so it adds no meaning about what is being limited or what happens when more downloads exist than the cap.

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

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

States a specific verb+resource ('List files downloaded by this server') and names the returned fields, which separates it from telegram_download_media (which fetches) and telegram_delete_download. It does not explicitly name those siblings, so an agent must infer the distinction from the 'downloaded by this server' scoping.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as telegram_download_media or telegram_delete_download. The scope phrase 'downloaded by this server' implies it is an inventory of prior downloads, but the agent gets no explicit routing signal.

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 and openWorldHint=true, so safety is covered. The description earns credit for disclosing output content beyond annotations: the current:true marker and the presence of a session hash, which tells the agent what it gets back and what it can chain into.

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

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

Two tight sentences with no filler. The scoping statement comes first and the downstream-consumer hint follows, which is the right order for an agent scanning for relevance.

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 zero-parameter read tool with no output schema, the description supplies the key return semantics (per-device entries, current marker, hash). Ordering or pagination behavior is not mentioned, but that is a minor gap given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify about inputs, and it correctly omits parameter discussion.

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

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

States a specific verb (list) and resource (logged-in devices/sessions) with added scope detail: every device, with the current one flagged current:true. It also distinguishes itself from the adjacent telegram_logout_session tool by naming what that tool consumes.

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 establishes the workflow context by noting each entry carries the hash that telegram_logout_session needs, which tells the agent to call this before logging a session out. It gives no explicit exclusions or alternate listing tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is largely covered. The description adds genuine behavioral value beyond that: it discloses the security-relevant fact that no code or password is retained afterward, which an agent cannot infer from the structured fields. It stops short of saying what happens if no login is pending.

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 filler, with the core action front-loaded ahead of the state-cleanup note. Every clause earns its place.

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

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

For a zero-parameter, no-output-schema mutation tool, the description covers the action and the post-condition. It is essentially complete, missing only edge-case behavior such as what occurs when no login is actually in progress.

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

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

The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% and there is nothing for the description to document on the input side.

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 ('abandon') and a specific resource ('an in-progress login'), which is clearly distinct from its flow siblings telegram_login_start, telegram_login_code, and telegram_login_password. An agent can tell this is the abort step of the login flow 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?

Phrasing 'in-progress login' implies the tool applies only while a login is pending, but the description never states when to reach for this versus completing the flow or restarting. No exclusions or alternative routing are provided.

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

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

Annotations only cover the generic safety profile (readOnlyHint=false, openWorldHint=true). The description adds real behavioral detail: the return flag needsPassword:true signals a 2FA branch, the required follow-up call, and a security constraint ('Never echo the code or password back'). This goes well beyond the structured data.

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

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

Four short sentences, all front-loaded: purpose, prerequisite, conditional branch, and security rule. Every sentence earns its place with no redundancy.

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

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

Given a single required parameter, no output schema, and generic annotations, the description supplies everything an agent needs: the prerequisite call, the conditional 2FA handoff, and the secrecy requirement. Nothing material 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% and the code param is fully documented ('digits only'), so the schema does the heavy lifting. The description only restates that it is the code Telegram sent, adding no format or validation 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 ('Finish login by submitting the code Telegram sent the user') and clearly distinguishes itself from the login siblings (start, password, cancel). An agent can identify this as the code-submission step without inspecting 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?

Explicitly names the prerequisite ('Call telegram_login_start first') and the conditional branch: if 2FA is active, ask the user for the password and call telegram_login_password. This routes the agent to the correct alternative under a stated condition.

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=false, destructiveHint=false, and openWorldHint=true. The description adds meaningful context that the password is used once and never stored, which is important for handling sensitive credentials, though it does not discuss failure handling for an incorrect password.

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: it front-loads the purpose, states the prerequisite, and adds only one important security fact. There is no redundant or filler text.

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 single required parameter, complete schema coverage, and existing annotations, the description provides enough context for safe invocation. It could optionally mention what happens after an incorrect password, but that is not essential for this narrowly scoped login step.

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 password parameter is already documented in the input schema. The description adds security context about the password's lifecycle but no additional format, validation, or semantic 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?

The description states a specific action (complete login) and resource (Telegram two-step verification password), and distinguishes this tool from telegram_login_code by requiring its passwordRequired:true result. An agent can identify its role in the login flow without opening 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 explicitly says to call only after telegram_login_code returned passwordRequired:true, giving a clear prerequisite and preventing premature invocation. This is a precise condition that routes the agent correctly within the login-flow siblings.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the description is not carrying the safety profile alone. It nonetheless adds real behavioral context: the tool sends a code to the user's Telegram app, honors the TELEGRAM_PHONE env fallback, and enforces a security rule about never echoing the code. Return format is not covered, but with annotations present this is solid.

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 trigger condition and effect, then the required input format, then the mandatory follow-up and security constraint. Every sentence carries actionable information with no padding.

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

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

For a two-parameter, no-output-schema tool, the description covers the precondition, the side effect, input formatting with env fallback, the next step, and a security constraint. Nothing needed 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 baseline is 3; the description earns a bump by adding the TELEGRAM_PHONE environment fallback for phone, which is not visible in the schema. The force parameter's 'only when the user asks' guidance duplicates the schema description rather than extending it.

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 ('Begin authorization') with the triggering condition ('when no session exists') and the concrete effect ('Sends the login code to the user's Telegram app'). It clearly differentiates itself from the sibling telegram_login_code, which is named as the follow-up step.

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 precondition ('when no session exists') and routes the agent to the correct next tool ('call telegram_login_code'), plus the phone-vs-env behavior. It does not explicitly say what to do if a session already exists (e.g. use telegram_status), so it stops just short of full when/when-not 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 readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the bulk all=true mode, and the guardrail that it refuses to revoke the server's own session. It does not say whether revocation is reversible or requires re-authentication on the other device.

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

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

Three short sentences, each carrying distinct information, with the primary action stated first and the guardrail last. 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 mutation with no output schema, the description covers the action, the parameter sources, the bulk mode, and the safety refusal. Only irreversibility and the result of a partial failure are left unstated.

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

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

Schema description coverage is 0%, so the description carries the burden and does explain both parameters: hash identifies one session and originates from telegram_list_sessions, while all=true revokes everything except the current session. It does not clarify the hash format or the interaction when both are supplied, which is a minor gap.

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 (revoke) and resource (session), and immediately distinguishes itself from telegram_list_sessions by naming it as the source of the hash. The all=true variant and the self-session refusal make the scope unambiguous.

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 routes the agent: get the hash from telegram_list_sessions, or pass all=true for a bulk revoke. It also states the one case where the tool will not act (the session running this server). It lacks a broader 'do not use this when...' framing, but the key selection logic is present.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds nothing beyond the one-liner: it doesn't say whether the operation is idempotent, whether it affects the peer's read receipt, or whether it must be authorized for that chat.

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

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

One short, front-loaded sentence with no filler. Nothing redundant or padded.

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

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

A state-mutating tool with no output schema and an undocumented required parameter needs more than one sentence. Key facts an agent needs — identifier format, permission requirements, scope of 'all messages' — are 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 0% for the single 'chat' parameter, so the description carries the burden. Saying 'in a chat' only weakly implies the parameter identifies the target chat; it gives no accepted identifier format (username, id, phone) or meaning beyond that.

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

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

States a specific verb+resource ('Mark all messages in a chat as read'), which is unambiguous about the operation. It does not differentiate from siblings that also touch read state implicitly (e.g., telegram_get_history), but the action itself is crisp.

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?

No when-to-use context, no prerequisites, and no named alternatives. An agent gets no guidance on when marking a chat read is appropriate versus simply fetching history, which also often marks messages read.

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 and openWorldHint=true, so the safety profile is covered. The description adds the field list (id, names, username, phone, premium), which is useful output context, but says nothing about auth prerequisites or failure behavior for an unauthenticated session.

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

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

One sentence, front-loaded with the subject ('Full profile of the authorized account') and a compact parenthetical of return fields. Nothing is wasted and nothing is buried.

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

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

With no output schema, the description compensates by enumerating the returned fields, and with no parameters there is no invocation ambiguity. Only the omission of auth context keeps it from being fully complete.

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

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

Zero parameters, and the schema has no properties, so there is nothing for the description to clarify. Baseline 4 applies; the parenthetical field list is a small bonus rather than parameter information.

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

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

States a concrete resource and scope: the full profile of the authorized account, with the returned fields enumerated. It implicitly distinguishes itself from telegram_full_user (other users) via 'authorized account' and from telegram_update_profile via the read-only framing, but never names those siblings explicitly.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The agent has to infer that this is for the caller's own profile versus telegram_full_user for another user, or telegram_status for connection state; no alternative is mentioned.

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 readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds useful format behavior: private chats yield the /c/ form and need no username.

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

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

Two sentences, front-loaded with the core action and the optional-parameter rule; every clause carries useful information.

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

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

For a simple read-only two-parameter tool with no output schema, it explains the output link form and the messageId omission behavior. It could state the return type more explicitly, but the definition is broadly complete.

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

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

With 0% schema description coverage, the description explains messageId's optionality and its effect on scope, and clarifies public/private chat behavior. It still leaves the chat parameter's accepted string format implicit, so some semantic detail is missing.

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

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

The description gives a specific verb ('Build') and resource ('t.me link') and scopes it to one message or a whole chat, making it clearly distinguishable from siblings that fetch messages or export invite links.

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 explains the key conditional: include messageId for one message, omit it for a chat-wide link. It does not name a sibling alternative or when-not-to-use condition, so it falls short of a 5.

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

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

Annotations already declare destructive/mutating behavior (readOnlyHint=false) and open-world reach, so the safety profile is covered. The description adds the days=0 unmute semantics and notes a default mute behaviour, but "default mute behaviour" is left undefined and no auth or return behavior is given.

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

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

Two tight sentences, front-loaded with the action and duration, with the unmute case stated immediately after. No wasted words.

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

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

For a simple 2-param mutation tool with no output schema and annotations covering safety, the description is nearly adequate. The remaining gaps are the undefined "default mute behaviour" and the unspecified format of the `chat` argument.

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 0%, so the schema supplies only types/default/range with no prose. The description meaningfully defines days (N days, 0=unmute), which is real added value, but it says nothing about the required `chat` parameter (ID vs. username format), leaving half the parameters undocumented.

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 ("Mute") plus resource ("a chat") and a duration parameter, and explicitly folds the inverse operation ("0 = unmute") into the purpose. An agent can distinguish this from siblings like telegram_archive_chat or telegram_pin_chat 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 tells the agent that days=0 unmutes, which is useful within-tool routing, but gives no guidance on when to choose this over alternatives or on prerequisites/context. Usage is implied rather than stated.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries the substantive burden and delivers: it discloses that the effect is account-local and invisible to other members. It does not state permission requirements or reversibility, but the scope disclosure is the key behavioral fact an agent needs.

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 tightly written sentences with the core action and the sibling exclusion front-loaded, and zero filler. Every clause carries information.

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

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

For a small mutation tool with no output schema the description covers scope well, but with 0% parameter coverage it leaves the chat identifier and the pinned toggle undocumented, which is a meaningful gap for correct invocation.

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

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

Schema description coverage is 0%, so the schema documents neither parameter, and the description does not compensate. It never explains the 'chat' identifier format (id vs username) or that 'pinned' is a boolean defaulting to true controlling the toggle direction.

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 (pin/unpin) and resource (a chat in the dialog list), and explicitly disambiguates from the message-pinning sibling telegram_pin_message. An agent can distinguish this from telegram_pin_message and telegram_unpin_all 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?

Explicitly names the condition that routes elsewhere ('not a message — use telegram_pin_message for that'), which is a real when-not plus the alternative. It does not, however, address the nearby telegram_unpin_all sibling or when to prefer this over bulk unpinning.

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=false and openWorldHint=true, so the write nature is known; the description adds essentially nothing beyond that. It omits whether pinning notifies chat members, whether it replaces or accumulates with existing pins, and what permissions are required for a chat-wide 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?

A single front-loaded sentence with no filler or redundancy. It is appropriately sized for what it conveys, though that size is also a symptom of its thinness rather than a virtue of economy.

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 4-parameter mutation tool with zero schema descriptions, no output schema, and only minimal annotations, this description is not sufficient. Key operational details (notify behavior, pin limits, permission requirements) are entirely absent.

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

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

Schema description coverage is 0%, so the description carries the full burden and fails to compensate. It implies the unpin toggle but says nothing about 'notify' (presumably controlling member notification) or the format expected for 'chat' and 'messageId'.

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 pair (pin/unpin) and resource (a message in a chat), which is clearer than the name alone and readable without opening the schema. It does not differentiate from closely related siblings like telegram_unpin_all or telegram_pin_chat, but the action itself is unambiguous.

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

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

There is no guidance on when to pin versus unpin, nor any mention of the sibling telegram_unpin_all that also removes pins. An agent gets no routing information and must infer everything from the boolean flag.

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 and openWorldHint=true, so the safety profile is covered. The description usefully adds that results include sender and text, but says nothing about ordering, pagination behavior despite a limit parameter, or whether it caps at Telegram's pin limit.

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

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

A single front-loaded sentence with the verb and resource first and the return content second. No filler or redundancy.

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

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

With no output schema, the description partially compensates by naming the returned fields (sender, text). However, it omits chat identifier format, pagination/limit semantics, and result ordering, which an agent needs to call it correctly on a chat with many pins.

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 0%, so the description must carry parameter meaning and it largely does not. It implies a chat target and mentions returned fields, but never explains the accepted chat identifier format or the limit parameter's role and default.

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 (read) and resource (pinned messages) and even hints at the return payload (sender and text), which clearly separates it from pin_message, unpin_all, and get_history siblings. It stops short of naming an alternative, but the resource is unambiguous.

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?

No when-to-use guidance at all. With siblings like telegram_get_history, telegram_search_messages, and telegram_get_message, an agent gets no cue about when pinned-message listing is the right choice versus general history retrieval, and no prerequisites are mentioned.

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 that this is not read-only and is open-world. The description adds useful behavioral detail about what 'moderator', 'full', and 'none' do, but it omits important operational context such as required permissions, whether changes are immediately effective, and any irreversible or sensitive 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?

Two sentences, front-loaded with the tool's action and followed by essential preset semantics. There is no wasted text.

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 admin mutation with no output schema and minimal annotations, the description leaves significant gaps: required chat/user semantics are undocumented, and permission prerequisites or failure conditions are not described. It covers preset behavior well but is not complete enough for safe invocation by an agent unfamiliar with Telegram identifiers.

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 parameter meaning. It explains the preset enum values and describes rank as an optional custom title, but it does not explain the required chat and user parameters or their expected identifier formats.

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: granting or revoking admin rights for a member, and the preset 'none' makes demotion explicit. It is clear but does not contrast itself with adjacent tools such as telegram_kick_member or telegram_chat_admins.

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 clear context for when to use the tool: granting or revoking admin rights. The preset explanations also clarify the intended effect of each mode, though it does not state prerequisites such as requiring the caller to be an owner/admin or name alternatives.

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 (readOnlyHint=false, openWorldHint=true) already signal a mutating, network-facing operation. The description adds one genuine behavioral fact beyond that: how to clear a reaction. It does not disclose whether a new reaction replaces an existing one (Telegram allows only one per user per message), nor any permission or failure behavior.

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

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

Two short sentences, front-loaded with the core action and followed by the edge-case instruction. Every clause carries information 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?

With no output schema, the description need not explain return values, and the annotations cover the safety profile. However, for a mutating tool the description omits replace-vs-accumulate semantics, permission requirements, and chat identifier format, leaving real gaps for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It usefully documents the clearing semantics of the emoji parameter, but says nothing about the accepted format of 'chat' (id vs username) or 'messageId', leaving two of three parameters undocumented anywhere.

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

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

States a specific verb (send) and resource (reaction/emoji) bound to a specific message, which is clearly distinct from the send_message, edit_message and forward_messages siblings. It does not explicitly contrast itself with any sibling, so it falls just short of the top band.

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

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

The description gives a conditional instruction for clearing reactions ('none' or ''), which is useful usage guidance, but offers no when-to-use vs when-not-to-use context or prerequisites (e.g. required permissions, whether the chat must be joined). Usage is only implied by the tool name and purpose.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value beyond them by clarifying that scheduling happens client-side and this tool only reads back what is queued, preventing the agent from assuming it can schedule. It stops short of describing pagination or the return shape.

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

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

Two tight sentences, front-loaded with what the tool returns and followed by the key behavioral clarification. 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 simple read-only list tool with annotations and no output schema, the description conveys what is returned and the read-only nature. However, with 0% schema coverage the parameters remain undocumented, leaving a real gap for correct invocation.

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

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

Schema description coverage is 0% for two parameters. The description only implicitly references the required 'chat' via 'in a chat' and never explains its accepted format (id, username, etc.), and 'limit' is not mentioned at all, so it fails to compensate for the coverage gap.

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

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

States a specific verb (List) and resource (messages queued to be sent later), scoped to a chat and including the planned send time. The purpose is unambiguous and no sibling tool covers scheduled messages, though it doesn't explicitly contrast itself with any 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?

Usage is only implied: an agent can infer you call this to inspect queued messages, but there is no when-to-use statement, no exclusions, and no named alternative (e.g., send_message for actually queuing). The second sentence clarifies behavior rather than selection 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?

With readOnlyHint and openWorldHint already supplied, the description adds useful behavioral details: matches include their owning chat, results are newest first, date filters use unix seconds, and Telegram cursor overlap is removed and reported as skippedRepeat. These are real operational traits 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?

Four tightly packed sentences: scope first, then return behavior, then date filtering, then the pagination caveat. No filler and the important distinctions are front-loaded.

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