segment_detail

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

No annotations are supplied, so the description carries the full behavioral burden, and it does disclose the shape of the returned evidence bundle — valuable given there is no output schema. It stays silent on whether this is a read-only lookup (implied by 'evidence bundle' and 'inspect'), how large the payload might be, or what an invalid segment number produces.

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?

A single front-loaded sentence naming the bundle and its parts, followed by a terse parameter note — no filler. The one weak spot is that the parameter note is appended after the return-value inventory rather than stated first, but it costs nothing.

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 one-parameter, no-output-schema tool, the description adequately conveys what comes back and how to address a segment. It leaves the caller to infer where segment numbers originate and how this aggregate relates to the individual sibling getters, which is the main gap.

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?

With a single parameter at 0% schema coverage, the description fully compensates by defining n as a 1-based segment number, including the indexing base a bare 'number' type would omit. It does not state whether n must exist in the current session or what the valid range is.

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 names a specific resource — a single segment's evidence bundle — and enumerates its contents (verbatim speech, suspect elements, dead clicks, errors, shots and DOM snapshots). What's missing is differentiation from siblings like list_segments or get_errors, since segment_detail aggregates the same data those tools expose individually; the '</p>' retrieval verb is only implied by 'inspect'.

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?

Usage is only implied: 'n = segment number (1-based)' signals that a caller must first have segment numbers, presumably from list_segments, but the description never says so. There is no explicit guidance on when this detail bundle beats calling get_asr, get_errors or get_dom_state separately, nor any exclusion for out-of-range segment numbers.

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