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

Annotations already declare readOnly, idempotent, non-destructive, and openWorldHint=false, so the safety profile is covered. The description reinforces and adds value by stating it 'operates entirely offline without Telegram API calls,' which is useful behavioral context for a cache tool, though it does lean on what openWorldHint already implies.

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 compact sentences, front-loaded with what is inspected before the usage hint and the offline note. Efficient, with only mild redundancy between the offline sentence and the openWorldHint annotation.

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?

An output schema exists, so the description need not explain return values, and it correctly focuses on purpose, scope, and usage. For a zero-parameter read-only diagnostic with full annotation coverage, this is complete enough to invoke correctly, with the only minor gap being the absence of any note on how failure/degraded states are surfaced.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the schema or description to document beyond the empty args object.

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 ('Inspect') and resource ('local SQLite/FTS5 archive') plus the concrete outputs it surfaces: integrity, database size, and active tool tier diagnostics. An agent can tell it apart from cache-related siblings like search_cached_messages and sync_chat_cache, though it doesn't name them directly.

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

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

'Use to verify cache readiness before running local searches' gives a clear when-to-use condition that routes the agent to this tool ahead of a search. There is no explicit when-not guidance or named alternative, but the operative context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description's 'Read-only operation' merely restates that, and it adds no extra behavioral detail such as pagination or account fan-out behavior for a read tool.

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

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

Three short sentences with the purpose front-loaded and zero filler. The final 'Read-only operation' sentence is largely redundant against the readOnlyHint annotation, which slightly weakens the economy.

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

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

For a simple read tool with an output schema, rich annotations, and 100% parameter coverage, the description supplies purpose, use case, and safety context. It does not mention the multi-account fan-out behavior described in the schema, but that gap is minor.

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

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

Schema description coverage is 100%, so both chat_id and account are already fully documented in the schema, including accepted identifier formats and multi-account fan-out. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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

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

The description states a specific verb and resource ('List all administrators and their permissions') plus the scope ('in a group or channel'). This is unambiguous and clearly distinct from the nearest sibling, get_banned_users.

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

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

'Use when verifying group moderation staff' gives a concrete triggering context for the tool. It stops short of naming alternatives or stating when not to use it, but the guidance is clear.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, idempotentHint, openWorldHint), lowering the bar. The description still adds meaningful behavioral context beyond them: the admin-permission requirement and the fact that restriction reasons are returned.

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

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

Three tight sentences with the core purpose front-loaded, then the usage trigger, then the prerequisite. No filler, though the prerequisite could arguably be merged.

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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies purpose, usage context, and the admin prerequisite, leaving little an agent needs missing.

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

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

Schema description coverage is 100% and both parameters (account, chat_id) are thoroughly documented in the schema. The description adds no syntax or format details for either parameter, so the baseline 3 applies.

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

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

States a specific verb ("List") and resource ("banned and restricted members in a group or supergroup") with the additional detail of returning restriction reasons. The resource is inherently distinct from the closest sibling, get_admins, but the description does not explicitly differentiate itself from it.

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 a clear trigger ("Use when auditing group moderation") and a prerequisite ("Requires admin permission in the target group"). It does not state when-not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds nothing about rate limits, freshness of the command list, or output shape. With an output schema present and annotations complete, only modest added value here.

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

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

Two short sentences, front-loaded with the primary action, then the trigger and the alternative. No filler; every clause earns its place.

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

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

For a two-parameter read tool with full schema coverage, complete annotations, and an output schema, the description covers purpose, trigger, and the nearest sibling. Minor gap: it does not mention that the command list reflects what the bot advertises (not necessarily what the caller can invoke), but that is a small 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 100%, so both parameters (account, bot_username) are already documented in the schema with examples and multi-account semantics. The description adds no parameter-level syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Inspect) and enumerates the resources returned (profile, command list, description, capabilities) scoped to 'a specified bot'. Clearly distinguishable from lookalikes like get_me/get_user_status, which target users rather than bots.

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

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

Explicitly names the trigger ('Use when discovering bot commands') and names the side-effecting alternative with the opposite intent ('To update bot commands, use set_bot_commands'). 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the agent knows this is a safe, repeatable read. The description adds the returned field set but no additional behavioral context such as caching, permissions, or error behavior. With annotations covering the safety profile, this is adequate but not rich.

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

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

Two sentences, no filler, and the primary purpose plus scoping constraint is front-loaded before the sibling pointer. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the description still names the key fields. Combined with 100% parameter coverage and clear annotations, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both chat_id and account are fully documented in the schema. The description's 'chat ID or @username' phrasing mirrors the schema rather than adding format or constraint details beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Retrieve) and resource (chat metadata) and enumerates the fields returned (title, member count, type). It explicitly distinguishes itself from the sibling get_full_chat, so an agent can route without opening either schema.

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

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

