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

Beyond the readOnly/idempotent/destructive annotations, it discloses a real cost: access triggers one cached Telegram request per account. It also clarifies installation-scoped vs per-account data, and warns about two default notions that must not be confused, adding meaningful 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?

The description is long but every section earns its place: core purpose first, then row fields, then the critical using/default warning, then ownership and shared-vs-per-account facts, then the Args block. The structure front-loads the most important information and ends with parameter guidance.

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

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

With no output schema, the description carries the burden of explaining the returned information, and it does so thoroughly: row fields, default semantics, shared vs account-level data, and the access parameter's side effects. An agent has enough to select and invoke 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?

The schema only exposes a boolean `access` with a default; the description fully compensates by explaining what access adds (Premium plus tool availability counts), the cost of setting it true, and when to pass false. This is exactly the information an agent needs 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 opening sentence states the resource precisely: which Telegram accounts the daemon holds and which one calls go to. The description then details row fields and explicitly separates `using` from `default`, making the tool's purpose unmistakable and differentiating it from related tools like tg_account_use.

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

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

The description gives clear context for when the tool is relevant, such as understanding current active account versus persisted default, and references tg_account_use to explain how they can diverge. It does not explicitly enumerate when not to use this tool, but the guidance is strong enough for an agent to decide.

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

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

Beyond the idempotentHint annotation, the description discloses the session-only default, the disk-persist side effect with daemon restart implications, that the background watcher remains unaffected, and that accounts can only be added by the owner from a terminal. This is exactly the behavioral context an agent needs beyond annotations.

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

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

The description is longer than average but every sentence earns its place: core purpose, persistence behavior, watcher exemption, alternative tools, and parameter definitions. The most important scoping statement is front-loaded and the parameter details are cleanly separated under Args.

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 state-switching tool with no output schema, the description covers all operational aspects: meaning of account, meaning of persist, default behavior, side effects, alternatives, and how to verify current state. Nothing needed to call it correctly or reason about its effect 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?

With 0% schema description coverage, the description fully compensates by explaining the account parameter as a signed-in account label or 'main', noting the agent cannot add accounts, and detailing persist=true as remembering the account across clients and restarts rather than just the session. This is complete semantic documentation of both 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 opening line, 'Point the following tool calls at this account', is a specific verb+resource statement that clearly identifies the tool's function. It also actively distinguishes itself from siblings by noting tg_capabilities can target an account without switching and tg_accounts shows current context.

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

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

The description explicitly explains when to use persist=true versus the default session-only switch: persist is for when the owner says 'work from this account from now on', not for one errand. It also names alternatives like tg_capabilities' account argument and tg_accounts for verifying current state, giving clear when-to-use and when-not-to-use 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: results are ordered oldest first, all writing calls are logged, and failed calls are included with their error. This goes beyond the annotations.

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

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

The description is well-structured: a concise definition, a useful distinction from the sibling, an explicit usage hint, and compact parameter explanations. Every sentence contributes value with no fluff.

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 still covers what the tool returns (audit log entries, including failures with errors), ordering, and filtering options. For a read-only list tool with four optional parameters, this is complete enough for reliable use.

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 for parameters. It explains all four: limit, since with ISO and relative formats, method filtering, and chat substring matching. This is exactly what an agent needs to invoke the tool correctly.

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 defines the tool as 'the audit log of every writing call, oldest first' and clearly differentiates it from sibling tg_events by contrasting what happened in Telegram versus what was done on the user's behalf. This allows an agent to immediately understand the tool's role.

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 use this tool to answer 'what did you send?' instead of guessing from memory, and names tg_events as the mirror image alternative. This provides clear selection guidance and distinguishes the tool from its closest sibling.

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?

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: days are UTC and newest first, archive is included, incoming and outgoing are counted separately, and for all-message calendars it relies on sparse server positions that are exact up to ~2000 messages then sampled, with the reply explicitly saying so. This goes well beyond the annotations.

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

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

The description is well-structured with a clear lead, a contrast to tg_unread, a mode explanation, an accuracy caveat, and a readable Args list. It is longer than strictly necessary, and the unexplained 'exact=true' reference adds minor noise, but most sentences carry useful information and the front-loaded purpose is strong.

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 description covers both usage modes, all parameters, default behaviors, sampling caveats, and UTC ordering, which is impressive for a tool with no output schema. However, the mention of 'exact=true' is not backed by a schema parameter, and 'same tabs as tg_media' relies on the agent understanding an external tool's tabs, leaving slight gaps for a fully self-contained call.

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 schema descriptions are completely absent (0% coverage), but the Args section compensates thoroughly by explaining all eight parameters: since/until bounds and defaults, limit_chats, kind, include_own, per_chat, chat, and limit_days. It also gives concrete offset examples like '-6h' and '-30d', which the raw schema does not provide.

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

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

The opening sentence states the tool's core function: 'Which chats had any conversation in a period — where did I talk today' — with a specific resource (chats) and action (find activity). It also explicitly differentiates from tg_unread by noting it covers already-read chats and owner-only conversations, and clearly describes the second calendar mode triggered by the chat parameter.

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 explicit when-to-use guidance: 'Unlike tg_unread this covers chats already read and chats where only the owner wrote, so it is the right start for a daily recap.' It also references related tools naturally, such as using tg_history to jump into a specific day and sharing attachment tabs with tg_media, showing the agent both the intended context and 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 already mark the tool as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavior beyond annotations by requiring admin permissions and clarifying that it retrieves specific admin action types and their timestamps.

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, front-loads purpose and access requirements, and then presents a clean Args list with no filler. Every sentence contributes 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 read-only tool with no output schema, the description gives enough to understand the purpose, required permissions, and parameter semantics. Missing details such as default behavior, pagination, or exact return format are minor because the task and inputs are well specified.

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: each parameter gets a meaningful explanation—chat identifies the target, limit controls event count, query filters by text, and admins restricts to specific people. Some semantic ambiguity remains (e.g., what text the query matches, or whether admins are usernames or IDs), but the coverage is solid.

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 clearly identifies the tool as an admin log for a group or channel, listing the specific event types returned (deleted, banned, promoted, renamed) and the time aspect. It reads as an unambiguous retrieval operation, though it does not explicitly differentiate itself from related siblings like tg_actions or tg_events.

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 states a concrete prerequisite: 'Needs admin rights in that chat.' This gives the agent a clear condition for when the tool is usable. It does not discuss alternatives or suggest when not to use this tool, but the context is clear enough for selection among 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 indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds context about the delivery channel and non-chat scoping, but does not disclose side effects, prerequisites, or delivery behavior beyond that.

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 with no filler. The main action and the key exclusion are both front-loaded.

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

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

