usbtmc_clear

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

Annotations already indicate the tool is mutating, idempotent, and non-destructive. The description adds valuable context about what gets cleared (input/output buffers) and that it resets communication state. It also discloses the return structure. This goes beyond annotations and provides useful behavioral insight, so 4 is warranted.

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 succinct and well-structured. It leads with the core purpose, then usage, then parameters, then return values. Every sentence serves a purpose, and there is no fluff. It is appropriately sized for the tool's 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?

Given the simple single-parameter nature, the description covers all essential aspects: what the tool does, when to use it, the parameter meaning, and the return value. Annotations provide additional safety cues. The description is complete and leaves no significant gaps.

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?

Despite the schema description coverage being 0%, the description explicitly explains the parameter: 'device_id (int): The unique identifier returned by usbtmc_connect().' It fully conveys the meaning and origin of the parameter, effectively compensating for any schema gaps. The single parameter is well-documented.

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 the tool's action: 'Clear the device input/output buffers and reset communication state.' This is a specific verb and resource, distinguishing it from sibling tools like send/receive/query. The purpose is unambiguous and immediately understandable.

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 explicit usage context: 'Use this to recover from communication errors or stuck states.' This tells when to use the tool, but it does not mention when not to use or contrast with alternatives. Since it gives clear context without explicit exclusions, a score of 4 is appropriate.

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