lw_ble_scan_poll

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

With no annotations, the description carries the full behavioral burden, and it discloses only that a running/not-running flag is included. It does not say whether polling consumes or clears accumulated results, whether it is idempotent, what happens with an unknown or finished scan_id, or whether the call blocks — all critical for a poll-style tool.

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 tight sentence with no filler and the key state information ('whether it is still running') front-loaded alongside the payload description. It is efficient, though the loose 'sweep' wording costs a little precision.

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?

An output schema exists, so the returned payload need not be re-described. What remains missing is the lifecycle context: how scan_id is obtained, whether a scan must be in progress, and whether results accumulate or reset between polls — gaps that matter for a 1-parameter polling tool with no annotations.

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 single required parameter scan_id has 0% schema description coverage, so the description must compensate and it does not mention the parameter at all. It never explains that scan_id is the identifier returned by lw_ble_scan, which is the one piece of semantics an agent needs here.

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?

It states a verb ('Fetch') and an object ('everything a sweep has gathered so far, plus whether it is still running'), so the basic operation is inferable. However, it uses the metaphor 'sweep' instead of the 'scan' terminology that the tool name and all siblings (lw_ble_scan, lw_ble_scan_list, lw_ble_scan_stop) use, and it never distinguishes this from lw_ble_scan_list, so the boundary is left to inference.

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?

There is no statement of when to poll versus when to use alternatives such as lw_ble_scan_list, lw_ble_scan_stop, or lw_ble_wait_notification, nor any prerequisite (e.g. a scan must already be running). The description gives no exclusions or routing guidance at all.

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