ble_inspect_gatt

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the core side effect ('connect'), but says nothing about whether the connection is torn down afterwards, whether pairing/bonding is required, what happens on timeout, or what platform permissions (e.g. Linux bluez) are needed. For a tool that opens a live radio connection, that leaves significant gaps.

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 tight per-argument block. Every line adds information; there is no restatement of the tool name, no filler, and the highest-value fact (what gets listed) is first.

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?

Because an output schema exists, the return shape need not be explained, and the two parameters are well covered. What remains missing is the behavioral envelope an agent needs before calling a connection-opening tool: pairing state, disconnect semantics, and failure/timeout behavior.

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%, but the description fully compensates for both parameters: 'address' is explained as a MAC (Linux/Windows) or a UUID (macOS) with an example, and 'timeout_sec' is framed as a connection timeout with its 10.0 default. This is exactly the OS-dependency detail the bare schema cannot convey. Only minor edge cases (invalid address, timeout bounds) are unmentioned.

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 gives a specific verb and resource pair: 'Connect to a BLE device and list all GATT Services, Characteristics, and their properties.' That is clearly distinct from ble_scan_devices (discovery) and ble_read_write_characteristic (value I/O). It does not explicitly name or rule out those siblings, so it stops short of a 5.

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?

Usage is only implied: the agent must infer that this is the inspection step before ble_read_write_characteristic. There is no statement about when to prefer this over ble_scan_devices, no prerequisite that the device be advertising or already known, and no exclusion guidance.

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