List my turns

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context the annotations cannot: a runtime prerequisite (npx llmxray), a latency bound ('Under a second'), the guarantee that no model is called, the ordering convention ('newest last'), and a genuine scoping trap (omitting `client` on a shared machine exposes every tool's turns). That is substantive disclosure beyond the structured fields.

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?

Purpose and output shape are front-loaded in the first sentence, and routing guidance follows immediately. The third paragraph re-states ranges (1–100, 1–10080, default 20) that the schema already carries verbatim, which is the one place a sentence does not fully earn its place.

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?

There is no output schema, so the description compensates by describing the exact line format the agent will receive, plus field-level flags (reloaded, rejected, cut by context, error). Combined with the prerequisite, latency, and scoping caveat, an agent can call and interpret this tool without further discovery.

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, but the description adds semantics the schema does not encode: 'limit … the newest kept' (schema only says 'newest turns to show') and 'The three combine', which tells the agent the filters compose rather than override. The numeric ranges and default are restated from the schema, so it does not fully escape redundancy.

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 a concrete verb+resource (list the turns your client sent through LLMxRay) and enumerates the exact per-line fields, so an agent knows precisely what comes back. It explicitly contrasts itself with diagnose_my_turns and read_my_last_turn, removing ambiguity among siblings. No other sibling in the list (compare_my_turns, estimate_my_prompt) overlaps this role.

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 positive triggers ('see the sequence behind a finding', 'pick the turn numbers for compare_my_turns') and explicit routing for the two nearest alternatives ('For a verdict use diagnose_my_turns; for one turn in full use read_my_last_turn'). The prerequisite ('Needs LLMxRay running') and the shared-machine caveat on `client` are both stated. Nothing is left to inference.

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