Scan connectable ports

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description reinforces this with 'does not pair or connect,' which is genuinely useful for an agent deciding whether it can call this freely, but it adds little else — no statement about return shape (a list of ports/devices) or whether the result reflects a live snapshot versus cached state.

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?

Three short sentences, each earning its place: what it enumerates, what it does not do, and when to use it. The read-only constraint is front-loaded immediately after the purpose, which is the right order for an agent skimming for call safety.

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 zero-required-parameter enumeration tool with full annotation coverage, the description covers purpose, side-effect profile, and usage trigger. The one remaining gap is that with no output schema there is no description of the returned structure (e.g., paired port/device lists), which an agent would need to parse results.

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?

There is only one optional parameter and the schema documents it at 100% coverage ('Also list B0-known (paired/known) receivers'). The description says nothing about includeKnownDevices or the default behavior of including known devices, so it neither compensates nor misleads — the baseline 3 applies when the schema does all the work.

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 opens with a specific verb and resource set ('Enumerate Web Serial ports and Web Bluetooth devices') and bounds the scope ('currently available to the CyberBrick app'). The clause 'Read-only — does not pair or connect' implicitly separates it from the connect_serial and connect_bluetooth siblings, so an agent can pick the right tool without opening a schema.

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?

'Use this to tell the user what hardware can be connected right now' gives a clear positive trigger. It never names the alternative tools (connect_serial, connect_bluetooth) as the next step, so the when-not/when-to-connect guidance is only implied by 'does not pair or connect.'

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