Explicitly states when to use it ('inspecting a known chat ID or @username') and names the alternative plus its selecting condition ('for full administrative settings and invite links, use get_full_chat'). This is exactly the when/when-not/alternative structure.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description's 'Read-only operation' merely restates the annotation, and the return-content note ('last message and unread count') overlaps with the existing output schema. It adds little behavioral context beyond annotations, so a baseline 3 is appropriate.

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

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

Three tight sentences that front-load the resource and scope before the routing note. The final 'Read-only operation' sentence is redundant with the readOnlyHint annotation and is the only wasted text.

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

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

Given the output schema exists, the description needn't explain return values, and it correctly covers purpose, scope, and sibling routing. It is essentially complete for a read-only list tool, with only minor redundancy rather than a substantive gap.

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

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

Schema description coverage is 100% with all three parameters (page, account, page_size) fully documented in the schema itself, including the multi-account fan-out behavior. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('retrieve active dialogs and recent conversation summaries') and immediately differentiates itself from the sibling list_chats for comprehensive listing. An agent can distinguish it from list_chats, get_chat, and get_full_chat without opening any schema.

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

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

Gives explicit context ('Use for overview of recent chat activity') and names the alternative tool with the condition that selects it ('To search or list all chats comprehensively, use `list_chats`'). This is the when/when-not/alternative pattern done well.

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 destructiveHint=false, so 'Read-only operation' merely restates structured data and earns no credit. The description adds nothing beyond that – no pagination behavior, result ordering, or account fan-out caveats.

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

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

Three short sentences with the purpose front-loaded and no filler. Slightly tighter than needed – the final 'Read-only operation' sentence is redundant given annotations.

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

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

A simple two-parameter read tool with a full output schema, so return values need no explanation. Purpose, scope, and usage context are all present; only the account fan-out nuance and any result-size limits are left entirely to the schema.

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

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

Schema description coverage is 100%: the schema fully documents both contact_id (numeric Telegram user ID) and account (multi-account fan-out behavior). The description's mention of 'a specific contact ID' adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Find') and a precisely scoped resource: groups and channels shared between the account and a contact. This scope naturally separates it from siblings like get_chats (all chats) and list_contacts, though no sibling is named explicitly.

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

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

'Use when inspecting mutual group memberships' gives a clear usage context, but there are no exclusions and no pointers to alternatives such as get_chats or get_full_chat when the agent wants a broader view. Adequate but minimal.

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 destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the 'lightweight' payload characterization and the address-book scope, which is modest additional context. It says nothing about ordering, pagination, or how the account fan-out behaves for reads in multi-mode.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the routing hint to list_contacts last. 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. For a one-parameter read-only lookup, nothing an agent needs in order to call it correctly is missing.

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

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

There is a single optional parameter and schema description coverage is 100%, with the account/fan-out semantics fully spelled out in the schema itself. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve a lightweight list of all Telegram user IDs') and scopes it to the address book. It explicitly names the sibling it is not (list_contacts) and the difference in payload weight, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit trigger ('Use when checking if a user ID is an existing contact') plus a named alternative with the condition that selects it ('For full contact profiles, use list_contacts'). Both the when and the when-not are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is fully covered without description help. The description adds only scope information ('all chats and channels'), saying nothing about pagination, ordering, or what an empty/missing folder returns.

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

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

Two short sentences, no redundancy, with the core purpose front-loaded and the routing hint second. Every sentence earns its place.

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

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

A read-only lookup with an output schema (so return values need not be described), full parameter coverage, and annotations covering safety. The remaining gap is only the absence of pagination/ordering notes, which is minor for this simple tool.

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

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

Schema description coverage is 100%: folder_id and account are both documented in the schema (folder_id as the Telegram dialog filter identifier, account for multi-account behavior). The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: retrieving the chats and channels contained in a given dialog folder ID. The title ('Get Chats Inside Specific Folder') usefully corrects the potentially misleading name 'get_folder', which could otherwise be read as fetching folder metadata itself.

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

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

It gives a usage cue ('Use when navigating folder contents') and explicitly routes to the alternative for a related need ('To list available folders, use list_folders'). There is no when-not guidance (e.g., single-chat lookup vs get_chat), but the key sibling boundary is drawn.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds an inventory of what is returned, which is useful scope context, but says nothing about rate limits, auth requirements, or per-account fan-out behavior that the annotations do not already imply.

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 tightly written sentences with no filler; the capability statement comes first, then usage scope, then the sibling routing hint in a natural priority order.

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 full input schema, rich annotations, and an output schema present, the definition covers what an agent needs to select and call the tool. The only thing not addressed is any behavioral caveat for the multi-account fan-out hinted at in the schema, but nothing essential is missing.

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

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

