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

Goes beyond the annotations by disclosing real side effects: it 'briefly pause[s] and restore[s] previous running state' and, when save is set, writes CSV and metadata to the export directory. This is consistent with readOnlyHint=false and destructiveHint=false and gives the agent useful operational context the annotations do not.

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 with the core action front-loaded and no filler. The indentation/line-break artifact adds minor noise but nothing substantive is wasted.

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 annotations cover the safety profile. However, the description leaves the filename and include_points parameters unexplained and never explicitly routes to scan_spectrum, so it is adequate but with clear gaps for a 3-parameter instrument 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% for all three parameters, so the description must carry the burden. It explains save's file-output behavior but says nothing about filename (format, location, default naming) or include_points, leaving two of three parameters undocumented anywhere.

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: 'Snapshot current actual dBm trace,' which is concrete and distinct from a scan. The line 'Does not guarantee a fresh scan' implicitly separates it from scan_spectrum, but it never names the sibling, so differentiation is inferential rather than explicit.

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?

'Does not guarantee a fresh scan' tells the agent what this tool is not, hinting that scan_spectrum is the choice when freshness matters, but it never states that alternative or the condition that selects it. Usage is implied rather than prescribed.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds valuable behavior beyond that: firmware rounds bandwidth to available filters, and changes are not rolled back on error, which warns the agent about partial-failure state. It does not state required permissions or idempotency.

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?

Front-loads what is set, then layers three short constraint sentences with zero filler. Every sentence carries operative information (rounding, null semantics, mutual exclusion, error behavior).

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 prose. For a 5-parameter, zero-required setter, the description covers the failure mode, rounding side effect, and the auto/explicit interaction an agent needs 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 only 20% (only rbw_hz is documented), so the description must compensate and largely does: it explains the null/'None' semantics and the mutual exclusivity between auto and explicit values, which is the key trap for rbw_auto vs rbw_hz and attenuation_auto vs attenuation_db. The unit_dbm boolean and attenuation_auto flag are still explained only by their names.

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 (explicitly set) and the exact resources it acts on (bandwidth in Hz, attenuation in dB, dBm display units), plus a read-back capability. It is clearly distinguishable from read-only siblings like get_status or scan_spectrum, though it never names an alternative directly.

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 real usage rules for the parameters ('None leaves a setting unchanged', 'Auto and explicit value are mutually exclusive'), which governs correct invocation. However it offers no guidance on when to pick this tool over siblings such as get_device_info or capture_spectrum, so tool-selection guidance is only implied.

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?

Annotations declare it is not read-only and not destructive, which is somewhat surprising for a 'disconnect' action; the description resolves this by explaining the disconnect is recoverable (next device tool reconnects) and explicitly scopes the side effect ('does not change the current sweep state'). This is meaningful behavioral context beyond the annotations.

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 short clauses with zero filler, and the core action ('Release USB') is front-loaded before the recovery caveat.

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 with no parameters the definition is nearly complete. The only gap is a lack of explicit when-to-use routing relative to the many sibling device tools.

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 schema carries no semantics to supplement; the baseline for a 0-parameter tool applies. Nothing in the description is needed or missing 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?

States a specific verb and resource ('Release USB') and clarifies the mechanism by which the device comes back ('the next device tool reconnects'). This distinguishes it from siblings like list_devices or get_device_info, though it never explicitly says what the device is, relying on context.

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 mention that the next device tool reconnects implies the disconnect is temporary and safe to call, which gives an agent usable context. However, it never states when to prefer disconnecting versus simply not using the device, nor names any alternative sibling.

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?

