token_bowl_chat_get_unread_direct_messages

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

No annotations are provided, so the description carries the full burden, and it discloses almost nothing behavioral: no auth/permission requirements, no statement about whether fetching marks messages as read (critical for an 'unread' tool), and no rate-limit or pagination-behavior notes. The only behavioral hint is the return shape (same structure as room messages).

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?

Front-loaded one-line purpose, one usage sentence, then clearly labeled Args and Returns blocks. No redundant or wasted text for a two-parameter read 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?

An output schema exists, so not explaining return values in depth is acceptable, and the pagination/model args are covered. However, with zero annotations the description should address auth and, importantly, whether reading consumes the unread state — a key behavioral gap for this 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 0% (parameters have only titles and defaults), so the description must compensate, and it does: it explains limit is a max count of messages (default 50, max 50) and offset is a skip count for pagination (default 0). This adds real meaning over the bare 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+resource ('Get unread private messages') with a scope qualifier (unread, direct) that separates it from token_bowl_chat_get_direct_messages and token_bowl_chat_get_unread_messages. It doesn't explicitly name those siblings or explain the contrast, 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?

The second sentence ('Use this to fetch only the direct messages you haven't read yet') implies the usage context but never states when to prefer this over get_direct_messages (all DMs) or how it relates to mark_message_read / get_unread_count. No exclusions or alternatives are given.

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