Schema description coverage is 100% for both parameters, including the accepted chat_id formats and the multi-account behavior of the optional account parameter, so the schema already carries the full burden. The description contributes no additional parameter meaning, making the baseline of 3 appropriate.

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

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

The description names a specific verb (Retrieve) and resource (complete chat information), then enumerates the concrete payload: description/about, admin rights, notification settings, and invite links. It explicitly contrasts itself with the sibling get_chat, so an agent can distinguish the two without opening either schema.

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

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

It states the selecting condition ('Use when needing deep metadata') and names the alternative with its own condition ('For basic title and type, prefer the lighter get_chat'). This is an explicit when-to-use / when-to-use-something-else routing 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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so "Read-only operation" merely repeats structured data. The description adds the ordering guarantee ("chronological") and limit-bounded behavior, which is mild extra context but no statement of return shape, pagination, or behavior on a missing/unresolvable chat.

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

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

Three short sentences, front-loaded with the core action and scope, with no filler. Slightly terse for a tool in such a crowded namespace, but nothing 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?

An output schema exists so return values needn't be explained, and annotations carry the safety profile. The description covers purpose, use case, and limit scoping adequately; the main omission is any differentiation from the many similar message-retrieval siblings.

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

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

Schema description coverage is 100%, so the schema already documents limit, account, and chat_id semantics thoroughly. The description only echoes the limit cap ("up to the configured limit") and adds nothing about ordering, defaults, or multi-account fan-out beyond what the schema states; baseline 3 applies.

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

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

The description states a specific verb and resource (retrieve complete chronological message history from a chat) with scope (up to the configured limit). However, it makes no attempt to distinguish itself from near-duplicate siblings such as get_messages, list_messages, and get_full_chat, leaving the agent to guess which history-retrieval tool to pick.

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

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

"Use when ingesting or summarizing a conversation" provides a genuine use context, but there are no exclusions and no reference to the many sibling tools (get_messages, list_messages, search_messages) that appear to overlap heavily. When-to-use is implied rather than fully clarified.

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 destructiveHint=false, and the description's 'Read-only operation' merely restates that. It does disclose what is returned (timestamp and summary of the most recent interaction), but adds little behavioral context 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?

Three short, front-loaded sentences that state purpose, usage, and safety. The final sentence is redundant with the readOnlyHint annotation and could be dropped, but the description is otherwise tight.

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

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

With a full output schema, complete parameter documentation, and rich annotations, the description only needs to convey purpose and when-to-use, both of which it covers. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (account and contact_id) are already fully documented in the schema. The description adds no additional parameter meaning, which is the baseline when the schema does the heavy lifting.

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

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

States a specific verb (Get) and resource (timestamp and summary of the most recent interaction with a contact). It clearly separates itself from siblings like get_messages, get_history, and get_user_status by scoping to the single most recent interaction.

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

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

Explicitly states the use case: 'Use to check communication recency before initiating contact.' This gives clear context for when to reach for it, though it names no alternative tool for related queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description adds the returned field list, which partly duplicates the output schema and provides little behavioral context beyond the annotations.

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

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

Two front-loaded sentences with zero filler: the first gives purpose and return fields, the second gives usage and the sibling alternative. Every clause earns its place.

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

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

With an output schema documenting return values and annotations covering the safety profile, the description only needs to convey purpose, usage, and routing – all of which are present. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the single `account` parameter and its multi-account fan-out semantics are fully documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Retrieve) and resource (profile identity of the current Telegram user account) and enumerates the exact returned fields (ID, name, username, phone). It also distinguishes itself from the sibling list_accounts by scoping to the current account rather than all configured accounts.

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

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

Explicitly names the triggering scenario ('verifying account identity or permissions') and routes the agent to the alternative tool (`list_accounts`) with the condition that selects it. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about its role as a pre-download verification step, though it does not describe behavior when a message has no media or when the account is unresolvable.

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

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

Three short sentences, zero waste, and front-loaded with the capability before the sequencing advice. Every sentence earns its place: what it returns, when to use it, and what to use instead.

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?

