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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description doesn't need to repeat that. What it adds is genuinely useful behavioral guidance: what is returned (saved text, request identities, settlement receipts) and explicit prohibitions against executing returned pending actions, resuming generation, or inferring a refund. Those constraints prevent real misuse. It doesn't discuss failure or empty-result modes beyond the refund caveat.

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 core purpose is front-loaded in the first sentence and the routing rule follows immediately. The warning sentence is dense but every clause maps to a distinct misuse. A small amount of the safety phrasing ('Never execute... resume generation... infer a refund') is compressed into one long sentence rather than structured, but nothing is wasted.

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 five undocumented parameters, no output schema, and 0% schema coverage, the definition should close more gaps than it does. It describes the return payload well enough that an output schema isn't needed, but minimumRevision's role and the identity of the three required IDs remain unexplained, which is material for a dual-mode read tool.

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 0% across five parameters, so the description carries the burden and only partly discharges it. It explains the mode split around 'three original IDs', chatId and cursor, but never names which three IDs they are (turnId, userMessageId, chatId), and minimumRevision is not mentioned at all. The value added is real but incomplete.

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 first sentence names two specific operations on a specific resource: reading an original durable chat turn, or discovering saved turns. That verb+resource pairing is far more precise than the generic 'recover' in the name and clearly separates it from sibling draft-recovery tools like soclo_work_drafts_read. It stops short of explicitly naming a sibling it displaces, so it lands at 4 rather than 5.

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?

It gives a concrete routing rule: pass all three original IDs to read a single turn, otherwise fall back to discovery with chatId and cursor. It also states an exclusion — 'Continue in the Soclo app for a deliberate new action' — making clear this tool is not for initiating work. It does not point to a named alternative MCP tool for that continuation case, which keeps it at 4.

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