cli_exec

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

With no annotations, the description carries full burden. It discloses the automatic 'simplified_tuning apply' after simplified_* commands. However, it does not mention that arbitrary CLI commands can modify system state, which would improve transparency for a general exec 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?

Two sentences: first sentence states the core purpose, second sentence provides crucial usage guidance. No wasted words, well-structured.

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 one-parameter tool with no output schema, the description covers purpose, usage guidelines, and a key behavioral quirk. It does not document return format or error handling, but those are implicit for CLI output. Slightly above adequate.

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 100% (command param described with example). The description adds little beyond the schema; it mostly restates the purpose. The note about simplified_* commands is the only additional semantic, but it's not about the parameter itself. Baseline 3 is appropriate.

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 'Execute an arbitrary CLI command on the flight controller and return the output,' specifying a verb and resource. It distinguishes itself from siblings like cli_dump or cli_help by being the general-purpose execution tool, and the note about set_pid_sliders further clarifies its scope.

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 explicit guidance: 'prefer the set_pid_sliders tool' for simplified_* commands, and explains the automatic behavior if used anyway. This tells the agent when to use this tool versus an alternative.

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