An output schema exists, so return-value documentation is unnecessary, and annotations cover the safety profile. With 100% parameter coverage and an explicit sibling hand-off, an agent has everything needed 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 100%, so chat_id, message_id, and the optional account parameter are fully documented in the schema itself. The description adds no format or constraint detail beyond what the schema provides, which is the baseline for high-coverage schemas.

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 (inspect) and resource (media metadata attached to a message), and enumerates the exact fields returned (size, dimensions, mime type, duration). It clearly distinguishes itself from the sibling that performs the actual download.

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 prescribes the usage sequence ('Use before downloading to verify file attributes') and names the alternative tool ('To download the actual file, use `download_media`'). The when-to-use condition and the hand-off target are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the 'Read-only operation' sentence adds nothing new and is effectively a restatement. The description does disclose the symmetric before/after window behavior, but omits any note on prerequisites (cached chat, valid message ID) or fan-out semantics. Adequate but thin against an annotation-rich tool.

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

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

Three short sentences with purpose, usage and safety front-loaded in that order. The trailing 'Read-only operation' duplicates the annotation and is mildly wasteful, but overall it is tight.

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

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

With a 100%-covered schema and an output schema present, the description need not explain parameters or return values. It covers what it is and when to use it, leaving only minor behavioral gaps (prerequisites, multi-account fan-out) unstated.

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

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

Schema description coverage is 100%, so chat_id, message_id, context_size and account are all documented in the schema. The description only alludes to 'target message ID' and the 'surrounding window', adding no syntax, format or default detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (a surrounding window of messages before and after a target message ID in a chat), which cleanly distinguishes it from the many list/search siblings like get_messages and list_messages. It does not, however, name any sibling explicitly to sharpen that boundary, 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?

Provides a clear usage condition: 'Use when understanding conversational context around a specific event or quote.' That tells the agent when this tool is the right pick over a plain history fetch, but it names no alternatives and gives no exclusions, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds only that results are sequential/paginated, which the schema also conveys; it says nothing about ordering, rate limits, or multi-account fan-out behavior (that detail lives only in the schema).

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

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

Three tight sentences, front-loaded with purpose before the routing guidance, with no padding. The only blemish is the mildly misleading 'offset or limit' clause, which costs it a perfect score.

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 full output schema, complete parameter descriptions and rich annotations, the description only needs to cover purpose and tool selection, which it does. Ordering semantics and multi-account behavior are left implicit, but those are adequately covered elsewhere.

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

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

Schema description coverage is 100%, so page, page_size, account and chat_id are all well documented in structured data; baseline is 3. The description contributes no additional parameter meaning and its 'offset or limit' phrasing does not match the actual page-based 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?

States a specific verb and resource ('retrieve paginated messages from a specific chat') and distinguishes itself from siblings by naming list_messages and search_messages. The phrase 'starting from an offset or limit' is slightly imprecise since the schema actually exposes page/page_size, not offset/limit, which mildly blurs what the tool does.

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

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

Explicitly states the selection condition ('Use for sequential message retrieval') and routes the agent to the correct alternative for two distinct cases: filtering by sender/date goes to list_messages, text search goes to search_messages. 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds a useful behavioral detail (produces a collage without downloading each item), but says nothing about return format, size, or rate behavior.

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

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

Two tight sentences, front-loaded with what the tool does and followed by the reason to pick it. No redundancy or filler.

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

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

For a read-only tool with no output schema, the description conveys the essential output (a visual contact sheet) and the rationale. It is nearly complete; a note on the returned image format or pagination would close the remaining gap, but 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 100%, so every parameter (limit, source, account, chat_id, columns) is already documented in the schema. The description adds no syntax, format, or default details beyond that, so the baseline of 3 applies.

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

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

States a specific verb (Generate) and resource (visual contact sheet collage of recent photos from a chat), which is clearly distinct from list_photos or open_photo by emphasizing the composited overview rather than individual retrieval. It doesn't explicitly name a sibling alternate, but the operation is unambiguous from the text alone.

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 a use case ('quick visual overviews of shared imagery without downloading each item individually'), which implies when it beats per-item tools. However, it never names list_photos or open_photo as alternatives or states exclusions, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond the read operation itself, such as ordering, result limits, or what happens in multi-account mode. Adequate but adds little beyond the annotations.

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

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

Three short sentences, front-loaded with the core action, followed by a usage cue and the alternatives. No filler, no repetition of the title.

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

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

For a simple read tool with an output schema, full parameter documentation and complete annotations, the description covers purpose, usage, and siblings adequately. A minor gap remains in not stating result ordering or whether all pinned items are always returned.

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

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

Schema description coverage is 100% with only two parameters, and both chat_id and account are fully documented in the schema. The description adds no extra meaning about accepted identifier formats or account fan-out behavior, so the baseline 3 for schema-complete tools applies.

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

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

States a specific verb and resource ('Retrieve all pinned announcements and pinned messages in a chat or supergroup') and explicitly demarcates itself from the write siblings pin_message and unpin_message. An agent can distinguish it from get_messages/list_messages without opening any schema.

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

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

