get_last_unread_message

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

With no annotations provided, the description carries the full burden of disclosure. It correctly signals a read-only operation, explains both execution modes, and discloses the return format for the scan-all case ('compact list of all unread messages with their senders and text'). It doesn't cover rate limits or the empty-result case, but the core behavior is transparent.

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 sentences with zero waste: main action first, then the two-mode explanation, then a terse imperative exclusion. The most decision-relevant info (mode behavior) is front-loaded, and the 'NEVER' directive earns its place as a guardrail.

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 tool with one optional parameter and no annotations, the description is thorough: it covers both invocation modes, the return shape of the scan-all mode, and an exclusion. Minor gaps are the unspecified return format for the single-chat mode and the no-unread-messages case, but these are small for the tool's complexity.

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 baseline is 3. The description adds value beyond the schema by explaining the behavioral consequence of omitting chat_name (scan all chats and return a compact list in one call) versus providing it (return latest in that specific chat), which the schema's 'Optional contact or group name' does not convey.

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

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

The description states a specific verb ('Reads') and resource ('unread messages'), and clearly distinguishes the tool from siblings by its focus on unread status. It differentiates behavior for the two invocation modes (specific chat vs. all chats), making it unambiguous what this tool does relative to get_last_message and get_last_messages.

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

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

The description gives explicit guidance on when to use it with vs. without chat_name, and includes a strong exclusion directive ('NEVER call list_teams_chats first') that prevents a common mistake. However, it doesn't explicitly contrast with get_last_message/get_last_messages, leaving the unread-vs-all distinction to be inferred rather than stated.

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