list_topics

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

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond them with cursor persistence rules, retry_after_seconds handling, ordering guarantees, 'issues' for incomplete metadata, and the caveat that titles/order can shift mid-traversal. It also flags the permission trap (public read rights don't cover forum groups) that an agent could otherwise walk into.

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

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

Purpose is front-loaded and nearly every clause carries operational information; clauses are short and scannable despite the lack of bullets. Minor waste in restating read-only semantics ('Listing topics does not mark them read or modify them') that annotations already imply.

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

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

With no output schema, the description still describes the shape of the response (next_cursor, issues, top_message_ref/root_message_ref, retry_after_seconds, ordering) and the edge case that a short or empty page can still return a cursor. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the load, and it explains three of four parameters: chat_ref's accepted formats, query as an optional topic-name filter, and cursor via the next_cursor/retry continuation rule. Only 'limit' is left implicit, which matters given its 30 default and 100 cap.

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

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

Specific verb plus resource (list topics in a forum supergroup) with the accepted selector formats (ID, @username, t.me link) spelled out. It cleanly separates itself from read-path siblings by pointing to get_history/get_pinned_messages for topic contents and get_thread/get_messages for refs.

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 routing ('Pass a topic ID to get_history or get_pinned_messages', 'Read top_message_ref with get_messages, or ordinary root_message_ref with get_thread') and explicit exclusions ('Bot forums and monoforums are unsupported', public discovery/read permissions do not authorize forum groups). It even states the non-effect: listing does not mark read or modify.

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