Gives a concrete usage context ('Use when checking key rules or notices') and names the two alternative write tools for the inverse operation. It does not, however, explain when to prefer this over the broader get_messages/list_messages, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the auditing framing and no further behavioral detail (no pagination, rate limits, or freshness caveats). It is not contradictory, but it adds little beyond the annotations.

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

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

Two sentences, zero filler, with the read purpose front-loaded and the routing hint second. Every clause earns its place.

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

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

For a read-only, zero-required-parameter tool with a full output schema and complete annotations, nothing an agent needs to call it correctly is missing. Return values are covered by the output schema, so the description need not explain them.

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

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

Schema description coverage is 100% and the single `account` parameter is fully documented in the schema, including multi-account fan-out behavior. The description mentions no parameters at all, so it adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (privacy rules and exception lists) plus the exact attributes covered (phone number, last seen, status). It also names the sibling it is not (set_privacy_settings), so an agent can route without opening either schema.

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

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

Gives an explicit usage context ('Use when auditing account security') and an explicit exclusion plus alternative ('To update privacy settings, use `set_privacy_settings`'). This is the when/when-not/alternative pattern done cleanly.

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 read-only, idempotent, non-destructive profile, so the bar is lower. The description adds a real behavioral constraint beyond them: 'Requires admin privileges,' which is an auth prerequisite an agent needs before calling. It doesn't add rate limits or log retention/window details.

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

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

Three short sentences, front-loaded with the action and resource, then usage cue, then prerequisite. No filler, though the parenthetical content list and the usage sentence could be merged without loss.

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

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

An output schema exists, so return values need not be explained. Purpose, usage cue, resource scope, and the admin-privilege requirement together cover what an agent needs; only explicit differentiation from related tools is absent.

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

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

Schema coverage is 100%, so both params (account, chat_id) are fully documented in the schema, including ID formats and multi-account fan-out semantics. The description adds only the resource scoping ('supergroup or channel') and no syntax beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Retrieve the administrative audit log') and enumerates contents (member bans, edits, admin changes) scoped to supergroups/channels. It separates reasonably well from siblings like get_admins or get_banned_users, though it never names them explicitly.

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

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

Gives one usage cue ('Use when reviewing moderation actions') but no when-not conditions and no mention of alternative sibling tools (get_admins, get_banned_users) that could also serve moderation review. Usage is implied rather than delimited.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the closing 'Read-only operation.' sentence merely restates structured data. The description adds no new behavioral context such as rate limits, privacy/last-seen visibility caveats, or how the multi-account fan-out described in the schema affects results.

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

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

Three tight sentences, front-loaded with the resource and what is retrieved, then usage, then safety. The final sentence is redundant with the annotations, which is the only wasted line.

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

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

With an output schema present, the description need not explain return values, and it covers purpose and timing adequately. The only unaddressed nuance is the multi-account fan-out behavior, which the schema itself documents, so no critical gap remains.

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

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

Schema description coverage is 100%, with both user_id (numeric ID, @username, or phone) and account fully documented in the schema. The description adds no meaning beyond that, so the baseline 3 for high-coverage schemas applies.

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

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

The description gives a specific verb and resource ('Check the online presence, last seen status, and bot flags for a specific Telegram user'), so the agent knows exactly what data comes back. It is clearly distinct from nearby siblings like get_me or get_last_interaction, but it never names an alternative to route against, so sibling differentiation is implicit 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?

'Use before messaging to see if user is active' gives a concrete triggering context rather than leaving usage to inference. It stops short of naming alternatives (e.g., get_last_interaction for history) or stating when this tool is the wrong choice, so it falls just short of the explicit when/when-not bar.

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 'Read-only operation with no side effects' is largely redundant. The genuinely additive behavioral disclosure is the security warning that returned names contain untrusted user content, which the annotations do not cover.

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 tightly written sentences: purpose and returned fields first, then the usage trigger, then the safety caveat. Nothing is wasted and the front-loading is correct.

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?

An output schema exists, so return values need not be re-explained; the description still previews the key fields. Purpose, call timing, and the untrusted-content caveat together make this complete for a zero-parameter read tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool 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 gives a specific verb and resource ('List all configured Telegram accounts') and enumerates the returned fields (profile name, phone number, online status). It implicitly distinguishes itself from single-account siblings like get_me by scoping to all configured accounts, but never names an alternative explicitly.

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

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

It states a concrete usage condition: 'Use at session start to discover available account labels for multi-account routing.' That is a clear when-to-use, though no when-not-to-use or named alternative is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description only adds that pagination is supported, without explaining the mechanism (there is no offset/cursor parameter, only limit), so the added behavioral value is modest.

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

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

