Set Eos OSC Fader

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

Annotations already convey read-only false, idempotent, non-destructive, and open-world. The description adds the precondition that the bank must exist and mentions a one-time session setup, giving useful session-level context. It does not contradict the annotations and adds value beyond the structured hints.

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 front-loaded with a clear purpose sentence and then a structured Args list. The prerequisite note is valuable. It is slightly verbose with the parenthetical 'it only needs to be done once per session,' but that is relevant. Overall, it is efficiently organized.

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 simple 3-number tool with no output schema, the description covers the essential context: purpose, prerequisites, and parameter meanings. The only notable gap is that fader_index's base (1-based vs 0-based) is not explicitly stated, but the inclusion of the master fader hint and the bank creation workflow makes it mostly 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 only 33% (only level has a schema description). The description compensates by documenting all three parameters, including bank_index's 1-based indexing and 0-for-master special case, fader_index's meaning as a position, and level's range. This adds meaning beyond the schema, though fader_index could be more explicit about its base.

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 and resource: "Set a fader in an OSC fader bank to a level." This clearly states the action and target, distinguishing it from siblings like eos_set_channel_level (channels vs faders) and eos_configure_fader_bank (creation vs setting).

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 states a prerequisite and alternative: "Requires the bank to already exist on the console (call eos_configure_fader_bank first if you haven't created bank_index yet)." It also gives a special-case instruction for the master fader (use 0). This provides clear context, though it doesn't explicitly discuss when not to use this tool relative to other fader-related commands.

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