Read recent Oase messages

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

With no annotations, the description fully bears the burden of behavioral disclosure. It reveals that messages are decrypted, how they are ordered, the tagging scheme for the agent's own messages, the display of reactions and attachments, and explicitly warns that reactions are real answers (not just UI clutter). It also explains that attachments require read_media, providing essential behavioral context for correct handling.

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 longer than typical, but every sentence contributes actionable information. It starts with the core purpose, then moves to output format, then to usage instructions for replying, threading, reactions, and attachments. There is no filler or redundancy; the structure is logical and front-loaded with the most essential facts.

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?

Given that there is no output schema, the description must (and does) explain the return format in enough detail for an agent to interpret results correctly: each line includes an id, tags, reactions, and attachment markers, plus how to use each piece with other tools. It also covers edge cases like thread replies and attachment handling, making the tool fully usable without further probing.

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?

The input schema already documents both parameters, including their defaults (limit defaults to 20, oase_id defaults to last joined oase). The description does not add additional semantic meaning beyond what the schema provides. With schema coverage at 100%, a baseline of 3 is appropriate.

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 verb (read) and resource (recent chat messages in an oase), adds meaningful detail like 'decrypted' and 'oldest first', and distinguishes from sibling tools like read_posts (posts vs messages) and send_message (write vs read). The purpose is unambiguous and specific.

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 explicit context for when to use this tool (reads recent messages) and provides clear instructions on how to act on the output: replying uses send_message with thread_id, continuing threads uses the root id, and any id works for react_to_message. However, it does not explicitly name alternatives for reading posts or state when not to use this tool, so it stops short of a 5.

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