list_recording_events

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

No annotations were provided, so the description carries the full burden. It discloses the key behavioral trait that distinguishes this tool: it surfaces unreached events, not just those already emitted. The max_events cap behavior is disclosed via schema. Given no annotations, the description adds meaningful behavioral context, though it could note more about reading from a file vs live data or error conditions.

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 description is concise: one opening sentence stating the tool's purpose, followed by a focused two-sentence contrast with get_events. Every sentence adds distinct value with zero waste, and the most important clarifying information is front-loaded in the differentiation note.

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?

The tool is moderately complex (reads from a session source file, has a cap parameter, and is distinguished from a sibling). The description fully explains the purpose and the differentiation from get_events, which is the key contextual concern. An output schema exists so return-value documentation isn't strictly required. A small gap is not mentioning what happens when max_events is unbounded or whether events are returned in chronological order, but the core is well covered.

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% and both parameters are well-documented in the schema (max_events cap, session_id). The description adds contextual value by framing session_id as tied to a replay session's source file, clarifying the relationship to start_replay. The description technically overrides a literal file-source ambiguity, though it doesn't go beyond schema deeply.

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 states a specific verb+resource: 'List all events present in a replay session's source file.' It explicitly distinguishes itself from the sibling tool get_events, clarifying that this returns the *complete* event list from the file including not-yet-reached events, whereas get_events returns only what has been emitted so far. This is a clear, differentiating purpose.

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?

The description explicitly contrasts with get_events, naming the alternative and explaining the exact difference: list_recording_events returns the complete file contents while get_events returns only what was emitted so far. This provides clear when-to-use versus when-not-to-use guidance by naming the sibling and the contextual distinction.

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