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

With no annotations, the description carries the full behavioral burden. It usefully discloses two traits: a connection_id is returned on success, and the call is wrapped in an outer timeout so a stalled driver cannot hang the client. However, it omits failure modes, whether pairing is required, idempotency/duplicate-connection behavior, and the need to later disconnect.

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, front-loaded with the core action and followed by return value and timeout behavior. No filler, though the timeout sentence is the least essential of the three.

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 return values need no further explanation. But with 0% parameter coverage and no annotations, the description leaves the 'pair' parameter and connect preconditions unexplained, which is a meaningful gap for a session-establishing tool.

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 compensate for all three parameters. It explains 'address' (a MAC) and alludes to the timeout wrapping, but says nothing about the 'pair' parameter or how 'timeout_s' relates to the described outer timeout. Significant compensation gap.

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?

States a specific verb and resource: 'Open a GATT session with a peripheral, addressed by its MAC.' It is easy to distinguish from siblings like lw_ble_scan or lw_ble_disconnect, though it never explicitly names an alternative or contrast. Clear and specific, just without sibling-level differentiation.

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 contains no when-to-use, when-not-to-use, or prerequisites. It never states that this should be called before read/write/subscribe, nor whether a prior scan is required to obtain the MAC. Usage is only inferable from the tool name itself.

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

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, yet it only states that all sessions are enumerated. It does not disclose whether stale or inactive connections are included, whether the call can block, or any failure/auth conditions, leaving the agent largely uninformed about behavior.

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?

It is a single efficient sentence with no filler and the listing operation is front-loaded. It borders on under-specification rather than verbosity, which keeps it just short of a 5.

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-parameter, read-only list tool with an output schema documenting returns, the description is minimally sufficient. It does not, however, explain what constitutes a 'session' or how the list relates to the connection/status/subscription siblings, which are the main open questions.

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 tool takes zero parameters, so the baseline is 4 per the rubric. There is nothing for the description to clarify beyond the schema, which is fully specified.

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 pairs a specific verb ('Enumerate') with a resource ('every session the server currently holds'), so an agent can tell this is a read-only listing operation. However, it says 'session' while the tool name and siblings use 'connection', and it does not distinguish itself from lw_ble_connection_status or the other *_list siblings.

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 guidance on when to call this versus lw_ble_connection_status (single connection detail) or lw_ble_subscription_list / lw_ble_scan_list. The listing intent is only implied by the verb 'Enumerate', and no prerequisites or exclusions are given.

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

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

No annotations are provided, so the description carries the full burden. It discloses what is returned (liveness and identity), which implies a non-mutating read, but says nothing about error behavior when the connection is absent, permissions, or whether the call blocks on a live BLE probe.

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 compact sentence that front-loads the operation and its payload. No filler, though it is arguably under-specified rather than optimally concise for a status tool.

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 and the description sensibly summarizes the returned content rather than restating it, which is good. But it omits the meaning of connection_id and any failure-mode context, leaving real gaps for a tool in a 21-member BLE family.

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, connection_id, is not mentioned in the description at all, and schema description coverage is 0%, so nothing anywhere explains its format, source, or whether it must correspond to an active connection. The description adds no meaning beyond the schema's bare property name.

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?

States a clear verb ('Report') and a specific subject: the liveness of a session plus the peripheral's identity details. This distinguishes it in practice from lw_ble_connection_list (enumerate sessions), though the description never names that sibling or explicitly contrasts scope.

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 guidance on when to call this versus lw_ble_connection_list, lw_ble_engine_status, or lw_ble_scan_list. Usage is only implied by the word 'session', leaving the agent to infer that this checks a specific existing connection.

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

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

With no annotations, the description carries the full burden. 'Close and forget' usefully signals that session state is destroyed rather than merely suspended, which is real behavioral value. It says nothing about idempotency, behavior on an invalid/stale connection_id, or effect on other active sessions, so it remains partial.

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?

