start_replay

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

With no annotations provided, the description carries full behavioral disclosure burden and largely delivers: it explains the wall-clock timing behavior, that annotations arrive at original timings, the identical buffering/chunking behavior to live streams, and the 'safe' framing implies non-destructive semantics. The description could add more on return values or side effects beyond event emission, but the core behavioral character is well disclosed.

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?

Three tight paragraphs, zero filler. The opening line states the action, the second paragraph justifies why this tool exists (safe real-time pipeline building, code-portability promise), and the third closes on a specific behavioral guarantee. Every sentence earns its place and the most important information is front-loaded.

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?

This is a moderately complex tool with 8 parameters and an output schema, yet the description plus schema cover the use case thoroughly: when to use, how it behaves, key shortcuts (path resolution), and parameter meanings. An output schema exists so return value documentation isn't strictly required. The description is complete enough to guide correct selection and invocation, though a note on stopping/replay_control coordination could slightly enhance completeness.

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 every parameter already has rich inline documentation (loop semantics, speed interpretation, start_sec offset, board requirement for BrainFlow, picks defaults, session_id usage). The description adds the key architectural context that parameters like speed and loop map to realistic-latency tradeoffs and long-running rehearsal use cases, reinforcing the schema. The description and schema together are quite complete; the marginal value added by the description's prose on parameters is moderate but real.

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 opens with a specific verb+resource combination: 'Replay a recording against a wall clock, re-emitting its events.' It clearly distinguishes start_replay from sibling tools like start_stream (live data) and start_recording (capturing), establishing itself as the playback-side complement. The purpose is unambiguous and the scope is precisely defined.

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 frames this as 'the safe way to build a real-time pipeline' because the session behaves exactly like a live stream with identical buffering, chunked delivery, and tools. It explains this is preferred over live hardware for development because code runs unchanged against hardware, giving a strong when/why directive. No explicit when-not guidance, but the contrast with live streams and the pipeline-building context serve as clear usage framing.

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