ftdi_i2c_scan

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

No annotations are supplied, so the description carries the full burden; it does disclose the required hardware class and that the operation probes for addresses, implying a non-destructive read, but it never states that explicitly, nor whether the bus is left in a particular state, how long a scan takes, or what happens when no devices respond.

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?

One front-loaded purpose sentence followed by a compact Args block; every line carries information. Only minor redundancy in restating a default the schema already declares.

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?

With an output schema present, return values need no explanation, and both optional parameters are documented with examples and defaults. Only edge-case behavior (empty scan results, timing, bus error handling) is left unaddressed, which is acceptable for a tool this simple.

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 supply parameter meaning and it does: ftdi_url is explained as a PyFtdi URL with a concrete example ('ftdi:///1'), and frequency_hz is given units plus the 100kHz standard-mode framing of the default. It would rate higher if it warned about invalid frequencies or URL forms.

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 names a specific verb and resource ('Scan an I2C bus ... for active slave addresses') and identifies the required hardware (FT232H/FT2232H MPSSE bridge), which plainly separates it from ftdi_i2c_transfer. It stops short of naming that sibling explicitly, so the distinction must be inferred from the verb.

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?

A bus scan is a recognizable discovery step, so its usage is implied, but the description never states when to use it versus ftdi_i2c_transfer or scan_hardware_bridges, nor does it mention prerequisites such as an attached bridge or that the bus should be idle.

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