plainhub_ledger_thread

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

With no annotations supplied, the description carries the full burden and does so: it discloses the storage location and env var dependency, the ordered field set of each message, and that results are wrapped in <ledger-data-…> markers with an explicit prompt-injection warning. That last point is behavioral context an agent could not get from any structured field.

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 the purpose, then usage, then alternative, then example, then the safety caveat — a sound ordering with no filler. The location/env-var detail is packed into a long opening sentence, which slightly blurs the lead.

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 single-parameter read tool with no output schema, the description covers what to pass, when to call it, where data comes from, and roughly what comes back. Nothing an agent needs in order to call it correctly is missing.

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 the baseline is 3, but the description adds the mapping of the thread value into the path .agents/threads/<thread>/ and a concrete example call. The example value itself largely duplicates the schema's own example, which keeps this from a 5.

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 a work thread in the ledger') plus the physical location (.agents/threads/<thread>/) and the per-message fields returned. It also distinguishes itself from the sibling plainhub_ledger_read, which returns a full message rather than the thread listing.

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?

Gives an explicit trigger ('Use it before you post to a thread, to see where the work is') and names the alternative tool with the condition that selects it ('Read a full message with plainhub_ledger_read'). No inference required from the agent.

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