tg_scheduled

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

With no annotations, the description carries the full burden of disclosure. It explicitly states that passing cancel_ids cancels scheduled messages, revealing the tool's dual behavior. However, it does not mention consequences such as permanence, whether cancellation requires confirmation, or how invalid IDs are handled. The core mutation is acknowledged but lacks depth.

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

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

The description is concise and front-loaded with the core purpose. The argument list is compact and easy to scan. The only issue is the initial sentence is a fragment ('Messages scheduled for later in a chat.'), which is slightly awkward, but it does not waste words or obscure meaning.

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

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

The description covers the tool's two modes (list and cancel), parameter semantics, and the chat identifier format. An output schema exists, so return values need not be described. It lacks usage guidance and edge-case behavior, but for a tool of moderate complexity, the core functionality is adequately covered.

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

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

Schema description coverage is 0%, so the description must compensate. It provides clear explanations for all three parameters: chat format ('chat id, @username, exact title or me'), limit ('how many to list'), and cancel_ids ('message ids to cancel instead of listing'). This adds significant meaning beyond the raw schema and fully compensates for the lack of schema descriptions.

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

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

The description states that the tool deals with 'Messages scheduled for later in a chat' and that passing cancel_ids cancels them. This clearly indicates it lists and optionally cancels scheduled messages, distinguishing it from siblings like tg_schedule (which likely creates them). The phrasing is slightly fragmented but the intent is understandable.

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

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

No explicit when-to-use or alternative guidance is provided. While the behavior of listing vs. canceling is implied by the presence of cancel_ids, there is no mention of when to use this tool instead of tg_schedule, tg_send, or other messaging tools. The description leaves usage context entirely to the agent's inference.

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