A single tight sentence with the action and the scoping constraint front-loaded and zero filler. Nothing to trim.

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 return values need not be explained. But for a state-destroying tool with no annotations, the description omits error/idempotency behavior and any confirmation of what state is cleared, leaving gaps an agent would care about.

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 compensate and largely doesn't. 'Given its connection_id' only ties the parameter to a session handle that already exists; it does not explain the format, where to obtain the ID, or what happens if it is unknown. One undocumented parameter at 0% coverage warrants a low score.

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?

States a specific verb+resource: 'Close and forget an existing GATT session', which clearly distinguishes it from siblings like lw_ble_connect and lw_ble_connection_status. However, it does not name or contrast against any alternative tool, so it stops short of the 5 bar.

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 phrase 'existing GATT session' implies the prerequisite that a connection must already be established, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., vs. lw_ble_connect for teardown of a pending connection). An agent must infer the context.

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

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

With no annotations, the description carries the full behavioral burden. It implies a non-mutating GATT traversal, but does not state that it requires an active connection, what happens on timeout, whether results are cached, or any failure behavior.

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?

A single front-loaded sentence that communicates the operation and its output scope with no wasted words.

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 return structure need not be repeated. But for a two-parameter BLE tool with no annotations and no schema descriptions, the definition omits the connection prerequisite and timeout behavior, leaving meaningful 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?

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It says nothing about the required connection_id or the optional timeout_s, leaving both parameters semantically unexplained.

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 uses a specific verb+resource ('Walk the remote GATT database') and names exactly what is returned (services, characteristics, descriptors), which distinguishes it from sibling operations like read, write, subscribe, and scan.

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 implied by 'in one call'—use this when the full remote GATT database is needed instead of individual reads. However, it never states when-not to use it or names alternative siblings such as lw_ble_read or lw_ble_dump.

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

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

With no annotations, the description carries full burden and does add value: it discloses the dump contents and the partial-failure behavior ('fail to read are reported in read_failures instead of aborting'). However, it omits the read-only/side-effect profile, connection-state prerequisites, and timeout behavior.

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?

Two tight sentences, front-loaded with the purpose and followed by the failure-handling nuance. No filler and nothing misordered.

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 moderately simple recon tool with an output schema covering return values, the description gives a clear purpose and the key failure-mode behavior. The remaining gap is the entirely undocumented parameters, which is a real but limited shortfall.

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% and the description says nothing about either parameter. Neither connection_id (the required handle) nor timeout_s (its meaning, units, or effect) is explained anywhere, so the description fails to compensate for the coverage gap.

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?

States a specific verb and resource: a one-shot recon that returns the service table, all readable characteristic values, and the negotiated MTU. The composite nature implicitly differentiates it from the granular read/discover/mtu siblings, though it never names them.

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 phrase 'one-shot ... in a single call' implies the use case (grab everything at once rather than making several calls), but there is no explicit when-to-use, when-not, or named alternative among the many read/discover/mtu siblings.

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

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

With no annotations, the description carries the full burden, and 'report' plus the enumerated observations strongly signal a non-mutating inspection. It discloses the concrete scope of what is inspected (links, scans, streams, bridge thread health), which is above-average behavioral content. It does not explicitly state that it is side-effect-free or mention any permissions, leaving a minor gap.

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?

Two sentences, both load-bearing: the first defines the report contents, the second frames the diagnostic purpose. The key resource list is front-loaded with no filler.

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 return-value explanation is not required, and a zero-parameter diagnostic needs little else. The description supplies the diagnostic rationale and the metric set, making it complete enough to call correctly; only the absence of explicit read-only framing keeps it from a 5.

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?

Zero parameters, so the schema contributes nothing to disambiguate and the baseline of 4 applies. The description correctly implies no arguments are needed by framing the tool as a self-contained status report.

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?

States a specific verb (report) and resource (engine resource usage), then enumerates exactly what is measured: live links, scans, notification streams, and I/O bridge thread health. This clearly distinguishes it as an aggregate diagnostic rather than a per-item lister like lw_ble_connection_status or lw_ble_subscription_list, though it never names those siblings explicitly.

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?

