list_messages

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

With no annotations, the description carries the full behavioral burden, and it mostly succeeds: it states ordering ('newest first'), server-side filtering, pagination mechanism, and the shape of the return value. It does not explicitly state 'read-only' or mention authentication/rate limits, but the read-only nature is strongly implied and no destructive side effects are suggested.

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 a one-line summary, an Args block, and a Returns block. Every parameter earns its place, and the filter examples are useful rather than filler. It is concise despite the large number of parameters.

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?

Despite no output schema, the description fully defines the return format and pagination token. It covers defaults, parameter semantics, filter interactions, and the one key limitation ($search) with a pointer to the right alternate tool. An agent has everything needed to invoke this correctly.

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 fully compensate. It explains every one of the 7 parameters in detail, adding default values, valid ranges (limit: 1-100), well-known folder names, OData filter syntax with examples, and the behavior of unread_only. This goes well beyond 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?

The description opens with a specific verb and resource: 'List messages from a mail folder, newest first.' It clearly distinguishes itself from sibling search_messages by noting that $search cannot be combined with filter and that search_messages should be used instead. The scope (folder, mailbox, pagination) is 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 description gives concrete usage context: default folder, default mailbox, pagination continuation, and filter behavior. It explicitly warns that filter cannot be combined with $search and points to search_messages as the alternative. It does not cover every sibling relationship (e.g., get_message for a single message), but it provides enough for correct tool selection.

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