list_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 of behavioral disclosure. It explains the return type and the unread_only flag, implicitly indicating a read operation, but does not explicitly state whether listing messages has side effects (e.g., marking them as read) or any other behavioral nuances.

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 well-structured with distinct sections for summary, usage, arguments, return value, and an example. It is concise without unnecessary repetition, and every section serves a clear purpose.

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 gives all necessary context: purpose, usage, parameter meanings, return format, and a concrete example. With an output schema available, the description doesn't need to detail return structure further, so the coverage is fully adequate.

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%, but the description compensates fully by documenting each parameter in the Args section. current_task_id is explained as 'Your current task ID' and unread_only as 'Only show messages not yet acknowledged,' adding meaningful semantics beyond the schema's bare type definitions.

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 explicitly states 'List messages received by this session' with a specific verb and resource. It clearly differentiates from siblings like send_message and acknowledge_message, making the tool's unique purpose unambiguous.

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 sentence 'Use this to see what other sessions have communicated to you' provides direct guidance on when to use the tool. While it doesn't explicitly mention alternatives or exclusions, the use case is clear and logically distinct from sibling tools.

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