Three short sentences, zero filler, and the capability statement is front-loaded before the routing guidance. 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The one remaining gap is that 'pagination support' is asserted but not operationalized, leaving an agent unsure how to page through results beyond the limit parameter.

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

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

Schema description coverage is 100% and all seven parameters are documented in the schema, so the baseline of 3 applies. The description alludes to filtering by title or type but adds no semantics beyond what the schema fields (chat_type, archived, unread_only, etc.) already state.

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

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

The description gives a specific verb (List) plus the resource and its full scope (chats, groups, channels, direct dialogs) and adds the pagination trait. It explicitly distinguishes itself from the sibling get_chats, so an agent can separate the two without opening either schema.

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

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

It clearly states when to reach for this tool ('locating specific conversations by title or type') and names the alternative for the other case ('quick recent dialogs overview, use get_chats'). It does not, however, distinguish itself from neighboring search tools such as search_public_chats or search_contacts, which also target conversation discovery.

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 destructiveHint=false, so the safety profile is fully covered. The description adds the scope of what is returned ('with IDs and phone numbers'), but since an output schema exists this is largely redundant and no auth or rate-limit context is added. A 3 reflects annotations doing the heavy lifting with modest added value.

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 with zero waste; the purpose is front-loaded and the routing hint follows immediately. Every clause earns its place.

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

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

With an output schema handling return values, rich annotations covering the safety profile, and 100% schema coverage of the sole parameter, the description supplies everything an agent needs 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 100% and the single 'account' parameter is fully documented in the schema, so the baseline is 3. The description does not mention the account parameter or its multi-account fan-out behavior, adding nothing beyond the schema.

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

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

States a specific verb (list) and resource (Telegram contacts in the account address book) and explicitly distinguishes itself from search_contacts. An agent can tell the two apart without opening either schema.

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

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

Gives an explicit when-to-use ('finding contacts to message') and names the alternative plus its triggering condition ('to search contacts by query, use search_contacts'). 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only that IDs and titles are returned, which the output schema already conveys, and does not mention the multi-account fan-out behavior described in the account parameter.

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

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

Two sentences, zero filler, with the core action front-loaded and the alternative-tool pointer placed after it. Every clause carries information.

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

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

With an output schema present, the description need not explain return values, and the annotations plus schema cover safety and the account parameter. It is essentially complete, though it never acknowledges the multi-account behavior the schema hints at.

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

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

Schema description coverage is 100% and the single optional 'account' parameter is fully documented in the schema, including the multi-account read fan-out rule. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('List all custom Telegram dialog filter folders (tabs)') and adds the returned fields (folder IDs and titles). It distinguishes itself from the sibling get_folder by explicitly routing chat-level inspection there.

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

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

Gives an explicit trigger ('Use when discovering folder organization') and names the alternative tool with the condition that selects it ('To see chats inside a folder, use get_folder'). 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only the implicit note that pagination here differs from get_messages; it says nothing about return size, ordering, or how filters combine.

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

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

Three short sentences, front-loaded with the core purpose and then the routing rules. The alternative-tool guidance is grouped at the end where an agent can act on it; no sentence is filler.

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

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

With an output schema present and full schema coverage, the description needn't explain return values, and it correctly spends its words on tool selection. It is nearly complete for a filtered-list tool, though it omits any note on pagination mechanics or how the filters interact (AND vs OR).

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

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

Schema description coverage is 100%, so all six parameters (chat_id, limit, account, from_date, to_date, search_query) are already documented in the schema — baseline 3 applies. The description's filter list only loosely overlaps the schema and adds no syntax or format detail.

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

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

States a clear verb+resource ('Retrieve messages from a chat') and explicitly distinguishes itself from get_messages and search_messages. However, it advertises filters ('sender... or topic') that do not map to any schema parameter, so part of the claimed capability is misleading.

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

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

Gives an explicit when-to-use ('Use when filtering chat history') plus two named alternatives with the exact condition that selects each: get_messages for simple sequential pagination, search_messages for text keyword searching. 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds only the conceptual scope (photo messages in a chat) and the download hand-off, with no detail on filtering behavior, ordering, or pagination.

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 filler, with the core capability stated first and the cross-tool routing second. Every clause earns its place and nothing is repeated from the schema or annotations.

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

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

With an output schema present, return values need no explanation, and the annotations cover the safety profile, so the description only needs to establish scope and routing — which it does. It could be slightly more complete by clarifying what 'inspect' entails or how results are ordered/limited, but no critical calling information is missing.

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

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

Schema description coverage is 100% across all four parameters, so `limit`, `source`, `account`, and `chat_id` are fully documented in the schema. The description contributes no additional parameter meaning (e.g., how `source` interacts with the results or default ordering), so the baseline 3 applies.

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

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

