start_stream

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

No annotations are provided, so the description carries the behavioral transparency burden. It does disclose non-obvious behaviors: data flows into a ring buffer from a background thread immediately, the session persists asynchronously, and read_window will have samples waiting. However, it doesn't disclose error conditions (e.g., invalid board name, connection failure), resource implications, or whether this mutates any persistent state. The key asynchronous behaviors are covered, but the failure/cleanup story is incomplete.

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 compact and front-loaded. The opening line states the core action, and immediately telegraphs the async/pre-buffering behavior. Every sentence earns its place: the ring buffer behavior, the read_window implication, and the stop_stream lifecycle note all add value without repetition. There is zero wasted verbiage.

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 tool with 100% schema parameter coverage and an output schema present, the description covers the essential behavioral context well. It explains the background-thread buffering semantics, the prerequisite relationship with read_window, and the termination contract with stop_stream. Given the tool's moderate complexity (4 params, all documented) and the presence of an output schema, this is complete enough for an agent to use it correctly.

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 parameters are well-documented in the schema itself. The description adds lifecycle context around session_id (referenced as a persistent name for later calls) and implies the board/params relationship. The session_id semantics ('Name you will pass to every later call') is enriched by the description's context about the session keeping running. This meets the baseline 3 and adds a bit more value by explaining the session_id's cross-call role.

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 clearly states what the tool does: opens a board and begins buffering EEG in the background. It uses specific verbs (open, begin buffering) with a specific resource (board/EEG). It distinguishes itself from siblings like start_replay (which is for playback) and stop_stream (which is the inverse), and clarifies it's distinct from start_recording.

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 explains when this tool is needed (before read_window calls) and what happens upon invocation (samples will be waiting), plus the lifecycle is made clear ('session keeps running until stop_stream is called'). It also references list_boards for board options via the schema, providing a clear alternative/discovery path.

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