Get Chat Messages

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context, such as pagination behavior, the meaning of fetchAll, or that messageId bypasses list filters. Given the annotations, a 3 is appropriate – the description doesn't contradict annotations but also doesn't enrich them.

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 extremely concise, a single sentence that conveys the core purpose. It's front-loaded with the main actions. However, it is arguably too terse for an 11-parameter tool, but that's a completeness issue, not a conciseness issue. It wastes no words, so it earns a 4.

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?

With 11 parameters, 2 enums, and no output schema, the description is severely underspecified. It doesn't explain the difference between listing and reading by ID, the role of pagination (fetchAll), or the filtering options (since, until, fromUser). An agent needs more context to call this correctly, especially to understand when to use messageId vs the list filters. The description is not sufficient for a tool of this 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 description coverage is 100% with each parameter having a meaningful description. The description itself adds nothing about parameters. Baseline 3 is correct since the schema does the heavy lifting; the description doesn't need to repeat what's already documented.

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 clearly states the tool lists chat messages or reads a single one by ID. The verb 'List' and 'read' specify the primary actions, and the resource is 'chat messages'. However, it doesn't explicitly differentiate from sibling tools like get_channel_messages, which also deal with messages, but the chat vs channel distinction is implied. It's clear but could be more specific about scope.

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 no guidance on when to use this tool versus alternatives such as get_channel_messages or search_messages. It doesn't mention scenarios where reading a single message via messageId is preferred, nor does it explain the relationship between chat messages and channel messages. An agent has to infer usage from the schema, which is not sufficient.

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