Annotations give readOnlyHint=false but do not explain why. The description closes that gap by disclosing 'temporarily pauses readout', which tells the agent this has a transient side effect on the instrument and is not a pure read. It stops short of saying when readout resumes or whether the pause is bounded.

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 front-loaded and the side effect appended, with no filler. It is appropriately sized, though the appended clause could be expanded slightly without harming flow.

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 pausing behavior is disclosed. However, with zero parameter documentation and no usage guidance against a crowded sibling set, the definition is only minimally sufficient.

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 names no parameter (limit, min_level_dbm, min_separation_hz). 'Strongest' and 'sampled' only loosely gesture at level filtering and the limit, leaving all three parameters' meaning to be guessed from their names.

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 (find) and resource (spectrum peaks), plus the scope of 'snapshot current trace' and 'strongest sampled local maxima'. This distinguishes it reasonably from capture_spectrum/scan_spectrum, though it never explicitly names 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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives like capture_spectrum or scan_spectrum. The agent must infer from context alone when peaks should be found versus a raw capture taken.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The word 'actual' adds a genuine nuance, signaling this queries live firmware rather than a static command list, but no auth, timing, or failure behavior is described.

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 key qualifier ('actual supported') front-loaded and 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 values need no explanation, and with no parameters the schema burden is minimal. The description is sufficient for this simple read tool, though a hint about what the returned command list is useful for would round it out.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

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 (read) and resource (the connected firmware's supported console commands), which is clearly distinct from siblings like get_status, get_device_info, or list_devices. It does not explicitly name a sibling it is not, so it falls short of the 5 bar for sibling 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?

Usage is implied: call this to discover which console commands the attached firmware actually supports. There is no explicit when-to-use/when-not-to-use guidance and no alternatives are named, leaving routing to inference.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral trait not in the annotations – it connects 'lazily' and performs an identity check – but says nothing about failure modes if the identity check fails or what happens if no device is attached.

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 dense sentence with no filler, and the connection step is front-loaded before the reported fields. It is appropriately sized for a no-argument 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, so the description need not enumerate return values; it still names the key reported fields (firmware, maximum scan points). Combined with annotations covering safety, the definition is complete enough for the agent to call it correctly, with only failure behavior left implicit.

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 there is nothing for the description to clarify beyond what the schema already conveys. Baseline 4 applies.

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 concrete verb chain and resource: connect to the device, verify its identity, and report firmware and max scan points. That is far more specific than the name alone, but it does not explicitly distinguish itself from siblings like get_status or list_devices, which an agent must disambiguate on its own.

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 and no mention of alternatives. Given siblings such as get_status and list_devices, the agent gets no signal about which one to pick for device inspection; usage is only implied by the phrase 'verify tinySA identity'.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety and locality profile is fully covered. The description adds which measurement/processing domains are reported, which is modest added value beyond the annotations.

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 names the verb first and then lists the returned domains. No filler, no 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?

With zero parameters and an output schema present, return values need not be spelled out. The description covers what the call reports and is safe to invoke from the annotations, so it is complete for the agent's decision.

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 there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies a parameterless read that scopes itself to the connected device.

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 (Read) and resource (status) and enumerates the exact state it returns: sweep state, bandwidth, attenuation, display units, processing settings. It does not explicitly differentiate itself from the sibling get_device_info, which is the closest overlap.

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 exclusions, and no mention of alternatives such as get_device_info or list_devices. The agent must infer the boundary between generic device info and this sweep/measurement status from the field list 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: it does not establish a connection, and device IDs are ambiguous because STM32 identifiers can also be NanoVNAs, which affects how results should be interpreted.

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 short sentences with no filler; the core action is front-loaded and the caveat follows immediately. 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?

With an output schema present, return values need not be explained, and the description covers the non-obvious parts: no connection is opened and device IDs are not reliably typed. The only minor gap is not stating that this is the entry point preceding device-specific calls.

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 no parameters, so per the baseline there is nothing for the description to compensate for. The description adds no argument detail because none is needed.

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: enumerating serial ports and USB candidates, which cleanly separates it from siblings like get_device_info or get_status. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than being told.

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?

'Does not connect' implies this is a safe discovery step to run before connect/get_device_info, which is useful implied guidance. However, there is no explicit statement of when to choose this tool over get_device_info or get_status, leaving routing to inference.

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?

Annotations already declare this is a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds the scope qualifier 'displayed sweep', but says nothing about whether the pause is reversible (only implied by the sibling resume_sweep) or what state the sweep is left in.

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 short sentence with the action front-loaded and no wasted words. Sized appropriately for a zero-argument operation.

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 no parameters, an output schema present, and annotations covering the safety profile, the description only needs to convey the action, which it does. The missing piece is any hint about the pause/resume pairing that an agent would need to sequence calls 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate about inputs.

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 (pause) and resource (the displayed sweep), so an agent can tell what it does without opening the schema. It does not explicitly differentiate itself from the sibling resume_sweep, though the verb makes the distinction obvious.

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 pause versus when to let the sweep continue, nor any mention of the counterpart resume_sweep or preconditions such as a sweep needing to be running. Usage must be inferred entirely from the verb.

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?

Annotations already declare this is a state-changing but non-destructive, non-open-world operation, so the safety profile is covered. The description adds one genuinely useful behavioral detail beyond the annotations — that resuming also restores the frequency array — but omits whether the call fails when no sweep is paused and how it interacts with an in-progress capture or measurement.

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 the verb and resource first and the parenthetical detail last. Nothing is wasted and nothing essential is buried.

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 not be described, and the annotations cover the safety profile, so the description is nearly sufficient for a zero-argument tool. The one gap is the precondition (a paused sweep) that determines whether the call will succeed.

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 there is no parameter semantics to explain; the empty schema is fully self-consistent with the description. Baseline 4 applies since the description cannot add parameter meaning where none exists.

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 ('Resume') and a specific resource ('the instrument's configured display sweep'), which is enough to distinguish it from the sibling pause_sweep by polarity alone. It stops short of explicitly naming pause_sweep as its counterpart, so it earns a 4 rather than 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 inverse of pause_sweep, but the description never says it should be called only when a sweep is paused, nor what happens if the sweep was never paused or the device is disconnected. No alternatives or preconditions are stated.

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?

Annotations declare a non-read-only, non-destructive, closed-world operation, and the description adds real value beyond that: the device is left paused by default, resume_after restarts the display sweep, and input mode/RBW/processing are deliberately untouched. It does not state permissions or what happens on failure, but the side-effect profile is well disclosed for a mutation.

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?

Four short sentences, each carrying distinct operational information, with the core acquisition behavior front-loaded. No filler or repetition of the schema, though the sentence fragments are slightly clipped.

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 explanation, and the sweep/pause behavior is covered. The gaps are the undocumented save/filename/include_points parameters and the absence of any routing guidance against the closely named sibling capture_spectrum.

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 only 43%, so the description must compensate; it usefully clarifies the points cap (Basic <=290, Ultra <=450) and the resume_after semantics, and confirms endpoints are integer Hz. It says nothing about save, filename, or include_points, leaving three of seven parameters with no explanation anywhere.

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 and resource: acquiring a new dBm spectrum with paired frequencies/levels. It is clear what the tool returns, though it never distinguishes itself from the sibling capture_spectrum, which an agent could easily confuse it with.

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 usage through behavior notes ('default leaves device paused', 'resume_after restarts the configured display sweep'), which tells the agent when to pass resume_after. However, there is no explicit statement of when to prefer this over capture_spectrum or configure_measurement, and no prerequisites are given.

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