disable_mosfets

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

No annotations are present, so the description carries the full burden. It adds meaningful behavioral detail: returns a success confirmation, and 'all' broadcasts never return responses. It stops short of explaining what disabling MOSFETs does to motor operation or what preconditions apply, but the disclosed behavior exceeds the minimum.

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 three compact clauses: the action with a necessary state caveat, the return value, and the parameter format. It is front-loaded with the core verb and every sentence conveys non-redundant 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 one-parameter firmware command with no output schema, the description is self-contained: it states the action, the relevant initial-state caveat, the return behavior, and all acceptable motor identifiers. No critical information needed to invoke the tool is missing.

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?

The schema provides zero description for the single motor parameter, but the description fully compensates by specifying alias numbers, 16-hex-digit unique IDs, the literal 'all', and the no-response behavior for broadcasts. This is more than enough for an agent to format the argument correctly.

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 states the exact action ('Disables the MOSFETS') and frames it as a firmware command in the Basic Control group, so the tool's function is unmistakable. The verb also separates it from the sibling enable_mosfets.

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 note that MOSFETs are already disabled after initial power-on gives the agent useful context about when the call may be unnecessary. However, it never explicitly names alternatives such as enable_mosfets or states conditions for when this command should be preferred, so the guidance is only implied.

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