List cached messages

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral traits: oldest-first ordering, the next_since pagination loop, retention-dependent empty results, shortened message bodies, and the meaning of the 'updates' field. This gives the agent a realistic expectation of results and side effects without contradicting the annotations.

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 has three focused paragraphs, each carrying distinct information: core behavior and pagination, topic discovery constraints, and result interpretation caveats. No sentence is redundant or filler; it is concise for the complexity of the 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?

With 9 parameters, full schema coverage, an output schema present, and safety annotations provided, the description still covers the essential behavioral caveats an agent would need: pagination mechanics, retention ambiguity, body truncation, and update entries. The tool is complex enough that these additions are necessary, and they are all present.

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%, so the baseline is 3. The description adds meaningful semantic context beyond the schema, especially for the 'since' parameter by explaining the next_since round-trip pattern and for the overall ordering semantics. This is more than a restatement, so it earns a 4.

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: 'Polls the cached messages of one or more topics, oldest first.' It clearly distinguishes itself from get_message by stating message bodies are shortened and pointing to get_message for full content, and from list_users/get_account by explaining topic discovery. An agent can immediately tell what this tool does and how it differs from siblings.

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 explicitly routes to get_message when a full message body is needed, and mentions get_account or list_users for topic discovery. It provides clear context for when this tool is appropriate (polling cached messages, using pagination via next_since) but does not comprehensively list when-not-to-use alternatives across the full sibling set. This is strong guidance but not exhaustive.

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