Watch fixture values change

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

No annotations are supplied, so the description must carry the full behavioral load, and it does most of it: declares read-only, states the call is server-side over time, describes the returned data (first/last value, min/max, timed changes), and discloses the failure mode for ungranted universes (outputState, samples nothing). What it never says outright is that the call blocks for up to 30 seconds and what happens if the fixtures do not exist.

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?

Front-loads the core concept and every sentence carries information, but the parenthetical asides accumulate and the source/default information is scattered rather than grouped, making it denser than it needs to be for five parameters.

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?

With no annotations, no output schema and five parameters, the description covers the return shape, the error condition, prerequisites and the phaser caveat. The remaining gap is the blocking nature of the call and its cost against the server, which an agent scheduling work would want to know.

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 only 40%, yet the description supplies defaults and bounds absent from the schema for seconds (1-30, default 5) and interval_ms (50-2000, default 200), explains source values (programmer default vs output), clarifies fixtures accepts a range or list, restricts output mode to 1-8 fixtures, and gives examples of attributes.

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?

States a specific verb and resource ('OBSERVES OVER TIME... samples the programmer values or the DMX output of fixtures... reports which channels changed'), plus the distinguishing scope: it samples repeatedly over a duration rather than returning a snapshot, which separates it from gma3_fixture_output and gma3_programmer.

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?

Explicitly names the alternative it replaces ('use it instead of a Lua polling loop'), states the prerequisite ('It starts nothing: run the playback or phaser first'), and gives a non-obvious exclusion with the correct fallback ('a running phaser in the programmer reads as its steps... watch its output instead').

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