States a specific verb and resource ('List and inspect photo messages within a chat'), and carves out a boundary against a sibling action by naming `download_media` for the download case. An agent can tell this is a read-only listing of image messages rather than a media-info or message-listing tool.

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

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

Gives an explicit usage context ('Use when auditing or finding images sent in a conversation') and routes downloading to `download_media`. It stops short of a full when-not statement, and the named alternative covers a different action rather than a competing list tool, so it is clear but not exhaustive.

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, covering the safety profile. The description adds useful return context ('Returns image metadata and preview') but says nothing about permissions, rate limits, or whether save_path triggers a download — modest added value over the structured data.

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

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

Three short sentences, front-loaded with the core action before routing the agent to the alternative. Every sentence earns its place; minor room for tightening but no waste.

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

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

For a read-only tool with no output schema, the description supplies the key return information (metadata plus preview) and a sibling routing hint. It is largely complete, though it could say more about what 'preview' contains or how save_path behaves.

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

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

Schema description coverage is 100%, so the schema already explains all five parameters including account, chat_id, photo_id, save_path, and message_id. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Inspect and view photo content from a chat') and adds the return scope ('image metadata and preview'). It distinguishes itself from get_photo_sheet, but does not address other plausible siblings like list_photos or get_media_info, leaving some ambiguity for an agent choosing among photo 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?

Gives a clear trigger ('Use when analyzing an image in a conversation') and names one alternative with its condition ('For bulk photo galleries, use get_photo_sheet'). It lacks any when-not guidance beyond that single case, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the closing 'Read-only operation' sentence largely restates structured data. The description does add value by specifying the returned identity pair (ID + object type), but it omits failure behavior for non-existent or private usernames and any rate-limit caveats. With annotations covering the safety profile, a 3 is appropriate.

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

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

Three short sentences, front-loaded with the core action and return shape, then the routing rule, then the safety note. No filler or redundant restatement of the title.

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

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

With an output schema present, return-value detail is not required, and annotations carry the safety profile; the description covers purpose, timing, and return type. The only gap is behavior on unresolvable handles, which an agent would likely want before committing to a resolution-then-fetch chain.

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

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

Schema description coverage is 100%, and the schema already documents that the handle omits the leading '@' and how the optional account parameter behaves in multi-account mode. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (resolve) and resource (@username) plus exactly what it yields: the underlying Telegram entity ID and object type. This clearly separates it from ID-consuming siblings like get_chat or get_user_status, which require an already-known identifier.

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

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

Gives a clear when-to-use rule: 'Use before calling ID-based tools when only a username handle is known.' It does not name any alternative or exclusion, though siblings such as search_contacts or search_public_chats could plausibly overlap, so the routing guidance is clear but not fully disambiguated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: no live API calls, no rate limits, and the dependency on previously synchronized messages. It doesn't mention staleness or what happens for unsynced chats, keeping it at 4.

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

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

Three short sentences, front-loaded with the core mechanism, then the benefit, then the prerequisite tool. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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

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

An output schema exists, so return values need no explanation, and the description covers the key non-obvious dependency (sync first) and the offline/rate-limit behavior. It could go further on cache staleness or coverage limits, but for a 4-param read tool it is largely complete.

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

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

Schema description coverage is 100%, with limit, offset, query, and chat_id all documented in the schema itself, so the baseline is 3. The description adds no extra meaning about query syntax (FTS5 matching rules) or pagination behavior beyond what the schema already says.

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 (Search) plus the exact resource and mechanism (local FTS5 SQLite archive), and contrasts it with live Telegram API requests, which separates it from siblings like search_messages and search_global. An agent can tell which search tool to reach for without opening a schema.

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

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

Gives a clear use condition (instantaneous, rate-limit-free search over synchronized messages) and names a concrete prerequisite alternative, `sync_chat_cache`, for populating the cache. It does not explicitly state when NOT to use it (e.g., fall back to live search_messages when the cache lacks a chat), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds scoping context (directory search by name/phone/username) but does not disclose the multi-account fan-out behavior that the account parameter implies. Adequate given annotation coverage, but not rich.

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

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

Two tight sentences: purpose plus matchable fields front-loaded, then the use-when and the sibling alternative. No filler, no redundancy.

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

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

Complete enough for a read-only directory search: an output schema exists so return values need not be described, and annotations cover the safety profile. The only gap is that the multi-account behavior (fan-out vs. default) lives solely in the schema description rather than being reinforced here, but nothing an agent needs to call correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the multi-account fan-out semantics. The description repeats the matchable fields (name, phone number, username) which loosely maps to the query parameter but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (search) and resource (Telegram contacts directory), and enumerates matching fields (name, phone number, username). It also explicitly distinguishes from the sibling list_contacts, so the agent can pick correctly without opening either schema.

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

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

