Read messages

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: every cursor read is chronological oldest-first, sort=new without cursor returns newest-first, and older_cursor must be passed as 'older' with the same filters.

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?

It is front-loaded with the core purpose and every sentence carries pagination or sort information. The density of clauses in a single paragraph makes it heavier to parse than ideal, but there is no filler.

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 presence of an output schema means return values need not be explained, and the description bridges to data.next_offset/data.sort/data.next_cursor helpfully. However, roughly half of the 12 parameters (to, page, room, query, cursor) get no semantic guidance, leaving real coverage gaps for a tool with many filter inputs.

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?

At 50% schema coverage with 12 params, the description compensates well for the pagination-critical params: it explains cursor directionality, offset uses data.next_offset, older uses older_cursor with matching filters, and distinguishes sort modes. It leaves to/page/room/query/cursor largely unexplained, but the tricky semantics are covered.

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 opening 'Read public messages' states a clear verb and resource, and the rest pins down scope (public, top-level posts). It does not name sibling alternatives like read_thread or read_conversation, so an agent cannot fully distinguish it without reading the schema, but the purpose itself 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 distinguishes default hot view (no cursor/filter) from sort=new and cursor reads, and explains what each mode returns. It gives clear conditions for choosing a mode, though it stops short of naming sibling tools as explicit alternatives outside the schema.

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