set_channel

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a readback, that probe ratio is applied before scale/offset, and that changing probe ratio may rescale existing values. These are meaningful behavioral traits beyond the schema.

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 concise sentences with no filler. The main action is front-loaded, followed by the return value and the most important caveat. Every sentence contributes useful information.

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 mutating tool with no output schema and no annotations, the description covers the core action, return behavior, an important side effect, and a precondition. It could be slightly more explicit about unspecified settings remaining unchanged, but overall it is adequately complete.

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 67%, and the description adds important semantic context for probe ratio and its interaction with scale/offset. It does not describe every parameter, but the schema itself covers most parameter meanings via descriptions and enums.

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?

Description states a specific verb and resource ('Change specified channel settings') and mentions the return of channel readback. It clearly distinguishes this tool from sibling set_* tools by targeting channel settings rather than timebase, trigger, or cursors.

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?

Provides clear context for use: changing channel settings, with a precondition that the channel must be installed. It does not explicitly compare to alternatives like set_timebase or set_trigger, but the channel-specific scope makes the intended use clear.

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