Gives a clear use context in the second sentence: diagnosing resource exhaustion in long-running sessions. This tells an agent when the tool is warranted. It stops short of naming alternatives (e.g., individual *_list/*_status tools) or stating when not to use it, so it does not reach the top band.

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

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 adds useful domain context (the ATT overhead calculation), which is genuinely helpful. However, it doesn't disclose whether the call blocks, what happens if the connection is missing, or whether a timeout is involved despite the timeout_s parameter.

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?

A single tight sentence that front-loads the primary purpose. No filler, no repetition. The technical detail about overhead is concise and relevant.

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 return values needn't be explained. However, for a 2-parameter tool with zero schema documentation and no annotations, the description is thin. It omits the timeout behavior and any usage context, leaving notable gaps for an agent trying to invoke it correctly.

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% and neither parameter is explained in the description. The required connection_id is intuitive from context, but timeout_s is entirely undocumented in both schema and description. With 2 parameters at 0% coverage, the description should compensate but does not.

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?

States a specific verb (Show) and resource (MTU agreed for a session). This clearly distinguishes it from siblings like lw_ble_read or lw_ble_write, which are data operations rather than link-layer introspection. The purpose is unambiguous, though it reads as a diagnostic call rather than part of a workflow.

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?

No guidance on when to use this versus alternatives. The sibling lw_ble_connection_status might overlap, and the description offers no disambiguation, no mention of prerequisites (e.g., an established connection), and no context on when an agent would call this.

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

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

No annotations exist, so the description carries the full behavioral burden, and it does disclose two key traits: non-blocking semantics (empty result = nothing yet) and the overflow/'dropped counter' behavior when the reader falls behind. Missing disclosure of auth requirements and any rate/polling-frequency limits keeps it from a 5.

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?

Two tight sentences, no waste, with the non-blocking guarantee front-loaded ahead of the overflow-reporting detail.

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 return-value explanation is not required. But with 0% parameter coverage and no annotations, the description is thin on the identifiers and max_items semantics needed to call a 3-param tool correctly.

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% across all three parameters. The description never explains connection_id, subscription_id, or crucially max_items (the drain batch limit, default 50), so an agent must guess the meaning of the batch-size cap and the identifiers.

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?

States a specific verb ('drain') and resource ('queued notifications') with the key qualifier 'without waiting'. It implicitly distinguishes itself from the non-polling notification sibling lw_ble_wait_notification, though it never names that alternative explicitly.

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 phrase 'without waiting' implies this is the non-blocking option versus a blocking waiter, but the description never names lw_ble_wait_notification or states when to prefer poll over wait. Usage is implied rather than made explicit.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the reply encoding, but says nothing about whether the read is blocking, what happens on a disconnected or unauthorised connection, how the timeout_s budget behaves, or what errors surface. For a BLE read this is a meaningful gap.

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 compact sentence with the action front-loaded and no filler. The trailing clause about base64/hex/byte count is largely redundant with the existing output schema, which slightly dilutes it.

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 return values need not be explained, and the tool is a simple read. Still, with no annotations, no parameter documentation, and no connection precondition stated, an agent lacks the context to call it correctly in failure or timeout scenarios.

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% across three parameters (connection_id, char_uuid, timeout_s), so the description must compensate and does not: it explains none of them. timeout_s in particular is left entirely ambiguous despite having a default.

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?

States a specific verb and resource: 'Fetch a characteristic's contents.' The word 'characteristic' naturally distinguishes it from the sibling lw_ble_read_descriptor and from lw_ble_write, but it doesn't explicitly name those siblings or route between them.

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?

No when-to-use guidance, no stated prerequisites (e.g. an active connection from lw_ble_connect), and no mention of when to prefer lw_ble_read_descriptor or lw_ble_poll_notifications instead. The required connection_id hints at a precondition but nothing is explained.

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

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

No annotations are provided, so the description carries the full burden. The verb 'read' makes the non-mutating nature inferable and the handle provenance is disclosed, but it says nothing about error behavior for invalid/foreign handles, connection prerequisites, or how the timeout affects the operation.

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?

A single tight sentence with the operation and its key parameter front-loaded, and the dependency clue appended without waste. Nothing redundant or padded.

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 return values need not be explained. Still, with no annotations and 0% schema coverage, the description leaves the connection_id and timeout parameters and the failure modes unaddressed, which is a real gap for an agent wiring this into a BLE session.

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 compensate for all three parameters. It explains the 'handle' parameter's origin well, but leaves 'connection_id' (which connection to target) and 'timeout_s' (default 10, in seconds) completely undocumented in both schema and description.

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?

States a specific verb and resource ('Read a descriptor's bytes') plus the keying parameter ('by its attribute handle'), which implicitly separates it from the sibling lw_ble_read that works on characteristics. It does not name that sibling, so it falls short of explicit differentiation.

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?

Provides a useful prerequisite/pipeline hint ('handles come from lw_ble_discover'), telling the agent how to obtain the required handle. However, it gives no when-to-use versus lw_ble_read, no when-not-to-use, and no note that an active connection must exist.

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

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

No annotations exist, so the description carries the full burden and does disclose the key behavioral traits: the call is asynchronous, returns a handle immediately, self-terminates within timeout_s, and the scan is passive. It omits permissions/auth requirements and any rate-limit or concurrency caveats, which is a modest gap for a radio-level operation.

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, front-loaded with the action and return contract, then the lifecycle bound, then the follow-up tools. No filler; every clause carries information.

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 return-value detail is not required, and the async handle is mentioned anyway. However, with zero annotation coverage and zero schema description coverage, the unexplained name_filter and service_uuid parameters leave the definition incomplete for correct invocation.

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 all parameter meaning. It explains timeout_s well (bounded 1–60) but leaves name_filter and service_uuid entirely unexplained, so two of three parameters remain opaque. Partial compensation only.

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?

States a specific verb ('kick off') and resource ('passive BLE discovery sweep'), and immediately clarifies the async return contract (a scan handle). This distinguishes it cleanly from siblings like lw_ble_scan_poll and lw_ble_scan_stop, which it names as the follow-up/abort paths.

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?

Routes the agent explicitly to lw_ble_scan_poll for results and lw_ble_scan_stop for early abort, which is strong when-to-use guidance. It does not state when this tool should be avoided in favor of a non-scanning alternative (e.g., lw_ble_scan_list), so it stops short of full exclusion guidance.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the key trait that results are not filtered by completion state, but it says nothing about ordering, result limits, or whether the list is a snapshot, so the disclosure is only partial.

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?

A single tight sentence with the scope qualifier front-loaded. The only minor cost is the idiosyncratic term 'discovery sweep' instead of 'scan', which briefly risks confusion with the lw_ble_discover sibling.

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?

The tool is a no-parameter read/list with a declared output schema, so return-value explanation is unnecessary. The description covers what the tool returns and that it is unfiltered, which is sufficient for an agent to call it; only minor terminology alignment is missing.

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 tool takes zero parameters, so the baseline of 4 applies; there is nothing parameter-related for the description to clarify or compensate for.

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 states a specific verb (Show/list) and resource (every discovery sweep = BLE scan), and adds the scope detail 'finished or not'. It does not explicitly differentiate itself from close siblings such as lw_ble_scan, lw_ble_scan_poll, or lw_ble_scan_stop, so it falls 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: an agent can infer this is the exhaustive-enumeration tool for sweeps because it claims to return all of them regardless of state. There is no explicit when-to-use statement, no mention of when to prefer lw_ble_scan_poll instead, and no prerequisites.

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

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.

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

With no annotations, the description carries the full burden, and it does usefully disclose that buffered results are returned upon stopping rather than discarded. However, it says nothing about what happens if the scan is already stopped or unknown, whether the scan is removed from lw_ble_scan_list, or any error/permission behavior — significant gaps for a state-mutating tool with zero annotation coverage.

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?

A single front-loaded sentence that states the action first and the return consequence second, with no filler or redundancy.

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?

The presence of an output schema excuses the description from explaining return values, and it does convey the core stop-and-collect behavior. But for a tool whose only parameter is undocumented and which has no annotations, the definition is thinner than the complexity warrants.

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 coverage is 0% for the single required 'scan_id' parameter, so the description must compensate and does not. It never mentions the identifier, its format, or where to obtain it (presumably from lw_ble_scan or lw_ble_scan_list), leaving the only argument undocumented.

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 ('End') and resource ('a sweep'), plus the side effect of returning recorded results, so an agent can tell it terminates an active scan. The word 'sweep' loosely maps to the ble_scan family, and it does not explicitly contrast itself with lw_ble_scan_poll or lw_ble_scan_list, so sibling differentiation is only implied.

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?

It implies a scan must already be running ('End a sweep now'), but states no explicit when-to-use condition, prerequisites, or alternative (e.g., polling vs. stopping). An agent must infer the workflow context from the sibling names alone.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose meaningful stateful behavior: this starts an ongoing stream and yields a subscription_id consumed by later management calls. It omits other relevant traits such as required connection state, whether a characteristic must support notify, what happens on duplicate subscription, and error/timeout behavior.

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?

A single tight sentence that front-loads the action and then the return contract. It is appropriately sized and has no filler, though it could have spent a few more words on the missing parameter semantics without becoming bloated.

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 return-value documentation is not required, and the description still usefully flags the subscription_id. But with 3 parameters at 0% schema coverage and no annotations, the definition leaves an agent guessing about connection/characteristic references and timeout behavior, so it is only minimally complete.

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 compensate, and it largely does not. It never names connection_id or char_uuid explicitly (only alluding to 'a characteristic') and gives no meaning at all for timeout_s, despite its default of 10 seconds being non-obvious for a subscription that conceptually persists.

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 states a specific verb+resource ('Begin receiving notification events from a characteristic') and even names the artifact it produces (subscription_id). It is clear on its own, but it does not explicitly distinguish itself from close siblings like lw_ble_wait_notification, lw_ble_poll_notifications, or lw_ble_unsubscribe, which an agent could easily confuse with a subscribe action.

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 implied by the streaming semantics ('Begin receiving notification events') and the note that later calls use the returned subscription_id to manage the stream. However, there is no explicit guidance on when to subscribe versus polling (lw_ble_poll_notifications) or waiting (lw_ble_wait_notification), and no preconditions such as an existing connection or enabled notifications.

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

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

No annotations are provided, so the description carries the burden. 'Show' and 'currently holding' imply a non-mutating snapshot of live state, which is useful framing, but it never states this is read-only, whether the list reflects only this session's subscriptions, or how stale the snapshot is. Adequate for a zero-param read, but thin.

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?

A single front-loaded sentence with no filler; every word ('every', 'currently', 'holding') does work.

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 return values need not be described, and there are no parameters to document. The only missing piece is how this list relates to lw_ble_unsubscribe and lw_ble_subscribe, which would help an agent act on the result.

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 tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies per the zero-param rule.

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?

Names a specific verb ('show') and resource ('notification stream'), and the word 'every' conveys exhaustive listing of current subscriptions. It is distinguishable from sibling lw_ble_subscribe (which creates streams) and lw_ble_poll_notifications/lw_ble_wait_notification (which consume them), though it does not explicitly name those siblings.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as lw_ble_connection_list or lw_ble_unsubscribe. The agent must infer that this is the introspection call to run before tearing down subscriptions.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one meaningful trait beyond the name: buffered data is released (i.e., discarded), which signals potential data loss. However, it says nothing about failure modes (e.g., unsubscribing an unknown subscription_id), whether the subscription becomes invalid, or auth/connection requirements.

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?

A single front-loaded sentence with zero filler; the verb and consequence come first. It is efficient, though the extreme brevity leaves information holes rather than wasting words.

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 state-mutating tool with no annotations and 0% parameter coverage, the description is too thin. An output schema exists so return values need not be explained, but prerequisites, failure behavior, and parameter meanings are all missing.

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% across three parameters (connection_id, subscription_id, timeout_s), and the description adds no meaning for any of them. The agent gets no hint that subscription_id must identify an existing subscription or what timeout_s governs.

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 pairs a specific verb ('stop') with a specific resource ('a notification stream') and adds the consequence of releasing buffered data. It is clearly the inverse of lw_ble_subscribe, so an agent can place it without opening schemas, though it doesn't explicitly name the sibling.

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 when-to-use or when-not-to-use guidance, and no mention of the natural alternative (lw_ble_subscribe) or of related tools like lw_ble_subscription_list or lw_ble_poll_notifications. The agent must infer that this is called to tear down a subscription.

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

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

With no annotations, the description carries the full burden. It does disclose the key behavioral trait: it blocks up to timeout_s and returns null on timeout. However, it omits that a subscription must first exist, and does not clarify whether concurrent calls, reuse across calls, or buffered notifications are handled.

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?

A single tight sentence that front-loads the blocking wait, the timeout parameter, and the null-on-timeout outcome. No wasted words.

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 return format needn't be explained, and the description still usefully states the null-on-timeout case. But with no annotations and two undocumented required identifiers, the definition is only minimally complete for a blocking-wait tool.

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 three parameters (connection_id, subscription_id, timeout_s) are undocumented in the schema. The description covers timeout_s ('up to timeout_s') and hints at the return or null, but adds no meaning for connection_id or subscription_id. Partial compensation for a 0%-coverage schema.

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?

States a specific verb (wait) and resource (notification) and its blocking semantics with a timeout and return shape. It is distinguishable from lw_ble_poll_notifications, though it never names that sibling explicitly, so the differentiation relies on the reader inferring 'wait' vs 'poll'.

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 explains the wait behavior but gives no guidance on when to choose this over lw_ble_poll_notifications, which is the obvious competing tool in the sibling list. No prerequisites (a prior subscribe) are mentioned.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the acknowledged-vs-unacknowledged write tradeoff via with_response, but omits other material traits for a BLE write: whether it requires an active connection, MTU/chunking limits, error behavior on failure, and the role of timeout_s.

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?

Two tight sentences, front-loaded with the core action and then the two key options, with essentially no filler. The compression is effective, though it comes at the cost of omitting several parameters that also needed coverage.

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 return values need not be described. But for a 6-parameter mutation tool with no annotations and 0% schema coverage, the description covers only half the parameters and none of the connection/MTU preconditions, leaving gaps an agent would need to guess at.

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 is the only source of parameter meaning. It defines data_b64, data_hex, and with_response clearly, but leaves char_uuid, connection_id, and timeout_s entirely unexplained, so half the parameters remain opaque.

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 ('Send bytes to a characteristic'), which clearly separates it from descriptor-writing and read siblings in the BLE family. It stops short of explicitly naming the closest alternative (lw_ble_write_descriptor), so differentiation is inferable rather than stated.

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?

It explains two in-tool choices well: encoding (base64 vs hex) and write mode (with_response vs fire-and-forget). However, it gives no guidance on when to choose this tool over siblings like lw_ble_write_descriptor or lw_ble_read, and no preconditions (e.g. an existing connection) are mentioned.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing: 'store bytes' implies a mutation but says nothing about required permissions, error behavior on an invalid handle, whether the write is acknowledged, or how timeouts are surfaced. For a write tool with zero annotation coverage this is a meaningful gap.

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?

A single efficiently packaged sentence that front-loads the operation and follows with the encoding constraint. It is well sized, though the second clause mixes behavior with parameter detail.

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 return values need not be described, but for a mutating BLE tool with no annotations and 0% parameter coverage the definition leaves too much unspecified: connection requirements, error/timeout semantics, and the remaining three parameters.

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 compensate, and it only partially does: it explains that the payload is base64 or hex, which hints at data_b64 vs data_hex. It says nothing about connection_id, timeout_s, handle semantics, or the mutual exclusivity of the two encoding parameters.

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?

States a concrete verb and resource ('store bytes into a descriptor') plus the addressing mechanism ('addressed by handle'), which separates it from the sibling lw_ble_write that targets characteristics. It stops short of naming that alternative explicitly, so differentiation is structural rather than stated.

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 when-to-use guidance, no prerequisites (must an active connection exist?), and no mention of the alternative lw_ble_read_descriptor or lw_ble_write. The agent must infer the use case purely from the tool name.

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