tg_dialogs

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds non-obvious behavior on top of that: sparse rows om it fields whose value equals the default (no pinned = not pinned), the t.me link construction, and the account-specific trait that most chats live in the archive. These shape both result interpretation and the default call pattern and appear nowhere in the annotations or schema.

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

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

One-sentence purpose up front, then output semantics, then a per-arg block — the right structure for a 5-param tool with a bare schema. The kind="saved" tail rambles and truncates slightly (". . . stuff articles, links, ..."), but no sentence is wasted and the tg_history cross-reference earns its place.

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

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

With no output schema, the row-semantics paragraph partly fills the return-shape gap (which fields appear, how to build the link). What's missing is the chat identifier an agent should hand to follow-up tools, plus any pagination/limit-bound behavior — a listing tool that feeds the rest of this API should say how rows reference chats for the next call.

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

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

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

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

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

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

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

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

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

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