Explicitly says when to use it ('looking up a specific person') and names the alternative (list_contacts) plus its selection condition ('to view the entire directory'). Routing is unambiguous.

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 destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the breadth of the scan (all joined dialogs plus public channels) and the cost trade-off versus the scoped sibling. It stops short of describing result ordering, pagination limits, or multi-account fan-out 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?

Three short sentences, front-loaded with the scope before the routing advice. Every sentence earns its place: what it searches, when to use it, and which alternative to prefer.

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?

An output schema exists, so return values need no explanation, and the annotations carry the safety semantics. Combined with full parameter documentation, the description supplies everything else an agent needs to select and call this search 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 100%, so all four parameters (query, page, page_size, account) are already documented in the schema. The description adds no syntax, matching, or filtering semantics beyond what the schema states, which is the baseline 3 case.

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 (search message text) with an explicit scope (all joined dialogs and public channels globally). It also names the sibling it is not — `search_messages` — so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit when-to-use condition ('Use when the target chat is unknown') and a when-not condition with a named alternative ('If the chat is known, prefer `search_messages` for faster scoped results'). 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 declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely new context by implying live Telegram API calls (contrasted with the cache-only sibling). It stops short of disclosing rate limits, pagination, or empty-result behavior, so it is strong but not exhaustive.

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

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

Three short sentences, zero filler: capability first, usage second, alternatives third. Every sentence carries information an agent needs before choosing 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?

Output schema exists so return values need not be explained, annotations carry the safety profile, and the schema fully documents parameters. The routing information the description supplies is exactly the missing piece, leaving nothing an agent needs absent.

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

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

Schema description coverage is 100%, so all four parameters (limit, query, account, chat_id) are already documented with examples and defaults. The description adds no syntax, format, or matching-behavior detail beyond the schema, which is the baseline expectation at this coverage level.

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

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

States a specific verb ('Search for text keywords'), an explicit resource scope ('within a specific Telegram chat or supergroup'), and contrasts itself with two named siblings. An agent can distinguish it from search_global and get_messages without opening any schema.

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

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

Names the exact scenario ('finding past conversations in a single chat') and then routes the agent to two alternatives with their selecting conditions: global public channel search versus offline cache search. When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety and idempotency profile is fully covered. The description adds the global-scope trait but says nothing about result volume, rate limits, or ordering beyond what structured fields provide. Adequate but not rich.

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

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

Three short sentences, front-loaded with purpose then routing guidance. No filler and 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers scope, purpose, and alternatives, leaving only minor gaps (e.g., pagination/limit guidance) relevant to 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 100%, so the schema already documents query, limit, and account; baseline is 3. The description refines what the query targets (public communities rather than the generic "messages, contacts, or entities" in the schema), a marginal but real addition.

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 (Search) plus the resources searched (public channels, supergroups, bots) and the scope (globally / Telegram-wide). It is immediately distinguishable from in-account search siblings. No schema opening required to understand the 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?

Gives explicit when-to-use ("when discovering new public communities") and names the alternatives with the condition that selects them ("search within your existing chats, use list_chats or search_messages"). The global-vs-local routing decision is fully specified.

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 full safety profile (readOnly, openWorld, idempotent, non-destructive), so the bar is lower. The description adds the persistence target and checkpoint-based incrementality, but stays silent on error/failure behavior, auth requirements, and rate limits, leaving it at the minimum-viable-plus level.

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 front-loaded sentences: purpose, then when to use, then mode behavior. Each earns its place, though the mode sentence partially duplicates the schema's mode description.

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

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

With a full output schema and 100% parameter coverage, the description needn't explain return values, and it does cover purpose, cadence, and modes. It is nearly complete for a cache-sync tool; only failure/partial-sync behavior is unaddressed.

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

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

Schema description coverage is 100%, so all four parameters (mode, limit, account, chat_id) are already documented with defaults and semantics. The description only restates the mode concept and adds no new syntax or constraints, so the baseline 3 applies.

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

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

The description names a specific verb (synchronize) plus resource (a batch of recent chat messages) and destination (local SQLite/FTS5 archive), so the tool's job is unambiguous. It implicitly separates itself from read-side siblings like search_cached_messages and cache_health, but it never explicitly names or contrasts a sibling, so it falls short of a 5.

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

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

"Use periodically to keep the offline cache fresh" gives a clear context for invoking the tool, and the incremental/full modes are explained. However, it offers no exclusions and does not route the agent against alternatives such as get_messages or search_cached_messages, so the guidance is contextual but incomplete.

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