Read a Juggle message conversation

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

Goes well beyond readOnlyHint by disclosing a real side effect — opening the conversation may mark Juggle's messages as read, mirroring the website — and by warning that returned text is third-party and untrusted. That injection warning is exactly the kind of context annotations cannot carry.

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?

Front-loads what is returned and the paging rule, then puts the side-effect and trust warnings at the end where they read as caveats. The clause explaining why read-marking happens is slightly wordy but justifies a behavior an agent would otherwise flag as surprising.

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?

For a four-parameter read tool with no output schema, the description covers the return shape, paging, id provenance, and the read-state side effect. The only gap is that response format variants (compact/full/raw) are left entirely to the schema, which handles them adequately.

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 coverage is 100%, so baseline is 3; the description adds ordering semantics the schema does not state ('the most recent limit messages, oldest first') and clarifies the offset direction for paging back in time. It leaves the 'view' enum to the schema, which documents it thoroughly.

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?

States a specific verb and resource ('Read the messages in one Juggle conversation') and enumerates the returned fields (sender, mine, time, text), which distinguishes it cleanly from the sibling juggle_list_conversations that enumerates conversations rather than messages.

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?

Explicitly routes the agent to juggle_list_conversations for the required conversation_id and explains paging behavior ('page further back with offset'). It does not name a when-not scenario or point at juggle_send_message as the write counterpart, but the read scope is unambiguous.

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