set_pid

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

With no annotations provided, the description carries full burden and does an excellent job: it discloses dry-run default, the confirm flag causing save+reboot, the safety warning, and the preconditions (gates). It also clarifies that only passed parameters are changed. This is far beyond the minimum and gives the agent confidence in invoking the tool.

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 well-structured and front-loaded with the core purpose. The args section is compact, the warning is a single line, and no sentence is wasted. It fits the maximum guidance for a tool with this complexity.

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?

Despite no output schema or annotations, the description covers the essential operational context: purpose, parameter semantics, dry-run behavior, confirmation effect, safety implications, and prerequisites. For a 6-parameter CLI write tool, this is complete enough for an agent to invoke 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 0%, so the description must explain parameters. It does so thoroughly: axis values are enumerated, p/i/d/ff map to fw_p_<axis> etc., and confirm's meaning is explicit. This fully compensates for the schema's lack of descriptions.

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 starts with a clear, specific action: 'Set fixed-wing PID gains for ONE axis (atomic CLI write).' This includes the verb, resource, and scope, and distinguishes it from sibling tools like read_tuning or set_nav. It also clarifies the atomic nature of the operation.

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 provides context on when to use the tool (changing PID gains per axis) and notes the dry-run default and gates. It does not explicitly name alternatives such as read_tuning for viewing gains or cli_batch for bulk operations, but the 'ONE axis' framing and atomic write hint at its niche. The gates (connected, not armed, auto-backup) are practical usage conditions.

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