The simple single-parameter tool is mostly described well, but the lack of any parameter semantics and absence of differentiation from tg_notify leaves minor gaps. It is adequate but not 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 compensate for the undocumentted 'text' parameter. It does not specify format, length, or content expectations, though the tool name and 'notification' wording imply the text is the alert message.

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 clearly states the verb ('Send'), the resource ('a notification'), and the channel ('through the agent's own bot'). The parenthetical exclusion ('not their chats') helps distinguish this from chat-sending siblings. It is specific and not a tautology.

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 useful negative boundary ('not their chats') but does not explicitly say when to prefer this over siblings like tg_notify or tg_send. Usage is implied rather than stated.

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

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

Annotations already convey that the tool mutates state, is idiempotent, is non-destructive, and operates in an open world. The description adds the toggle direction, but does not disclose side effects such as chat visibility changes or notifications. No annotation contradiction.

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

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

A single, tight sentence with no filler. The verb and operation are front-loaded, and both directions are conveyed in a compact way.

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

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

For a simple two-parameter tool with strong annotations, the description is serviceable. However, it omits parameter semantics for the required chat field and does not explicitly state the undo flag's behavior, leaving an agent to infer part of the invocation contract.

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 only hints at the undo behavior with 'or back out', but gives no meaning for the required 'chat' parameter, such as expected identifier format or how the boolean maps to archive vs unarchive.

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 uses a specific verb ('Move') and a clear resource ('a chat'), and explicitly covers both directions: into the archive and back out. This distinguishes it from siblings like tg_delete, tg_leave, and tg_mute.

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 two relevant use cases are clearly stated: archive a chat or unarchive it. There are no explicit alternatives or exclusions, but the context is unambiguous for a simple toggle 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?

Goes beyond annotations by disclosing the critical timeout behavior: 'A timeout means no answer, which counts as "no permission" — never treat silence as approval.' This is valuable behavioral context that annotations do not capture. It does not contradict the annotations.

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

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

The description is front-loaded with the core purpose, followed by usage context, a safety warning, and a compact Args section. Every sentence earns its place; there is no repetition of schema fields or annotation 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 tool that asks the owner and waits, the description covers purpose, when to use, answer mechanism, parameter semantics, and timeout significance. It does not describe the exact return format, but the phrase 'wait for the answer' and 'they answer by tapping a button or replying in text' imply the response is the answer, which is adequate.

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 fully compensates by documenting all three parameters: question ('what to ask, in plain language'), options ('buttons to offer; defaults to yes/no'), and timeout ('seconds to wait, 10 to 3600'). It adds constraints like the timeout range that the schema does not provide.

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: 'Ask the owner a question through the agent's bot and wait for the answer.' The examples clearly distinguish it from sibling tools like tg_alert or tg_notify by focusing on interactive decision-seeking and waiting for a human response.

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?

Provides explicit when-to-use guidance: 'Use this when the decision is theirs and you are not at the keyboard with them,' with concrete examples. It does not name alternative tools or give exclusion conditions, but the decision context is clear enough for an agent to route correctly.

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 meaningful behavioral context beyond the annotations: blocking is reversible via unblock=true, and the default action is a block. The annotations already indicate non-read-only, idempotent, and non-destructive behavior, so the description complements them without contradiction.

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 a single sentence with no filler, front-loaded with the main action and ending with the parameter behavior. Every word contributes to understanding 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?

For a simple two-parameter tool this is mostly adequate, but there are gaps: no user identifier format, no mention of return value, and no information about what blocking actually affects. The annotations cover idempotency and destructive-ness, but the description alone leaves a few practical details unresolved.

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 clarifies the meaning of the 'unblock' parameter and implicitly identifies 'user' as the block target, but it does not specify the required format for 'user' (e.g., ID, username), leaving some ambiguity.

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 clearly states the action ('Block a user') and the resource, and also covers the unblock behavior. It is specific and unambiguous, but it does not explicitly differentiate itself from sibling tools that might overlap (e.g., tg_moderate), so it falls just short of a 5.

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

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

The description gives clear context: use this tool when you need to block a user, and set unblock=true to undo the block. It does not mention alternative tools or when not to use it, but the stated purpose is enough to guide basic selection.

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

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

Annotations already signal readOnly=false, destructive=true, idempotent=true, so the description does not need to restate safety. It adds a useful behavioral constraint about command editing requiring the bot's token, but does not disclose error/ownership failure behavior or whether edits are immediately visible.

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 two sentences with no fluff: the first front-loads the action and editable fields, the second explains the important command restriction and alternative. 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?

The description covers most user-facing fields and the key ownership/token caveat, but without an output schema it does not explain return values, error conditions, or how to specify bot (username vs ID). lang_code is also missing. It is adequate for a straightforward edit tool 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?

With 0% schema description coverage, the description compensates partially by mapping name/about/description fields and defining commands as a list of {command, description} objects. However, bot is only vaguely implied as an identifier and lang_code is left completely unexplained, so parameter coverage is incomplete.

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 ('Edit a bot you own') and identifies the resource plus editable fields: display name, 'what can this bot do' text, and description. It is distinguishable from read-only siblings like tg_bot_info, though it does not explicitly name sibling edit 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 clearly scopes the tool to bots the agent owns and explicitly says commands can only be set for this agent's own bot because Telegram requires the bot token. It also provides an external alternative (@BotFather) for other bots, giving a practical when-to-use boundary.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds a useful behavioral nuance not captured by annotations: the command list is contingent on the bot being the agent's own bot. This is meaningful additional 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?

The description is a single sentence and reasonably compact. It is slightly awkward in phrasing ('Name, about and description'), but it front-loads the return content and the key conditional about command lists.

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 tool with two undocumented parameters and no output schema, the description leaves important gaps: parameter formats, language code behavior, and what 'bot you own' means operationally. It is adequate for a very simple read-only tool but incomplete for reliable 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 explain the parameters, but it does not. It never clarifies what format bot should take (ID, username, handle) or what lang_code controls. Both parameters remain effectively 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?

The description identifies the resource (a bot the agent owns) and the fields returned (name, about, description, command list). It is clear enough to distinguish from editing tools like tg_bot_edit, though it lacks an explicit verb like 'retrieve' and does not name sibling 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?

The description implies usage context: it applies to bots the agent owns, and the command list is only included when the bot is the agent's own. However, it does not specify when to choose this over related tools such as tg_bot_edit or tg_capabilities, nor does it state exclusions.

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

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

Direct contradiction: annotations declare destructiveHint=false, yet the description says the tool can 'delete everything in data/downloads.' That is destructive behavior, and the contradiction is significant. The idempotentHint=true aligns with cache-clearing, but the annotation conflict forces a score of 1.

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

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

A single sentence that front-loads the primary purpose and then states the optional behavior. There is no filler or redundant restatement of the tool 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?

The tool is simple with one optional parameter, and the description covers the core behavior. However, the destructive optional operation lacks caveats about permanence or scope, there is no output/return information, and the annotation contradiction makes the description incomplete as a safe guide.

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 schema only provides type and default for the 'downloads' parameter, with 0% schema description coverage. The description compensates by tying the parameter to 'optionally delete everything in data/downloads,' which gives an agent the essential meaning, though it could explicitly state 'when true.'

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 ('drop the cached chat-title index'), the resource, and the trigger condition ('use after chats are renamed'). It also clearly names the optional secondary effect (delete downloads), making the tool's purpose unambiguous and distinguishable from related index/cache operations.

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

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

The description explicitly says when to use the tool ('use after chats are renamed') and gives the condition for the optional downloads deletion. It does not mention when not to use it or name alternatives, but the stated context is clear enough for basic selection.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds that ceilings are read from Telegram, not guessed, and that only the chat part costs a request. It explains the grouping of blockers by fix type, which is useful beyond the annotations. No contradictions.

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 long but information-dense, starting with a one-line summary before moving to usage and parameters. Every sentence adds either context, a constraint, or a cost warning, so it earns its length.

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 capability-reporting tool with no output schema, the description covers purpose, when to use it, parameters, account behavior, and cost model. An agent has enough to invoke it correctly and interpret the conceptual result without needing more.

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 carries the entire load for the three parameters. It explains chat's accepted formats ('id, @username, exact title or "me"') and what it reports, notes the cost implication, and clarifies that chat rights are not reported with all_accounts. This fully compensates for the missing schema descriptions.

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

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

The description opens by defining the tool's scope: reporting what this agent can and cannot do and what would unblock the rest. It gives a specific output shape ('N of M tools available, K blocked') and distinguishes this from trying tools and reading errors, so an agent understands this is the capability-introspection tool, not a sibling like tg_status or tg_limits.

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 start here when unsure whether something is possible at all, positioning it as a cheaper alternative to trying a tool. It also gives conditional guidance: pass chat only when the question is about a chat, and use all_accounts when several accounts are signed in. This is clear contextual routing, though it doesn't name sibling tools explicitly.

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

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

The annotations already provide readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description does not need to restate those. It adds useful behavioral details such as 'slowmode: seconds between messages per member, 0 turns it off (supergroups only)' and 'forum: true turns the supergroup into a forum with topics.' However, it does not disclose side effects such as overwriting existing values or the potential consequences of changing default member rights.

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

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

One concise introductory sentence followed by a compact Args block. Every line adds either a parameter definition or a constraint, and there is no filler or repetition of schema 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 complex 7-parameter tool with nested objects and no output schema, the description covers the parameter semantics thoroughly and includes important constraints. It is slightly incomplete regarding how the chat identifier should be provided and what destructive consequences may follow, but the core calling contract is well specified.

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 full burden for parameter meaning, and it does. It explains chat, title, about, photo, slowmode, permissions (with example JSON and allowed keys), and forum, giving each parameter far more meaning than the bare schema names.

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 the verb 'Change' and the exact resource ('a group's or channel's'), then enumerates the affected attributes: 'title, description, photo, slow mode, the default rights of its members, or turn topics (forum mode) on and off.' This clearly scopes the tool to chat-level settings, though it does not explicitly differentiate it from siblings like tg_topic_edit or tg_edit.

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 guidance about when to use tg_chat_edit versus alternatives. The only contextual note is 'supergroups only' for slowmode, which helps slightly but does not explain when this tool should be preferred over sibling tools such as tg_topic_edit, tg_moderate, or tg_edit.

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

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

Annotations already declare the operation read-only and idempotent, and the description adds meaningful behavioral detail: counters are server-counted with no history download, zero counts are omitted, similar results may be empty or truncated, and truncation is signaled in the reply. This goes well beyond the structured metadata.

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 well-structured, front-loaded with a concise summary followed by an Args block. Each parameter explanation adds value, though the similar explanation is slightly elongated with caveats; still, no sentence is wasted.

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

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

Without an output schema, the description still surfaces the expected fields, counter categories, and special reply behavior such as total/truncated for similar. An agent has enough information to decide whether to call this tool and how to configure its parameters.

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 thoroughly explains chat accepted formats (id, @username, exact title), counters semantics and behavior, and similar's channel-only scope plus truncation behavior. This is rich, actionable parameter documentation.

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 clearly identifies the tool's purpose: retrieving details about a chat or person, including id, username, type, member count, and bio. It goes beyond a tautology by enumerating what 'info' means, but it does not explicitly distinguish itself from sibling tools like tg_person or tg_status.

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 practical guidance for using optional parameters: counters should be used to see how much content is available before fetching, and similar is channel-only. It provides clear context for parameter choices, though it does not explicitly say when to choose this tool over 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 already flag the action as non-read-only and destructive. The description adds a crucial behavioral detail: pressing a button acts as the user and must be confirmed first unless already asked. This goes beyond the structured safety signals without contradicting them.

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 concise sentences, front-loaded with the core behavior and with no filler. The warning about user confirmation earns its place because it changes invocation behavior.

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 interaction tool, it covers invocation modes, button matching, and safety confirmation. Minor gaps remain around error cases (e.g., no inline keyboard, invalid index) and return values, but these are not critical 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 `button` well: optional, accepts exact-ish text or index. However, `chat` and `message_id` are left to name/type inference and are not explicitly tied to 'the bot's message' in the 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?

Names a specific verb and resource: inline keyboards under bot messages. Clearly distinguishes two modes — listing buttons without `button`, pressing one with it — so an agent understands the tool's exact purpose without guessing.

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 usage context: call without `button` to inspect, with `button` to press, and requires user confirmation before clicking. It does not name alternative sibling tools, but the context is clear enough that alternatives are unnecessary.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds that results are limited to groups/channels shared with the target person, but it does not disclose ordering, pagination, or other runtime behaviors beyond that scoping.

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 extremely concise: two short clauses with no filler. The core result is front-loaded, and the use-case note earns its place by helping the agent decide when to call 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?

For a simple two-parameter lookup, the description conveys scope and purpose well. However, it lacks explicit parameter mapping, especially 'limit,' and since there is no output schema, the absence of any return-value description leaves some ambiguity about what the agent will receive.

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 schema_description_coverage at 0%, the description carries the full burden for parameter meaning. It indirectly defines 'user' as 'this person,' but the 'limit' parameter is not mentioned at all, leaving one of two parameters unexplained.

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 clearly identifies the resource as 'groups and channels' and specifies the relationship 'you and this person are both in,' which makes the tool's purpose unambiguous. It also distinguishes itself from sibling tools by focusing on shared/overlapping chats rather than general chat info or contacts.

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 provides clear use cases: 'where do we overlap' and 'placing an unknown contact.' It does not explicitly name alternative tools or state when not to use it, but the context is specific enough to guide an agent toward appropriate invocation.

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 meaningful behavioral context beyond annotations: the note is private, visible only to the owner, not sent anywhere, and unreadable by the person. Annotations already indicate mutability and destructiveness, but the description usefully clarifies privacy semantics. It does not contradict annotations.

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

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

The description is concise and well-structured: a one-line purpose summary followed by a compact args block. Every sentence adds useful information, and the privacy note is high-value rather than 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?

Given six optional parameters, no required fields, no output schema, and zero schema coverage, the description is adequate but has gaps. It does not clarify what happens on overlapping arguments (e.g., delete plus add), what a successful call returns, or what preconditions apply to users being edited.

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 of explaining parameters. It maps phone/name/last_name to adding, user to deletion/noting, delete to removal, and note to private annotation. This provides real meaning beyond the raw parameter names, though it leaves some combination rules implicit.

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 clearly states the tool adds a contact by phone number, deletes one, or keeps a private note on a person. It names a specific resource ('contact') and explicit operations, so an agent can understand the core function. It does not explicitly differentiate from sibling tools like tg_contacts, but the operation set is specific enough.

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 argument-level guidance but no overall when-to-use guidance. It does not mention when to prefer this tool over related siblings like tg_contacts or tg_person. There is no statement about exclusions or alternative tools for reading contacts.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral constraints: query only applies when kind='all', birthdays are date-sorted, and top is ranked by Telegram itself. No contradiction with annotations; these details go beyond 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?

The description is compact and well-structured: a one-line opener followed by a tidy three-item arg list. Each kind line adds functional meaning, so every sentence earns its place without fluff or repetition.

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-required-parameter, read-only tool with no output schema, the description fully covers all inputs and all kind variants, including sorting and intended use cases like birthdays. An agent can correctly select and invoke any mode based solely on this description.

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 there are no enumerations, so the description carries the full parameter-documentation burden. The 'Args' section defines all three parameters: query (name/username filter, scoped to all), limit (row count), and kind (all five accepted values with their precise meanings). This fully compensates for the schema's silence.

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

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

The opening phrase 'Your contacts, or a slice of them' names the resource but lacks an explicit verb like 'list' or 'get'. However, the kind parameter enumerates five concrete retrieval modes (all, birthdays, top, online, blocked), making the tool's purpose clear and distinguishable from siblings such as tg_block or tg_person.

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

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

The kind descriptions implicitly route usage—'birthdays' explicitly answers 'whose birthday is coming up', 'online' selects currently online contacts, and 'blocked' is the block list. But the description never names alternatives or states when not to use this tool, such as using tg_person for a single contact's details, so the guidance is implied rather than explicit.

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

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

Annotations already indicate this is a mutating, non-idempotent, non-destructive operation. The description adds the useful behavioral detail that users can be invited immediately during creation, but it does not disclose longer-term effects such as whether the group is immediately visible, whether creation may fail due to duplicates, or what happens to partially created entities.

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: one clear purpose sentence followed by a concise Args block. Every line adds necessary semantic information with no filler or repetition of the schema.

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

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

For a creation tool with four parameters and no output schema, the description gives enough to invoke it correctly: required title, optional users, kind, and about are all explained. It lacks only minor operational context such as expected return value or how to address the newly created chat afterwards, but nothing essential to a first call 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?

Input schema coverage is 0%, so the description carries the full burden of explaining parameters. It does so well: title is described as the chat name, users lists accepted identifier forms, kind explains the group/channel distinction, and about is identified as the chat description. This goes well 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?

The description opens with a specific action and resource: 'Create a supergroup or a channel and optionally invite people right away.' This clearly distinguishes the tool from sibling tools like tg_topic_create or tg_invite by naming both the object created and the optional follow-on invite behavior.

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 purpose strongly implies when to use the tool, but the description never explicitly states when to prefer it over alternatives, nor does it mention exclusions such as 'use tg_invite for existing chats' or 'use tg_topic_create for topics.' The guidance is therefore implied rather than explicit.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds important context beyond annotations: 'revoke=True removes them for everyone' and 'Not recoverable,' which meaningfully informs an agent about consequences. No contradiction with 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?

Extremely concise and well-structured: three short sentences with no filler. The most critical behavioral facts—multi-user revocation and irreversibility—are front-loaded.

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

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

For a simple deletion tool, the description covers the essential facts: what it deletes, the revoke flag behavior, and irreversibility. It lacks explicit explanation of required parameters and result behavior, but the straightforward schema and strong annotations reduce the need.

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 adds meaning to 'revoke' by explaining its effect, but 'chat' and 'message_ids' are left to be inferred from names and the overall deletion context. Partial compensation, not complete.

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

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

States a specific verb and resource: 'Delete messages.' It clearly identifies the operation and distinguishes itself from the many sibling tools by naming the core action. The additional revocation detail reinforces the tool's purpose.

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 no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where another tool might be more appropriate. The revoke behavior is stated, but not as a usage 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 readOnly/openWorld/idempotent/non-destructive, and the description adds non-obvious behavior on top of that: sparse rows om it fields whose value equals the default (no pinned = not pinned), the t.me link construction, and the account-specific trait that most chats live in the archive. These shape both result interpretation and the default call pattern and appear nowhere in the annotations or schema.

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

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

One-sentence purpose up front, then output semantics, then a per-arg block — the right structure for a 5-param tool with a bare schema. The kind="saved" tail rambles and truncates slightly (". . . stuff articles, links, ..."), but no sentence is wasted and the tg_history cross-reference 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 row-semantics paragraph partly fills the return-shape gap (which fields appear, how to build the link). What's missing is the chat identifier an agent should hand to follow-up tools, plus any pagination/limit-bound behavior — a listing tool that feeds the rest of this API should say how rows reference chats for the next call.

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 kind is just a bare string with no enum, so the description carries all parameter meaning — and it defines all 5: limit, unread_only, archived (three-state with folder semantics plus advice), query (title-contains match), and kind (enum-like values including "inactive" and "saved" that are only discoverable through this prose). It fully compesates for an 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?

Opens with a precise verb+resource statement: "List chats, most recent first, with unread counts" — it names the object (chats), the ordering, and the data each row carries. The row-semantics paragraph further pins down what this tool returns, and the sibling list shows it is the chat-listing tool, distinct from tg_search, tg_folders, and tg_unread.

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

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

Gives concrete when-to guidance: "This account keeps most chats archived, so pass null when searching for a chat rather than browsing the main list," and it maps user intent to parameter values (kind="group" answers "what groups am I in"; kind="saved" is tied to the follow-up call tg_history(chat="me", saved_from=<that author>)). It stops short of full when-not-to routing — it never says to prefer tg_search for full-text search.

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

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

Annotations already cover idempotentHint=true, rereadOnly=false, destructive=false, and openWorld=true. The description adds one useful behavioral detail (the default destination directory), but does not disclose what happens if the message has no media, whether it overwrites existing files, or whether it returns a path. With annotations carrying the safety profile, this modest addition merits a 3.

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 one short sentence plus a helpful default-location detail. It is front-loaded with the primary action and leaves out filler. It loses one point because it could have used the remaining space to clarify parameters or mention the many-sibling.

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 download tool with no output schema and 0% parameter coverage, the description leaves too much unspecified: how to identify the chat, the destination path semantics, and the expected result. Annotations clarify safety and idempotency but not operational details like file naming, overwrite behavior, or error cases, so the description is not complete 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%, and the description adds no parameter-specific meaning: it does not clarify what 'chat' expects (ID vs username vs entity), the format of 'message_id', or what 'dest' accepts (relative vs absolute path). The only hint is that the default destination is data/downloads. With zero schema coverage, the description fails to compensate for the 3 undocumented 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 states a specific verb ('Download') and resource ('the media attached to one message'), and clarifies scope by saying 'one message' — distinguishing it from tg_download_many. It does not name the sibling explicitly, but 'one message' vs the many-sibling makes the distinction clear enough.

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 the tool is for downloading media from a single message and the default destination is project's data/downloads. It gives context but no explicit when-to-use guidance or alternatives; the sibling tg_download_many is implied but never mentioned. A 3 is appropriate because the context is present but exclusions are left to inference.

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

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

Annotations already mark the tool as non-destructive and idempotent; the description adds useful behavior beyond that: a 50-item limit and a default download destination. No contradiction with annotations is present.

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: a one-sentence purpose, a source hint, then a short Args list. Every sentence adds information and there is no repetition of schema fields.

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 three-parameter tool with annotations covering safety, the description covers purpose, parameters, limits, source, and default destination. A minor gap is not describing what happens if more than 50 ids are passed or what the tool returns, but these are not essential 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%, but the description compensates fully by explaining all three parameters (chat, message_ids, dest) and the default value for dest. This is exactly what the agent needs beyond the bare schema types.

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 uses a specific action and resource: 'Download several attachments at once (max 50).' It marks the batch scope, which separates it from the single-download sibling tg_download, and 'Get the ids from tg_media' tells the agent where the required ids come from.

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

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

It clearly states the batch use case ('several attachments at once') and supplies the necessary preliminary step ('Get the ids from tg_media'). It does not explicitly name tg_download as the single-item alternative, so it stops short of a full when-not-to-use rule.

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 establish that the operation is not read-only but also not destructive and is idempotent. The description adds valuable behavior beyond annotations: it does not actually send, the user is the one who sends, nothing leaves the account, and drafts persist across devices. It does not discuss overwriting an existing draft, but the idempotency hint reduces that concern.

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. The core behavior is in the first sentence, followed by succinct usage guidance and the key parameter behavior. 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 simple four-parameter tool, the description provides enough context to select and invoke it: target chat is clear, draft content is implied, clear semantics are explicit, and usage context is strong. The main gap is the reply_to parameter, which is not described at all.

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 explicitly explains clear ('Pass clear=true to wipe the draft') and implies chat through 'Save a draft in a chat,' but text and reply_to receive no direct semantic explanation, and reply_to is left entirely 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?

The description opens with a specific verb and resource: 'Save a draft in a chat instead of sending it.' It clearly differentiates from sending-related siblings by explaining that the user sees the draft and presses send themselves.

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

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

Explicitly states when this tool is the right choice: 'This is the right tool when a message needs the user's eyes first.' It further clarifies the use case with behavior differentiators like 'nothing leaves the account' and 'survives across devices,' and instructs to pass clear=true to wipe the draft.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile. The description adds useful scope information (all drafts in the account, chat association), but does not disclose return format, ordering, or behavior when no drafts exist. This is comparable to the get_calls calibration where a scoping constraint adds moderate value beyond 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?

A single sentence with no filler words. The key scope ('every', 'in the account') is front-loaded and the chat association is a necessary differentiator. It earns its place without any 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?

For a parameterless, read-only list tool, the description is largely complete: it states the resource, the scope, and the included context (chat). The lack of an output schema and no mention of return type are minor gaps given the simplicity and the annotation coverage.

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 are zero parameters and the schema coverage is trivially 100%, so the schema carries no burden. The description adds no paramater-specific details, but none are needed. The baseline for zero parameters is 4.

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 clearly identifies the resource (unsent drafts) and the scope (every drafts in the account) and adds the chat association. It is a precise noun-phrase definition rather than an explicit verb phrase, and it does not name or contrast with sibling tools like tg_draft, but it is still specific enough for an agent to understand the listing purpose.

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 is provided on when to use tg_drafts versus related tools such as tg_draft, tg_pending, or tg_history. There are no exclusions or alternatives mentioned, so the agent must infer usage from the name and description 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?

With readOnlyHint=false and destructiveHint=true already present, the description is not required to restate that this mutates data. It adds the useful constraint 'own sent', but does not disclose effects such as replacing the original text, edit visibility, or failure conditions, so it provides only modest value 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?

One short sentence, front-loaded with the action, and every word adds scope ('one', 'own', 'sent', 'messages'). No redundant clauses or boilerplate.

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 tool has three required parameters, no output schema, and no parameter descriptions, yet the description only explains the general purpose. An agent still lacks the information needed to construct correct arguments or anticipate the output, so the definition is not complete enough 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 carries the burden of explaining chat, text, and message_id. It gives no parameter-level details: 'chat' could be an ID or username, 'message_id' could be chat-scoped or global, and whether 'text' is the full replacement content is only implied. Some inference is possible from the field names and tool purpose, but the description does not compensate for the missing schema descriptions.

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

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

The description states a specific verb ('Edit') and target ('one of your own sent messages'), making it clearly a message-editing operation. This distinguishes it from sibling edit tools like tg_chat_edit, tg_bot_edit, tg_topic_edit, and tg_contact_edit without needing their schemas.

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

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

The phrase 'own sent messages' gives clear context: this tool applies only to messages already sent by the caller, which implies it is not for drafts, scheduled messages, or others' messages. It does not explicitly name alternatives or state when-not-to-use, 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 convey read-only, idempotent, non-destructive behavior, so the description primarily adds the 'newest last' ordering and watcher-source context. It does not describe the resulting message shape or whether events are deduplicated, but the annotation coverage lowers the burden.

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 with the essential purpose, followed by terse parameter explanations. Every sentence earns its place and no irrelevant detail is included.

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 listing tool with two optional parameters, the description covers the use case, ordering, and parameter semantics. It lacks details about the response format, but its simplicity and strong annotations make this a minor gap rather than a critical omission.

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 description compensates by explaining both parameters: limit as 'how many events' and since as an 'ISO timestamp lower bound' with a concrete example. This adds real meaning beyond the bare schema types, though limit could be more precise about bounds or defaults.

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

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

The description states a specific resource ('incoming messages captured by the watcher') and a clear ordering ('newest last'), going well beyond the generic name tg_events. It distinguishes itself from sibling tools like tg_history or tg_unread by identifying the watcher as the source.

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 the tool is for retrieving recent watcher-captured incoming messages, but it never explicitly states when to prefer this over siblings or when it should be avoided. No alternatives are named, so the usage guidance is only inferred rather than explicit.

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

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

The description adds substantial behavioral detail beyond the annotations: media downloading, local file paths in transcripts, t.me message links, per-chat failure isolation ('One failure does not stop the rest'), skipped-attachment behavior, and a message cap. These side effects matter for a tool with readOnlyHint=false, and they are clearly disclosed.

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

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

The core purpose is front-loaded in the first sentence, followed by a short behavior summary and then a compact Arg list. Every line adds information; there is no filler. The length is justified by the 9 parameters and the need to explain batch behavior and media handling.

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?

Despite having no output schema and 9 parameters, the description is complete for invocation: it explains limits, defaults, batch semantics, date constraints, media handling, and destination defaults. It also gives the recommended workflow with tg_activity. An agent has enough context to call this tool correctly without external documentation.

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 full responsibility for explaining the 9 parameters. It delivers: chat vs chats, limit semantics ('most recent, written oldest first'), format guidance ('json for analysis, markdown or text for reading'), dest default, since/until bounds, and media_max_mb behavior. Every parameter in the schema is explained.

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?

Description opens with a specific verb and resource: 'Dump whole conversations to files', and adds a concrete cap (max 5000 messages per chat). It explicitly frames itself as the tool for 'give me the full conversation with everything in it', which distinguishes it from narrower history/search siblings like tg_history or tg_search.

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?

Provides clear usage context both by naming the exact user request it satisfies ('give me the full conversation with everything in it') and by instructing the agent to pair it with tg_activity: 'take the chat ids from there, feed them in as chats'. It doesn't explicitly name tools not to use, but the guidance is strong enough for an agent to select it appropriately.

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

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

Beyond the annotations, the description adds valuable behavioral detail: 'Anything not passed is left untouched' clarifies partial-update semantics, and 'The chats themselves are not touched' explains the delete behavior. This aligns with destructiveHint=true while reassuring that chat data is preserved. It provides meaningful context about side effects.

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

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

The description is well organized with a concise intro followed by a labeled Args list. The most important invariant ('Anything not passed is left untouched') is front-loaded. Every sentence earns its place without redundant 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 tool with 9 parameters, no output schema, and nested objects, the description covers all parameters and key behavioral guarantees. It does not mention return values, error conditions, or interactions between mutually exclusive operations like create and delete, which leaves a modest gap for an agent planning a call.

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 schema description coverage at 0%, the description carries full responsibility for explaining parameters, and it does so for all nine: folder, add, remove, create, delete, rename, emoji, rules, and exclude. It adds constraints like 'max 12 characters' for create and lists rule checkbox names. Some details remain underspecified, such as the exact formats for chat identifiers and the rules object structure, so it is not perfect.

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 opens with specific verbs and a resource: 'Create, delete, rename and fill Telegram folders.' This clearly distinguishes tg_folder_edit from sibling read-only tools like tg_folders and from chat/topic editing tools. The scope is unambiguous and action-oriented.

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 practical usage context, such as 'folder: existing folder by title or id (from tg_folders); not needed with create,' which tells the agent when the param is required and where to get it. It also communicates safe partial updates with 'Anything not passed is left untouched.' However, it does not explicitly state when to prefer this tool over alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond those annotations by specifying exactly what each folder entry contains: pinned chats, explicitly included chats, exclusions, and automatic rules. No contradiction with annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the core subject, and the second adds the necessary detail about folder contents. Every clause contributes distinct information.

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

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

For a zero-parameter, read-only informational tool with no output schema, the description provides enough context for an agent to understand what the tool returns: folder membership, exclusions, and automatic rules. No critical detail is missing 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?

The tool accepts zero parameters, so there is no parameter ambiguity for the description to resolve. The schema coverage is effectively 100%, and the description adds no confusing parameter-related claims. The zero-parameter baseline of 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?

The description clearly identifies the resource: Telegram folders/chat filters and the chats they contain. It distinguishes itself from editing or structural tools by focusing on folder membership, but it lacks an explicit verb such as 'returns' or 'lists', so the action is slightly implied rather than stated.

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

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

There is no guidance about when to use this tool versus alternatives like tg_folder_edit or tg_structure. The description implies it is a lookup tool for folder contents, but it never states the condition, prerequisites, or which sibling tools to prefer in other situations.

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 indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description is consistent with these. However, it adds no extra behavioral context such as whether forwarding copies messages, whether the original is retained, or what happens on failure.

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 eight words and contains no filler; the action and direction are front-loaded. Any gaps are matters of substance rather than conciseness.

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, no parameter descriptions, and no behavioral details, the definition is thin for a tool that must take three required parameters. The annotations cover mutability, but an agent still lacks information about return values, errors, prerequisites, or usage boundaries.

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, but it only loosely maps to the three parameters: 'messages' suggests message_ids and 'one chat to another' suggests from_chat/to_chat. It provides no format, type, constraint, or relationship details beyond the schema itself.

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 uses a specific verb ('Forward') and resource ('messages') with direction ('from one chat to another'), clearly stating the core operation. It does not explicitly distinguish itself from siblings like tg_send or tg_message, so it stops short of a 5.

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

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

The description offers no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states the action, leaving the agent to infer appropriate use 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?

Discloses meaningful behavior beyond the safe-read annotations: ordering (oldest to newest), pagination semantics (before_id yields older messages), and the concrete output-size effect of brief ('about a quarter smaller'). Fully consistent with readOnlyHint=true, idempotentHint=true, and destructiveHint=false — no contradiction.

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 framing sentence followed by a compact Args block. Every line earns its place with operational information, and the most complex parameters (saved_from, brief) get the most explanation — no filler anywhere.

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

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

For an 8-parameter tool with a bare schema and no output schema, the description covers all invocation semantics, including tricky conditional constraints. The only gap: the return value shape/format is not described, and no output schema exists to fill that 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?

With 0% schema description coverage, the description fully compensates: chat's five accepted formats, saved_from's conditional 'chat="me" only' rule, topic's id source, and brief's exact output effects all add meaning far beyond the schema's bare types and defaults.

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

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

Opens with a specific verb+resource+scope: 'Read messages from one chat, oldest to newest.' The ordering constraint and the single-chat scope clearly distinguishe it from siblings like tg_history_batch, tg_search, and tg_message.

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

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

Provides explicit operational guidance on parameters — 'Twenty is a conversation; raise it when reading a chat properly, not to be safe' and 'brief ... for triage, not for reading a chat closely' — and cross-references tg_topics and tg_dialogs(kind='saved'). However, it never explicitly names alternatives or states when-not-to-use this tool in favor of a sibling.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds extra behavioral detail: brief mode drops reactions, link cards, and edit times while keeping messages identical, and search is applied to every chat. It stops short of describing failure or pagination behavior, but the added context 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?

The description is concise and front-loaded with the core purpose, followed by a compact Args list. Every sentence adds functional value, including the triage caveat for brief, with 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 batch read tool with no output schema, the description covers use case, parameter meanings, and behavioral nuances thoroughly. The only notable gap is that it does not describe the shape of the returned data, but the core usage context is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden of documenting parameters. It does so well: chats accepts ids, @usernames, or exact titles; limit is per chat; search applies to every chat; and brief has a precise effect on output size and content.

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

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

The description states a specific action ('Read several chats in one call') with a resource ('chats') and a limit ('up to 25'). It also distinguishes itself from the sibling tg_history by explicitly positioning itself as a batch alternative, so an agent can tell what this tool does and how it differs.

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

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

The description explicitly says 'Use this instead of calling tg_history repeatedly when comparing or summarising multiple conversations.' This gives a clear condition and names the alternative, and also includes a caveat about brief mode being for triage, not close reading.

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 goes well beyond the annotations: it discloses that the index is a plain-text copy stored in data/index.db with mode 600, that action="drop" deletes it, that sync is incremental and cheap on repeat, and that the first sync of a chat must name it. This gives the agent an accurate mental model of side effects, storage, and destructive behavior. It is fully consistent with destructiveHint=true and idempotentHint=false.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose in one line, then provides a compact warning about indexing scope, then a clearly labeled arg list. The structure makes it easy for an agent to scan actions and parameter semantics without wading through 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 tool with four parameters, no output schema, and destructive potential, this description covers the essentials: what the index is, where it lives, how each action behaves, parameter constraints, and even the return shape for 'status'. Nothing critical is missing for an agent to select and invoke 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 carries the full burden, and it succeeds. It explains every parameter: action and its three enumerated behaviors, chats with the 25-chat limit and omission semantics, since with allowed formats ('today' or ISO date), and limit with default, max, and the 'go deeper' meaning. This is far richer than 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?

The first sentence states the resource precisely: 'Local full-text index of the correspondence, for tg_search(engine="local")'. It immediately orients the agent to what this tool manages and how it relates to a sibling tool. The arg list then clarifies the concrete operations (sync, status, drop), removing any ambiguity.

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

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

The description gives clear context: the tool indexes only explicitly named chats, it is for local search, and the action values define distinct use cases. It also states an important precondition ('the first sync of a chat must name it'). However, it does not explicitly say when not to use this tool or point to alternative tools beyond mentioning tg_search.

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

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

Annotations already signal mutation (readOnlyHint=false), and the description adds useful specifics: it can return a primary invite link, add users, and revoke an old link while issuing a new one. This goes beyond the annotations by exposing a potentially destructive side effect (revoking an existing link) and the 'and/or' conditional 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 short and front-loaded with the core purpose, followed by a compact Args list. Every line adds information about a parameter or behavior, with no filler or repetition of the schema's type 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 four-parameter mutating tool with no output schema, the description covers the main invocation concerns: what each argument does and the primary side effects. It does not explain edge cases like calling with no users and link=false, or how output is structured, but it is still largely self-sufficient for correct invocation.

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

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

Schema description coverage is 0%, but the description documents all four parameters with meaningful semantics: chat is 'the group or channel,' users are 'who to add,' link 'also return[s] the primary invite link,' and revoke 'revoke[s] the old link and issue[s] a new one.' This fully compensates for the lack of schema-level descriptions.

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

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

The opening line names a clear verb and resource: 'Invite people to a chat and/or get its invite link.' It covers the dual behavior of the tool well. It does not explicitly contrast with siblings like tg_invites or tg_create_group, so it loses the differentiation point for 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 tg_invites, tg_create_group, or tg_chat_edit. The description implies usage from its purpose, but it provides no explicit context, exclusions, or recommendations, so an agent must infer when this is the right 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 already mark this read-only/idempotent/non-destructive, and the description adds useful behavioral context: admin-rights dependency, the two result modes, and the revoked-link behavior. No annotation contradiction exists.

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

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

The main purpose is front-loaded, followed by a necessary permission warning and a compact Args block. Every sentence adds information; 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 still conveys what the caller will get: link usage counts, limits, expiry dates, other admins, joiners and timestamps. It also notes the revoked limitation, making the tool callable without guessing.

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 explain all parameters, and it does: chat formats, the conditional behavior of link, limit's meaning, and revoked's restriction to link lists. This fully compensates for 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?

The description opens with a specific verb+resource: retrieving invite links for a group/channel and the joiners per link. It is clearly distinct in action from siblings like tg_invite, but it never names an alternative or says what it is not, so it lacks explicit sibling differentiation.

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

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

It states a concrete prerequisite: admin rights are required and Telegram returns nothing without them. It also explains the two modes (with or without link param). It does not explicitly say when to prefer another tool, but the context is clear enough for invocation.

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 include destructiveHint=true and readOnlyHint=false, so the description adds value by specifying the irreversibility of delete=true for private chats and advising to ask first. This goes beyond the annotations by detailing the consequence and the appropriate social precaution. It does not contradict the annotations, so it is accurate and adds 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?

The description is two concise sentences. The first states the core action, and the second adds a crucial safety caveat. Every word earns its place, and the information is front-loaded with the purpose. There is no redundancy or fluff.

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 leave action with two parameters and no output schema, the description covers the main purpose, the destructive edge case, and a caution. It doesn't mention permissions or side effects beyond the delete flag, but those are not critical for a basic leave operation. The annotations cover destructive behavior, so the description is reasonably complete for an agent to invoke 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 explain parameters. It explains the delete flag's meaning (erases conversation, not recoverable) and the accompanying caution. However, the chat parameter is not described at all – its format (e.g., username, ID, phone) is left unspecified. Given two parameters, the description covers one partially and the other not at all, which is a moderate 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?

The description clearly states the primary action: 'Leave a group or channel.' It's specific about the resource and verb. However, it doesn't explicitly differentiate from sibling tools like tg_delete or tg_archive, which might also involve leaving or removing something. The purpose is clear but not contrasted with 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?

The description provides usage guidance for the delete flag: 'For a private chat, delete=true erases the conversation on your side and is not recoverable — ask first.' This is helpful contextual advice, but it does not explicitly state when to use this tool versus alternatives (e.g., tg_delete, tg_archive). There is no 'when not to use' or mention of alternative tools, so the usage guidance is incomplete.

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 read-only, non-destructive, and idempotent, so the description adds value by explaining the plain-vs.-premium ceiling behavior and the fact that the same action can fail at different points depending on account tier. It also discloses that the full response can get long, which is useful behavior context beyond the annotations.

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

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

The description is front-loaded with the core purpose and every sentence adds context, including usage guidance, an exclusion, and parameter semantics. It is slightly wordy around the motivating scenario, but not wasteful enough to drop to a 3.

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 one optional parameter and no output schema, the description gives enough to invoke correctly: what the tool returns, how the account tier affects results, when to pass `full`, and where related non-limit setup information lives. No critical operational detail is missing for this simple read-only tool.

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

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

Schema coverage is 0%, and the description fully compensates for the single parameter. It explains that `full` returns every default/premium pair and config keys, and gives explicit guidance on when to use it: only when hunting for a limit not in the curated list, because the answer gets long.

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 clearly identifies the tool as exposing account-level Telegram limits and the Premium flag, with examples of the kinds of limits covered. It does not use an explicit verb like 'returns' or 'lists,' and it distinguishes itself from tg_status but not from the potentially similar tg_capabilities, so it is clear but not fully differentiated.

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 tells the agent when to read this tool: before promising the owner something that may exceed account limits, instead of guessing or trying and failing. It also explicitly excludes local setup details and routes those to tg_status, giving a clear when-not-to-use and an alternative.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral detail: clear_mentions 'also clear the mention badge' and unread true 'flips it the other way,' showing the state changes the call will cause. There is no contradiction with the annotations.

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

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

The description is short and front-loaded: core behavior first, then a compact Args list. The reminder phrase is not filler – it explains why the unread mode is useful.

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

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

For a simple state-toggle tool with three scalar parameters and strong annotations, the description is complete enough to invoke correctly. It covers all argument forms and the main side-effect options; return-value details are not necessary for selection or 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%, but the Args section fully compensates by explaining all three parameters. chat accepts 'chat id, @username, exact title or "me"', clear_mentions is defined as clearing the mention badge, and unread is explained as flipping the chat to unread.

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

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

The first sentence states a concrete action and resource: 'Mark a chat as read, or put the unread mark back on it,' and the unread flag makes the two-way behavior explicit. It is clear, but it does not explicitly distinguish itself from sibling tools such as tg_unread or tg_status.

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 alternatives are mentioned and there is no explicit when-to-use or when-not-to-use guidance. The only usage context is the rationale for unread ('how the owner keeps a reminder to come back to it'), which is not enough to route an agent among 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?

Beyond the readOnly/idempotent annotations, the description discloses that the tool returns metadata rather than file content, supports pagination via before_id, and accepts multiple chat identifier formats. No behavior contradicts the annotations.

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

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

The description is compact and well organized: a one-sentence purpose, a returns-and-follow-up line, then a tight bullet-style Args list. Every sentence adds operational value; nothing is redundant or padded.

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

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

For a read-only listing tool with four simple parameters and no output schema, the description covers purpose, return fields, all parameter semantics, and how to continue the workflow with tg_download_many. Nothing needed to select or invoke the tool correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the burden, and it fully delivers: chat formats, the complete kind enumeration with the 'media' default, limit's meaning, and before_id's pagination behavior are all explained in the Args section.

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 opens by framing the tool as 'Attachments in a chat, the way Telegram's own media tabs work' and then explicitly says it returns message ids, file names, sizes, mime types, and durations. This clearly identifies the resource (chat attachments) and the operation (list/browse by kind), and it distinguishes the tool from tg_download_many by noting the download tool consumes these ids.

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 concrete workflow: use tg_download_many to fetch files after collecting ids from tg_media. It also sets the selection context by scoping the tool to media-tab-style browsing across kind categories, though it does not explicitly contrast it with tg_history or tg_search.

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 discloses important behavioral traits beyond the annotations: updates send messages to an external model (privacy impact), the dossier is written from untrusted text and must never be treated as instructions, and updates are incremental with first-call creation. No contradiction with annotations exists.

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

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

The description is well-structured into concept, usage guidance, warnings, and argument explanations. Each section earns its place; the privacy and trust warnings are especially valuable and the argument list is compact and readable.

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 description covers the use case, privacy implications, incremental update behavior, defaults, and parameter meanings. Minor gaps remain: the exact format of the chat identifier is vague, and the return shape of show/list is not stated, though it is largely inferable.

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%, but the description fully compensates by explaining every parameter: chat, action values with meanings, limit with default, and model override. This gives the agent enough to invoke the tool correctly without needing 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 clearly defines the tool as a per-chat dossier written by an LLM, and then enumerates the concrete actions (show, update, list) with their effects. This distinguishes it from related tools like tg_history or tg_summarize by emphasizing the persistent, incremental, LLM-written memory file.

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

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

The description explicitly says to read it before answering in an unfamiliar chat, and contrasts this with the cost of reading full history. It does not name sibling tools or state when not to use it, but the usage context is clear and actionable.

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

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

Annotations already declare readOnlyHint and idempotentHint, so no safety re-statement is needed. The description adds meaningful behavior: the unread semantics, the distinction between mentions and reactions, and the brief mode's effect of dropping reactions, link cards, and edit times for a smaller triage-oriented payload.

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 purpose is front-loaded in one clear sentence, followed by a compact Args block. Every sentence contributes information, with no filler or redundant restatement of schema defaults.

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 tool with three optional parameters and no output schema, the description covers the returned content, all parameter semantics, and the trade-off of brief mode. An agent has enough information to select and invoke this 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%, but the description fully compensates: limit is explained as how many to return, kind gets plain definitions for each value, and brief's behavior is concretely described. Every parameter has meaning 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 opens with a concrete result: unread messages that mention you or unread reactions to your messages. This clearly identifies the resource and distinguishes it from broader unread/activity siblings like tg_unread or tg_activity.

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 clearly implies when to use it: when you need unread mentions or unseen reactions, with the kind parameter selecting which. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to route correctly.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description productively focuses on content-level behavior. It discloses a genuinely surprising edge case: poll messages get a 'votes' block with counts and your own vote, a public poll additionally lists who voted for what, and an anonymous poll shows no voter list at all — not even to the author. This kind of conditional behavior is exactly what an agent needs to anticipate. It stops short of describing response shape or error behavior, but the behavioral specifics provided are strong.

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 summary line is front-loaded and information-dense, the poll paragraph adds an important conditional behavior in just two sentences, and the Args list is compact and scannable. There is no filler or repetition of what the schema already states.

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 read tool with no output schema, the description documents every parameter, the core payload, and the poll edge case that would otherwise surprise an agent. The main gap is the concrete shape of the returned message object (field names and nesting), which the absence of an output schema leaves unstated. Still, an agent has everything needed to invoke it correctly in the common and poll cases.

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 Args block carries the entire parameter-documentation burden — and it fully delivers. chat is explained as accepting 'chat id, @username, exact title or "me"', context is glossed as 'also return this many messages before and after it', replies as 'also return this many replies to it (threads/comments)', and message_id as 'the message to inspect'. Every one of the four parameters receives meaning the bare schema lacks.

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

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

The opening line, 'One message in full: reactions, inline buttons, how many people read it, plus optional surrounding context and its reply thread,' names the exact resource (a single message) and its distinguishing payload. The 'one message' scope sets it apart from list-style siblings like tg_history or tg_view, and the explicit mention of context and reply thread reinforces that this is a deep read of a single message, not a listing tool. A verb is implied rather than stated, but the purpose is unambiguous and clearly differentiated.

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

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

The description conveys its use case implicitly — reach for it when you need full detail of one message (reactions, buttons, read counts, poll vote breakdown) with optional surrounding context or thread replies. However, it never states when not to use it or names any alternative tool for simpler message reads, and none of the many siblings is referenced for routing. An agent must infer applicability from the feature list rather than being told.

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 mutation risk is known. The description adds valuable behavioral context beyond annotations: admin permission is required, actions are visible to the entire chat, and approve/decline answer pending join requests. No contradiction with 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 tight sentences: the first front-loads the verb, resource, and action list; the second clarifies join-request behavior; the third covers permission and visibility. Every sentence carries necessary information and there is 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 simple three-parameter tool, the description covers the essential operational context: the complete action vocabulary, the admin requirement, and a visible side-effect warning. It lacks explicit chat/user identifier formats and return-value information, but these are relatively minor given the clarity of the action model and the annotations.

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%: chat, user, and action are bare strings with no descriptions or enums. The description compensates partially by listing valid action values and explaining two of them, but it never defines what chat or user should contain (ID, username, display name) or their formats. Meaningful but incomplete parameter guidance.

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 opens with a specific verb and resource ('Moderate a group member') and immediately enumerates the full action set: kick, ban, unban, promote, demote, approve, decline. This clearly distinguishes it from siblings like tg_block, tg_delete, and tg_leave, and the extra sentence explaining approve/decline removes ambiguity about join-request handling.

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 clear prerequisite ('Only for chats where the user is an admin') and a practical usage caution ('Confirm before using — kicking and banning are visible to the whole chat'). It does not explicitly name alternative tools or state when not to use this tool, which keeps it just 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 establish that the tool is non-read-only, non-destructive, and idempotent. The description adds meaningful behavioral context: the default mute duration is indefinite, and the same action can unmute via a boolean switch. It also implies reversibility through the unmute option, which is helpful beyond the raw 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?

A single, front-loaded sentence captures the full action, the optional duration, the default, and the inverse operation. Every clause earns its place, and there is no padding or repetition.

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 three-parameter tool with annotations and no output schema, the description covers the core behavior and parameter semantics well. The only minor gap is not specifying how 'chat' should be passed, but the required chat field and the resource name make this a small omission rather than a blocking one.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It does clarify that hours is a duration in hours and that the default is indefinite, and that unmute toggles the mute state. However, the required 'chat' parameter is left without any format or type guidance, so coverage is partial.

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?

Description uses a specific verb-resource pair: 'Mute a chat', with a clear optional duration and an explicit unmute branch. This distinguishes it from sibling tools like tg_block or tg_alert, even without naming them, because the action and resource are 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 about when to choose this tool over alternatives such as tg_block, tg_alert, or tg_notify. The description only states the action and parameter behavior; it does not specify preconditions, exclusions, or comparison with other chat-moderation tools.

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

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

Annotations already cover idempotency and non-read-only status, and the description adds useful behavioral detail: no arguments reports defaults, 'exceptions' lists chats with differing settings, and 'hours' changes silence from indefinite to time-limited. It does not describe return format, but the annotations reduce the burden on the description.

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

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

The description is front-loaded with the core purpose and then organized by usage context and an Args section. Despite being long, every sentence earns its place because it supplies meaning the schema lacks.

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 description covers all parameter semantics, the no-argument default behavior, and how this tool relates to tg_mute. It leaves minor gaps around parameter interactions (e.g., whether chat and scope can be combined) and exact return shapes, but overall it gives an agent enough to use 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%, and the description fully compensates by explaining every parameter with concrete meaning: mute, hours, sound, previews, stories, scope, chat, and exceptions. This goes well beyond the bare types in 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 opens with 'Read or change notification settings — for one chat or a whole category', stating a specific verb, resource, and scope. It also differentiates itself from tg_mute by explaining that tg_mute is the shortcut for silencing one chat while tg_notify handles everything else.

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 names tg_mute as the alternative and gives clear conditions for choosing this tool: 'turning a whole category off, controlling sound, message previews and story notifications, and finding chats whose settings differ from the default.' It also explains the no-arguments case for reading account defaults.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the bar is lower here. The description adds valuable behavioral context by specifying exactly which member attributes are returned, including the conditional 'phone when visible' and role variations like owner/admin/custom rank. It does not disclose pagination or error behavior, but the annotations cover the safety profile adequately.

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

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

The description is front-loaded with the core result summary and the most important member fields, followed by a compact Args list. Every sentence adds value; there is no filler. Minor redundancy between 'Members of a group or channel' and the chat parameter explanation, but overall it is tightly structured.

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 tool with no output schema, the description does a good job conveying both the return content and the input formats. It lists the member fields, the accepted chat identifier forms, the limit semantics, and the query filter. It does not specify the exact return shape (e.g., list vs. object) or explain requiredness/defaults, but the essential calling contract is clear enough for an agent to use it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It explains all three parameters: chat accepts id, @username, or exact title; limit controls how many members; query filters by name or username. This goes beyond the bare schema, though it omits details like the default limit value and any bounds or case-sensitivity behavior.

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 clearly identifies the resource being accessed (members of a group or channel) and enumerates the specific data returned (username, direct chat link, phone when visible, role, last-seen, bot/premium flags). It is distinguishable from siblings like tg_person and tg_contacts, though it does not name them explicitly. A slightly stronger explicit verb like 'list' or 'retrieve' would make it a 5.

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

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

The description implies when to use this tool: when you need members of a group or channel and their reach/contact details. It does not contrast with alternatives such as tg_person, tg_contacts, or tg_chat_info, nor does it state when not to use it. The parameter guidance (chat, limit, query) gives practical usage context but no explicit selection rules.

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 read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those flags: ordering is oldest first, messages read but not answered are still counted, bots are excluded by default, and the archived parameter has a tri-state behavior. No contradictions with the annotations exist.

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

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

The description is front-loaded with the core concept, immediately distinguishes the tool from tg_unread, and then organizes parameter explanations clearly under an 'Args' section. Every sentence adds information, and the length is justified by the number of nuanced parameters.

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

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

Given the complexity of the six parameters and the absence of an output schema, the description is complete for tool selection and invocation. It explains defaults, exclusions, ordering, direction semantics, and the effect of each argument, leaving no critical gap for an agent to call tg_pending 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?

With 0% schema description coverage, the description carries the full burden of explaining all six parameters, and it does so thoroughly. Each parameter gets a plain-language explanation, default behavior, allowed values for direction and kind, and the semantic meaning of archived as a tri-state. This goes far beyond what the raw schema provides.

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

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

The description clearly defines the tool's purpose: listing chats with messages awaiting a reply, with a specific distinction between 'waiting on you' and 'owed to you'. It explicitly differentiates itself from tg_unread by noting that opened-but-forgotten chats remain pending, so an agent can tell exactly what tg_pending returns.

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 provides explicit usage guidance by contrasting with tg_unread ('this survives the chat being opened') and by detailing exclusions for broadcast channels and Saved Messages. It also explains how the kind parameter overrides these default exclusions, giving clear conditions for when to use this tool versus 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 already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so safety is covered structurally. The description adds genuinely new behavioral context beyond annotations: the MTProto global-search limitation scoping author search to private chats, and the semantic effects of messages=0 (drops texts but keeps counters) and chats=0 (skips the lookup). This is valuable disclosure an agent would not otherwise know.

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

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

Front-loaded with purpose and usage before descending into detail, with the 'Limit worth knowing' warning clearly separated. The returns enumeration is long, but that length is justified for a tool consolidating four siblings and no output schema exists to carry that burden. Every sentence earns its place; only minor tightening of the profile-fields list is possible.

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

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

With no output schema, the description compensates by enumerating return categories thoroughly. Parameters, limitations, alternative tools, and 0-value semantics are all covered. The only minor gap is expected behavior for unresolvable user inputs, but for a read-only aggregation tool with complete param docs and annotations, nothing critical 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 description carries the full burden — and it succeeds completely. user is expanded to 'user id, @username, t.me link, exact name, or "me"', messages and chats each explain their 0-value behavior, and brief quantifies its effect ('same messages, about a quarter smaller'). Every one of the 4 parameters receives meaning the bare schema types do not convey.

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

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

The description opens with 'Everything the account knows about one person, in a single call,' naming the exact resource (one person) and precise scope (aggregated account knowledge). It differentiates from siblings by explicitly stating it replaces chaining tg_chat_info, tg_contacts, tg_common_chats and tg_history, and it enumerates concrete return categories (profile, flags, shared groups, ranking, last messages). An agent cannot confuse this with any of the 70+ siblings.

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

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

Gives explicit when-to-use guidance: 'Use this before writing to someone instead of chaining...' It also provides a when-not-to-use case with the MTProto limitation ('no global search by author... for what they wrote in a shared group, call tg_history(chat=<group>, from_user=<person>)'), naming the exact alternative and its parameters. Nothing is left to inference.

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

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

Annotations already establish that the tool is mutating, idempotent, and non-destructive. The description adds the 'top of the list' behavior and the unpin capability, but does not disclose additional behavioral context such as whether pinning displaces other pinned chats, permission requirements, or effects on list ordering beyond the basic statement.

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 a single, front-loaded sentence with no filler. Every word contributes to understanding the core operation, and it is appropriately compact for a tool with only two simple parameters.

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

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

For a simple pin/unpin action, the description conveys the core operation and the annotations cover safety and idempotence. However, it lacks any disambiguation from tg_pin_message and provides no detail about the 'chat' parameter format, which an agent needs to invoke the tool correctly in a realistic context.

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 for the undocumented parameters. It indirectly explains the unpin boolean through 'or unpin it,' but it does not clarify the expected format or identity semantics for the required 'chat' parameter, nor does it explain the default behavior of unpin when omitted.

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 uses a specific verb and resource: 'Pin a chat to the top of the list, or unpin it.' It clearly distinguishes this tool from the sibling tg_pin_message by specifying 'chat' rather than 'message,' so an agent can tell them apart 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?

There is no guidance about when to use this tool versus alternatives such as tg_pin_message, tg_archive, or tg_mute. The operation is stated, but no context is provided about prerequisites, exclusions, or which sibling tool should be used for pinning messages instead of chats.

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 convey mutation (readOnlyHint=false), idempotency, and non-destructiveness. The description adds useful context about operating inside a chat and unpinning, but does not disclose side effects like whether notify controls a service message or whether pinning replaces an existing pinned message. No contradiction with annotations.

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

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

Two sentences, no fluff. The core operation is front-loaded, and the differentiator from tg_pin is stated in a compact second sentence. Every word 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?

The description is sufficient for choosing the tool and understanding its high-level behavior, and annotations cover safety traits. However, for actually invoking it correctly, important parameter semantics like unpin and notify are left to inference, and no guidance is given on what happens to previously pinned messages.

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 input schema has no descriptions for any parameter, so schema_description_coverage is very low. The description does not explain chat format, how message_id is used, or the semantics of unpin and notify. Parameter names and defaults provide only minimal clues, so the tool description fails to compensate for the schema 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?

The description begins with a clear, specific verb and resource: 'Pin (or unpin) one message inside a chat.' It also explicitly differentiates this tool from tg_pin by noting tg_pin pins the whole chat, making the tool's scope 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?

The description names the sibling tool tg_pin and gives the exact difference: message-level pinning here vs chat-level pinning there. This tells an agent when to choose this tool over the most likely alternative.

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

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

Annotations already signal a non-read-only, non-idempotent mutation, so the description does not need to restate that. It adds useful behavioral context: the platform rejects private-chat polls, and anonymous=false modifies vote visibility. No contradiction with annotations.

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

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

Two lead sentences then a compact Args block. No fluff, each line adds meaning, and the most important scope constraint appears up front.

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 6-parameter tool with no output schema and sparse annotations, the description defines the operation, every parameter, and a critical platform limitation. It omits minor constraints (e.g., range of quiz_answer, mutual exclusivity with multiple), but these are inferable or edge-case. Substantially 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 has 0% description coverage, so the description carries the burden. It glosses all six parameters, adding semantic layers: chat restricted to group/channel, multiple allows several answers, quiz_answer turns it into a quiz, anonymous=false reveals voter identities. Some constraints such as quiz_answer's valid range are left implicit, but the coverage is adequate.

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

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

The description opens with a specific verb and resource: 'Post a poll (2-10 options)'. This clearly distinguishes it from generic messaging siblings like tg_send and tg_send_file. The platform constraint about private chats further characterizes the tool's scope.

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 includes an explicit platform constraint: 'Telegram refuses polls in private chats', which tells the agent not to use the tool for private chats and implies group/channel usage. It does not name alternative sibling tools for general messages, so it stops short of full when-to-use 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 mark the tool as mutating, idempotent, and non-destructive; the description adds real behavioral context on top of that: omitting `emoji` removes the reaction, and unsupported emoji/list attempts are refused before chat lookup. No contradiction with the annotations is present.

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: the core action and removal behavior come first, followed by a separate, focused caveat about Premium. Every sentence earns its place and there is no filler or restatement of the schema.

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

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

For a 4-parameter mutation tool with no output schema, the description covers the primary action and the most important `emoji` edge cases, while annotations cover idempotency and safety. Still, it omits `big` semantics, chat/message_id format expectations, and return/error behavior beyond the Premium refusal, leaving small but real 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?

With 0% schema description coverage, the description supplies useful meaning for `emoji`: optional, removal on omission, custom-emoji IDs/lists require Premium, and exactly one plain emoji otherwise. However, `big` is left unexplained and the exact input format for a 'list of several reactions' is not defined, so it does not fully compensate for the missing schema descriptions.

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

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

The first sentence states a specific verb ('React'), a specific resource ('a message'), and the mechanism ('with an emoji'), and immediately clarifies the alternative mode of removing a reaction by omitting `emoji`. This makes the tool's purpose unmistakable and distinguishes it from siblings like tg_send, tg_send_sticker, and tg_pin_message.

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

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

It explicitly describes two usage modes: adding a reaction and removing one by omitting `emoji`. It also gives a clear constraint about when calls are refused, namely custom-emoji IDs or multiple reactions without a Premium subscription. However, it does not name sibling tools or provide when-not-to-use guidance, so it falls short of full routing.

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

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

Beyond the annotations, it discloses that the reminder is stored on disk, survives restarts, never sends anything to anyone but the owner, and self-cancels when an incoming message arrives. This is rich behavioral context about persistence, privacy, and cancellation that annotations alone 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?

The description is compact yet fully informative: a one-sentence purpose, two clarifying examples, the key distinction from tg_wait, and a structured Args section. Every sentence adds meaning, and the most important behavioral facts are front-loaded.

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

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

For a tool with six parameters, no output schema, and subtle reminder semantics, the description covers purpose, timing formats, cancellation, persistence, ownership, and the list/cancel modes. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it succeeds: text, when (with format examples), chat, unless_reply, list, and cancel are all explained in plain language. It even includes required-conditional information for chat and explains that cancel uses ids returned by list.

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 opens with a specific verb-resource statement: 'Remind the owner later, through the agent's bot, optionally only if nobody replied.' It names the exact use cases with examples and explicitly distinguishes itself from tg_wait, saying it does not block and is not capped at ten minutes.

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 concrete scenarios ('remind me in two hours if Lena hasn't answered'), explains when to choose it over tg_wait, and clarifies the cancellation behavior for unless_reply. This lets an agent decide when to use this tool versus a sibling without ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description goes well beyond them by detailing what different link types return, how phone numbers with a plus are handled, how bare digits are interpreted as ids, and that non-Telegram URLs are merely reported as external rather than fetched.

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 appropriately detailed for the variety of accepted inputs, but every sentence earns its place. The one-line summary is front-loaded, and the subsequent paragraphs categorize inputs and behaviors clearly without padding 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 a single parameter, no output schema, and rich annotations, the description covers all essential context: what the input can be, what the tool returns for each major link type, how phone numbers are treated, and how external URLs should be handled. An agent can invoke this tool correctly with no additional information.

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 schema provides no description for the single `link` parameter, so the description must carry full semantic weight. It comprehensively defines accepted formats: t.me usernames, invite hashes, joinchat links, message links, addstickers links, phone numbers with a plus, bare digit ids, and non-Telegram URLs.

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 starts with a clear, specific statement of what the tool does: it resolves what a Telegram link or phone number points to, without side effects. It enumerates the exact link formats handled, distinguishing it from action-oriented siblings like tg_click, tg_join, or tg_send.

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 clearly implies when to use this tool (for resolving links/phone numbers) and explicitly excludes non-Telegram URLs by instructing to use a web tool only if the user asked. It does not name sibling Telegram tools as alternatives for actions like opening or joining, but the 'without opening, joining or saving anything' phrasing provides useful 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?

Even with annotations present (idempotentHint=true, destructiveHint=false), the description adds high-value behavioral context: it explains merge/patch semantics, that digest_at and auto run in a daemon without Claude, that filter actions are safe and reversible, that save only writes to Saved Messages, and that a rule suppresses alerts unless alert:true. This exceeds what the annotations alone reveal.

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 long but information-dense and well organized: the simple rule keys come first, then automation keys, safety constraints, and exclusions. Every sentence adds necessary behavior or semantics, and the pointer to docs/configuration.md keeps it from growing even longer.

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 complex patch tool with no output schema, the description covers the input surface almost completely — key names, types, merge behavior, safety, and restrictions. It does not state what the call returns or how invalid patches are handled, but the detailed key semantics plus docs reference make it sufficient for correct invocation.

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

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

The schema is nearly empty (a single patch object with additionalProperties true), so the description carries the entire parameter burden. It lists all valid keys with their value shapes, nested structure for digest_at and auto, and explicitly rejects confirm_* keys. This fully compensates for 0% schema description coverage.

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

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

The description opens with a specific verb and resource — 'Update alert rules' — and then enumerates the keys it manages, including the automation-only digest_at and auto. It also distinguishes itself from tg_status by telling the agent to call that sibling first, and clarifies that confirm_* keys are not handled here.

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 workflow: call tg_status first because tg_rules merges onto current values. It also names an exclusion — confirm_* keys are rejected and must be edited by hand in data/rules.json — which tells the agent when not to use this 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 already cover safety (readOnlyHint, idempotentHint, destructiveHint=false). The description adds useful behavioral context beyond the annotations: it returns aggregated counts per tag and explains how the results plug into tg_search. It does not mention ordering or pagination, but for a zero-parameter read-only tool this is acceptable.

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, each earning its place: the first defines the output, the second gives an actionable next step. No filler, no redundancy, and the essential information is front-loaded.

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

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

For a simple read-only tool with no parameters, the description is complete: it states what is returned (tags and per-tag message counts) and how to continue the workflow with tg_search. No output schema is present, but the description sufficiently explains the result shape.

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