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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description still adds substantive behavior: the 5000-line ring buffer capacity, the fact that only lines captured after attachment exist, the redaction policy for tokens/keys/PINs/certs, and that B0 traffic and keepalives are suppressed unless includeNoise. These are exactly the constraints an agent needs to interpret sparse or missing output.

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 the resource and capture window, then the polling pattern, then the noise caveat; each sentence carries distinct operational information. The trailing 'Read-only' is redundant against readOnlyHint but costs almost nothing.

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 5-param, zero-required read tool with no output schema, the description covers capture window, capacity, redaction, and filtering. The one soft gap is that it only implicitly signals that responses carry a lastSeq cursor and the line/seq shape the agent must parse to continue polling.

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 100%, so grep, limit, since, levels, and includeNoise are all already documented in the schema. The description reinforces since-as-polling-cursor and includeNoise noise control in workflow terms but adds little semantic detail beyond the schema text. Baseline 3 is appropriate.

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 the CyberBrick app's renderer console,' and scopes which portion of it is available ('captured by this MCP server since it attached'). No sibling tool in the list returns console logs, so the resource is unambiguous against tools like device_status, cb_health, or flash_check.

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?

Explicitly describes the intended workflow: poll with since=<lastSeq> to follow long-running tasks, naming flash_config with hardwareMappings and its upgrade → send config → pairing sequence as the motivating case. It gives clear when-to-use context but names no exclusion or alternative log source (there is none in the sibling set), so no explicit when-not 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely new behavioral context by disclosing that results are aggregated from three underlying device commands (B0 SYSTEM_VERSION, GET_BOARD_INFO, GET_BOARD_TYPE), which explains the composite/latency profile. It doesn't say what happens if one sub-read fails or if the device is unreachable.

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: the scope ('one device') and the returned fields are front-loaded, and the data-source clause is tucked at the end. 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?

With no output schema, the description carries the return-value burden and does so by naming the aggregated fields. Combined with annotations and a fully documented single parameter, an agent has nearly everything needed; only error/partial-failure behavior 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?

Only one parameter exists and the schema documents it fully (100% coverage, including that it is a bluetoothDeviceId from device_list). The description adds nothing about device_id, so the baseline 3 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?

Names a specific verb+resource ('Aggregated board info for one device') and enumerates exactly what's returned: firmware/loader versions, hardware string, project string, SN, board type. It doesn't explicitly contrast with sibling readers like device_detail or device_status, which keeps it out of 5 territory.

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 tool for reading a single device's board identity, but there is no statement of when to prefer it over device_detail, device_status, or device_config_get, nor any prerequisites such as the device needing to be connected.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds value by naming exactly what is probed (CDP endpoint, app version, renderer bridge, device count), confirming it is a diagnostic probe rather than 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?

Two short sentences, zero waste, with the core checks front-loaded and the 'call first' directive appended where it is easy to act on.

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?

No output schema exists, so the description carries the return-value burden; it lists the facets checked but does not describe the result shape (e.g., pass/fail vs. values). For a simple parameterless diagnostic this is nearly sufficient but leaves a small gap in what the response looks like.

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. Schema coverage is 100% and empty, consistent with the 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 (Check) and resource (CyberBrick app health) and enumerates the concrete checks: CDP endpoint live, app version, renderer bridge access, device count. This clearly distinguishes it from sibling diagnostic tools like app_logs or device_status.

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?

"Call this first" gives explicit sequencing guidance for an agent about to interact with the CyberBrick app. It lacks explicit when-not-to-use conditions, but the entry-point framing is clear 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?

Goes well beyond the annotations by disclosing the single-instance lock, endpoint reuse behavior, that killing discards unsaved work, and the unsandboxed-shell constraint. The only minor gap is not describing what the tool returns on success (e.g. endpoint URL) — a 4 rather than 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?

Three tight sentences plus a NOTE, front-loading the core action before the failure mode, the destructive caveat, and the environment constraint. Every sentence carries distinct operational value.

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 annotations carrying the destructive/idempotency profile and the schema documenting both params, the description still supplies the crucial environmental prerequisite (unsandboxed shell) and consent requirement. Nothing an agent needs to invoke it safely 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?

Schema coverage is 100%, so both parameters are already documented, including the default timeout and the destructive nature of kill_existing. The description reinforces the kill_existing consent requirement but adds no syntax or extra meaning beyond the schema, matching the baseline 3.

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 (launch) and resource (CyberBrick desktop app) plus the distinguishing detail that it starts with the CDP debug port on 9223. This is clearly separable from siblings like window_list, cb_health, or project_open_editor.

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?

Explicit about conditions: reuses a reachable CDP endpoint, fails if the app runs without the debug port unless kill_existing=true, and must run from an unsandboxed shell. It also names the required user-consent precondition before killing, leaving nothing 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 flag non-readonly, non-idempotent, open-world, so the safety profile is covered; the description still adds real value by naming what the mutation is ('pairs a device'), describing the scan filter and the no-UI auto-selection, and noting that timeout cancels the chooser while the B0 probe has a separate budget. Only gap is the absence of stated permission/auth or failure semantics.

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-loaded with the action and the key consequence ('MUTATING') packed into a single dense sentence plus a trailing verification hint. Some internal identifiers (BluetoothDeviceManager.requestDevice, B0 probe, manufacturer data prefix) are implementation noise, but they are compressed into parentheses rather than expanded.

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?

All three params are optional and fully schema-documented, so the description's remaining burden is what happens and what comes back; it covers the flow, the side effect, the timeout abort, and points to device_list for verification. Without an output schema it could say more about what a successful resolve returns, but an agent has enough to call 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 100%, so deviceId precedence, deviceName substring matching, and timeoutMs budget are already fully documented in the schema. The description adds no parameter-level detail beyond what the structured fields provide, which is the baseline-3 case.

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?

Specific verb and resource wrapped in the actual mechanism: 'Drive the app's real add-device flow... starts a BLE scan filtered to CyberBrick devices... then auto-selects the matching device'. The BLE-scan-and-auto-select framing cleanly separates it from connect_serial and connect_scan_ports in the sibling set.

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?

Clear context for when to reach for it (BLE add-device pairing, no UI interaction needed) and a follow-up instruction to verify with device_list. It never states an explicit exclusion, e.g. use connect_serial for wired boards or device_ble_heal for repairing an existing link, so the agent must infer the boundary.

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

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

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

With annotations already declaring readOnlyHint=false, idempotentHint=true and destructiveHint=false, the description adds real meaning: it clarifies that the mutation is only app-side port selection ('Opens nothing on the board'), and explains the board-matching rule (USB serial number = chip MAC, matched against GET_DEVICE_WIFI_MAC). It stops short of covering what happens when no port is found, but the safety profile is well resolved.

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-loaded with the action and mechanism, then the return value, then the critical scope caveat — no filler sentences. It is dense and long-ish per sentence (function names inline), but every clause carries selection-relevant 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?

No output schema exists, so the description's explanation of the return (port metadata plus the associated BLE-connected board) is necessary and present. Combined with the explicit non-effect on the board and the scoping to the flasher feature, an agent has everything needed to call and interpret it.

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 schema has zero parameters and 100% description coverage, so there is nothing parameter-level for the description to compensate for; baseline is 4. The description does note that selection is automatic with strategy "first", which explains why no arguments are 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?

States a specific verb (auto-select) and a specific resource (Web Serial / USB-C port) and adds the exact IPC mechanism used (window.electron.ipcRenderer.autoSelectSerialPort, strategy "first"). It is clearly separable from siblings connect_bluetooth and connect_scan_ports, and the description also says what it returns.

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?

Explicitly scopes the tool to the USB flash / rescue flasher feature and states the exclusion: config, pairing, upgrades and every other device tool go over Bluetooth, and this does not make a board usable by other tools. That is exactly the when-to-use / when-not-to-use routing an agent needs against connect_bluetooth.

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 non-read-only, idempotent, non-destructive, so the description's marginal value is in explaining that only the in-memory connectionCount is rewritten ('on live devices', 'the state markBluetoothDevice would have set') and that no BLE traffic occurs — useful disclosure beyond the structured fields. It stops short of saying whether the reset survives a reboot or what the call returns on success/failure, which matters for a mutating tool with no output schema.

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, front-loaded with the mutation, followed by the precondition — no filler. Dense internal jargon ('markBluetoothDevice', 'connectionCountOk') is justified since it maps to sibling tool fields, though it slightly narrows readability.

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-param, no-output-schema repair tool the description covers what changes, why it helps, and when to invoke it. The only gap is the absence of any hint about the call's result/confirmation, which an agent might want before deciding to re-run.

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 the schema is fully covered, so the baseline applies. The description correctly implies no arguments are needed by framing the fix as a targeted state repair rather than a configurable operation.

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 ('Reset ... BluetoothDevice.connectionCount to 0') with the precise condition being fixed (non-finite NaN/undefined) and the exact effect. It also distinguishes itself from siblings by referencing device_ble_state as the diagnostic counterpart, so an agent can place it in the toolset without opening other schemas.

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 an explicit trigger ('Run before upgrades/pairing when device_ble_state shows connectionCountOk=false') and an explicit exclusion ('No BLE I/O'), which routes the agent away from connect_bluetooth/connect_serial. Nothing is left 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, idempotentHint, non-destructive, so the safety profile is covered and the trailing 'Read-only' is redundant. The description does add genuine context about what the returned signal means (a failed connectionCount implies every reconnect, including enterLoader during upgrades and BLE drops, will fail), which is useful behavioral insight. It does not describe freshness/polling behavior or the shape of the response.

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 what is reported before the failure-mode caveat. Only waste is the closing 'Read-only', which merely repeats readOnlyHint=true from the annotations.

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 output schema, the description must carry the return-value burden, and it names the key fields plus the semantics of the critical connectionCountOk flag and its remediation. It does not enumerate the full response shape or whether results cover all devices or one, which is a minor gap given the 'per device' phrasing and empty input schema.

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 there is no parameter meaning to convey and baseline 4 applies. The description wisely spends its space on interpreting returned values instead.

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 ('Live BLE link state per device') and enumerates the exact facets it reports: GATT connected, store vs. manager status, pool membership, loader mode, connectionCount. It does not explicitly contrast itself with the adjacent device_status / device_pool_state tools, so an agent must infer the boundary, but the reported field list makes the tool's niche clear.

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 concrete usage signal: when connectionCountOk=false, reconnect attempts will fail with RECONNECTION_INTERRUPTED, and the fix is device_ble_heal. That routes the agent to the correct sibling for remediation. It stops short of saying when to prefer this over device_status or device_pool_state, so no explicit exclusions or alternatives beyond the heal path.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is well covered. The description adds the file_size>0 precondition and the reqType context, but it repeats 'Read-only' and does not describe return shape, block size, or error behavior. With rich annotations, this is adequate but not especially informative beyond structured fields.

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?

The description is two compact sentences and front-loads the core operation. The reqType detail and precondition are useful and there is no wasted prose.

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 simple two-parameter read tool with strong annotations, the description is sufficient to invoke the tool. However, there is no output schema, and the description does not explain what a block contains, its size, or the response shape, leaving interpretation of the return value under-specified.

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 100%, and both parameters are documented in the input schema: device_id comes from device_list and index is 0-based. The description adds no parameter-specific meaning beyond that schema. Baseline 3 is appropriate because the schema does the parameter work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: fetch one board-config file block. It also ties the operation to the underlying GET_DEVICE_CONFIG reqType and distinguishes it from device_config_get by noting that it fetches one block after file_size>0. It does not explicitly distinguish itself from device_config_read, so it is strong but not fully sibling-differentiating.

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 provides a clear precondition: use after device_config_get reports file_size>0. That gives the agent actionable sequencing guidance. It does not explicitly state when not to use it or name an alternative such as device_config_read, so it falls short of full alternative routing.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value on top: the underlying request type and the special file_size=0 sentinel value, which the agent cannot get from 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?

Three compact fragments, front-loaded with the resource and the protocol call, then the sentinel semantics and the read-only flag. No waste, though the raw reqType jargon is unexplained and somewhat cryptic without protocol context.

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?

There is no output schema, so the description should indicate what metadata is returned (filename, size, timestamp, etc.). It only discloses the file_size sentinel, leaving the shape of the response largely unspecified for an agent that must decide whether to call this before reading config.

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?

Only one parameter and schema coverage is 100%, with the schema itself explaining that device_id comes from device_list. The description adds nothing about the parameter, so the baseline 3 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+resource: retrieves board config file metadata, with the underlying protocol named (GET_DEVICE_CONFIG reqType=GET_FILE_INFO). It implicitly distinguishes itself from siblings like device_config_block and device_config_read by returning metadata rather than content, though it does not name 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?

There is no explicit when-to-use or when-not guidance. The 'file_size=0 means no config stored' note hints at a pre-check use case before reading or writing config, but the agent must infer that the alternative tools (device_config_read, device_config_block) are the follow-ups.

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 cover read-only, idempotent and non-destructive, so the bar is lower, and the description still adds real mechanism: the read is synthesized from one info call plus a call per block, and the result is trimmed to file_size. The 'Read-only.' closing restates the annotation rather than adding, but the aggregation cost and trimming behavior are genuinely useful disclosures.

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 dense sentence that front-loads the resource and the mechanism, followed by a short safety tag. No wasted hedging, though the parenthetical protocol-level detail is heavier than most readers need.

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?

There is no output schema, and the description compensates by naming the return contents (file_size-trimmed bytes, MD5, parsed config JSON). For a single-parameter read tool with full annotation coverage, that is essentially complete; only the multi-call cost/failure behavior is unstated.

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?

Only one parameter and schema coverage is 100%, with the schema itself documenting device_id as a bluetoothDeviceId from device_list. The description adds nothing about the parameter, so the baseline 3 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 and resource (read back the whole board config file) plus exactly what it assembles: GET_FILE_INFO plus every GET_FILE_BLOCK, trimmed to file_size. By saying 'whole ... file' and referencing flash_config's md5, it distinguishes itself from the per-block sibling device_config_block and from device_config_get without the agent opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'compare with flash_config's md5' signals the verification workflow, but it never explicitly says when to choose this over device_config_block or device_config_get, nor when-not to use it. An agent can infer the whole-file use case but gets no explicit routing rule.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so 'Read-only' in the description is redundant. It adds some value by specifying what 'detailed status' includes (connect state, loader mode, connection-pool entry), but does not describe error behavior for unknown devices or return format.

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, front-loaded with the action and the status fields inspected. There is no filler; the trailing 'Read-only' is redundant but does not bloat the description.

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 simple one-parameter read tool with rich annotations and no output schema, the description is largely complete: it names the inspected facets and scope. It does not state what happens for an unknown device_id or whether all three status fields are always present, which is a minor gap.

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 sole device_id parameter is fully documented in the schema, including its provenance from device_list. The description adds no further syntax, format, or validation semantics beyond what the schema already provides, so baseline 3 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 specific verb ('Get') and resource ('detailed status') scoped to one device, and enumerates the status facets returned. It distinguishes itself from list-oriented siblings such as device_list, but not from close siblings like device_status or device_pool_state.

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 provides no explicit when-to-use or when-not-to-use guidance; 'Read-only' is a property, not a routing rule. It does not name alternatives such as device_status or device_list, leaving selection largely to inference from the name.

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, idempotentHint, and destructiveHint=false, so the trailing 'Read-only' is redundant repetition rather than added value. The one genuine addition is naming the zustand deviceListStore, which hints this reads client-side app state rather than performing a live scan – but it never states that explicitly or says whether results are cached/stale.

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 scope first; nothing is padded. The only waste is the trailing 'Read-only.' clause, which merely restates the readOnlyHint annotation.

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 no-parameter listing tool with no output schema, the description is minimally sufficient to call it. It omits what a listed device looks like (id, name, connection state), whether the list reflects live hardware or cached store contents, and whether an empty list is possible – gaps that matter because no output schema defines the return shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading param language is present.

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 ('List devices known to the CyberBrick app') and even names the backing store, so the operation is unambiguous. It does not differentiate itself from nearby siblings like device_detail, device_status, or device_pool_state, so an agent must infer that this is the broad enumeration versus per-device reads.

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 guidance, no prerequisites, and no named alternative. With ten device-related siblings in the list, an explicit 'use device_detail for one device, device_pool_state for pool membership' would have removed real ambiguity.

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, idempotentHint, and destructiveHint=false, so the trailing 'Read-only' largely restates structured data. The description does add that the observation is of an 'internal' pool returning size and ids, which gives behavioral context the annotations cannot, but nothing on freshness, cost, or side effects.

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, front-loaded with the resource and scope, with no filler. The 'Read-only' sentence duplicates an annotation hint, which is the only wasted element.

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?

No parameters, no output schema, and rich annotations mean little burden on the description. It compensates for the missing output schema by naming the returned data (size + ids), leaving only minor gaps such as the shape of the id list.

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. Baseline for a parameterless tool is 4.

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 ('Inspect') and a precisely scoped resource ('the internal Bluetooth connection pool') and even declares the payload ('size + ids'). It is distinguishable from siblings like device_ble_state or device_status, though it never explicitly contrasts itself with 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?

There is no statement of when to use this tool rather than the adjacent device_ble_state, device_status, or device_detail tools. Usage is only implied by the word 'inspect'; an agent must infer the selection rule from the name 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, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful behavioral context by listing the exact allowed methods and commands and stating that other inputs are refused. It does not describe auth requirements or return format, but the allowlist/refusal behavior is substantial added value.

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?

The description is a single dense sentence with the core action front-loaded and no wasted prose. The parenthetical lists are long but necessary to define the allowlist, though they make the sentence less scannable.

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 has only two parameters, full schema description coverage, and rich annotations covering safety. The description supplies the crucial allowlist and refusal rule, which is enough for correct invocation. The main remaining gap is that it does not explain how B0 commands should be passed within args or when to prefer specialized sibling 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?

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by enumerating valid method names and B0 command identifiers, which effectively supplies an allowlist that the schema does not declare as an enum. It still does not explain how the args array should be structured for sendGetMessage or how commands map into arguments.

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: call a read-only window.app.local method. It also enumerates the permitted methods and B0 commands, so an agent can understand the tool's scope. However, it does not explicitly distinguish this generic escape hatch from specialized sibling tools such as board_info, device_status, or device_config_get.

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 gives constraints for use: only the listed methods and commands are allowed, and anything else is refused. It does not say when to use this tool versus the many device-specific sibling tools, nor does it give explicit routing guidance for common read operations.

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, idempotentHint, and destructiveHint=false, so the 'Read-only' note adds nothing new. The description says nothing about what the 10 bytes encode, error behavior for an unreachable device, or whether a connection is required — the substantive behavioral gaps for a hardware query.

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 terse fragments with no filler, and the resource identity comes first. The only wasted token is 'Read-only', which merely repeats the annotation.

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?

There is no output schema, and the description only hints at the payload ('10 bytes') without explaining how to interpret the status vector or its fields. For a single-parameter read tool this is borderline adequate but leaves the return value opaque.

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?

With a single parameter and 100% schema description coverage, the schema already explains device_id and its provenance ('from device_list'). The description adds no extra semantics, so the baseline 3 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 names the resource (ADC/channel status vector, DEVICE_STATUS, 10 bytes) but supplies no verb, relying on 'Read-only' to imply retrieval. It does not differentiate from siblings that also report device state, such as device_pool_state or device_ble_state, leaving the agent to guess which status it returns.

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 call this versus the many sibling state tools (device_pool_state, device_ble_state, device_detail, board_info). No prerequisites are given, such as whether the device must be connected or flashed first.

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?

The annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that changes immediately apply to the editor config and repeats the mutating nature, but does not disclose failure behavior, reversibility, or permission requirements 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?

The description is three short sentences with no waste. It front-loads the core action and examples, then adds the immediate-effect warning and the prerequisite lookup guidance.

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 two-parameter mutating tool with no output schema, the description covers purpose, immediate application, and the need to consult firmware_edit_actions. It does not explain return values or error behavior, but the annotations already carry the core safety profile and the schema is fully documented.

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 100%, so the schema already documents both parameters. The description adds meaningful context by naming example actions, describing args as positional, and pointing to firmware_edit_actions for exact signatures and enum values such as receiverKey/actuator.

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: it calls a single firmware store action on the app store, with concrete examples. It distinguishes itself from firmware_edit_actions as the executor versus the discovery tool, though it does not explicitly differentiate itself from firmware_config_set.

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 gives a clear prerequisite: use firmware_edit_actions first to obtain the exact argument signature. It also states that the action immediately applies to the editor config and is mutating, which gives useful usage context, but it does not name when not to use this tool versus related siblings like firmware_config_set.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by identifying the exact data source and clarifying that the returned config is the pre-burn state, but it says nothing about the shape/contents of the config or caveats such as uncommitted edits.

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, front-loaded with the action and resource, then the source and the semantic meaning. The closing "Read-only" mildly duplicates the annotation but is negligible.

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?

No output schema exists, so the description is the only place an agent could learn what the firmwareConfig object contains or how it relates to the editor state; it doesn't provide that. For a zero-parameter read tool the basics are covered, but the return payload remains opaque.

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 are no semantics to document and the baseline is 4. Nothing in the description misleads 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 and resource ("Read the current firmwareConfig") and even names the underlying source (window.app.useFirmwareConfigStore). It doesn't explicitly differentiate itself from nearby siblings like device_config_get or firmware_config_edit, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"This is what would be burned to the board" implies the inspection use case, but there is no explicit when-to-use guidance and no named alternative for the modify path (firmware_config_edit, firmware_config_set, firmware_config_load_template). Usage is only inferable.

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?

Goes well beyond the annotations by disclosing the deferred-commit model: the editor becomes modified, nothing is written to the project list or board until project_save/flash_config, and identity fields are retained by default. This is the key non-obvious behavior for a mutating tool and is not derivable from readOnlyHint=false or destructiveHint=false.

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-loaded with the action and the key constraint, and every clause carries information. It is a single dense run-on with parentheticals and semicolons, which is slightly harder to scan than it could be, but nothing is redundant.

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?

No output schema exists, and the description covers what an agent needs: what state changes, what does not change yet, how identity handling works, and which tool commits the change. The 'MUTATING' tag reinforces that this is staged, not persisted.

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 100%, so the baseline is 3, but the description adds real meaning by explaining the consequence of keepIdentity's default (id/name preserved so project_save overwrites) rather than restating the schema's 'keep the current project id/config_name/design_id/region'.

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 ('Replace the editor config with one of the app's built-in project templates') and explicitly ties the payload to project_create's data set, so an agent can distinguish it from template-editing siblings like firmware_config_edit and from project_create itself.

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?

Explains the two operating modes via keepIdentity (overwrite the loaded project vs. load as an unsaved new config) and names the downstream follow-ups project_save and flash_config. It does not explicitly say when to prefer project_create or project_import instead, but the selection context is clear.

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 no open-world access, so the description's "MUTATING" restates structured data; however "Immediately applies" adds real value about the lack of a pending/confirm phase. There is an unresolved tension with destructiveHint=false when the text says the existing config is cleared to empty defaults, and no statement about reversibility or whether prior settings are recoverable.

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 clauses, front-loaded with the action and ending with the two highest-value behavioral facts (immediate application, mutation). 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?

For a zero-parameter operation with full annotation coverage and no output schema, the description covers action, target, immediacy and the source method. The only real gap is scope and recoverability — which config it resets (device vs project) and whether the cleared settings can be restored.

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 the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing 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 specific verb and resource ("Clear the firmware config to empty defaults") and names the underlying store method resetFirmwareConfig, so the agent knows exactly what happens. It doesn't explicitly contrast itself with the nearby firmware_config_set / firmware_config_edit / firmware_config_load_template siblings, but the destructive-reset semantics are distinguishable.

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?

"Immediately applies. MUTATING." signals the operation is applied without a confirmation step, which implicitly tells the agent to be careful, but there is no explicit when-to-use/when-not guidance and no mention of the alternative config tools. The agent must infer that this is the nuclear option versus firmware_config_set/edit.

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 readOnly=false, destructive=false, and idempotent=false. The description adds useful timing context beyond those annotations: the change applies immediately to the app store and affects the next burn. It doesn't explain what happens to config keys absent from the supplied object, which is the main remaining ambiguity for a full-replace 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?

Three short sentences, front-loaded with the action. The 'MUTATING — writes to the app's firmware config' sentence largely restates the annotations, so it earns its place less than the timing sentence does.

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 one required parameter, full schema coverage, annotations covering the safety profile, and no output schema, the description supplies what an agent needs: what is replaced, the underlying call, and when the effect lands. Only the partial-vs-full-replace failure mode is left unaddressed.

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 100% and the single parameter already documents itself as a 'Full firmware config object (mirror of firmware_config_get).' The description repeats that framing rather than adding format, validation, or shape details beyond the schema, so baseline 3 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 and resource: 'Replace the whole firmware config.' The word 'whole' implicitly distinguishes it from the partial-edit sibling firmware_config_edit, but no sibling is named 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 description conveys that this is a full replacement that applies immediately to the app store and the next burn, which implies when it's appropriate. It never explicitly says when to prefer firmware_config_edit, firmware_config_reset, or load_template instead, so the routing decision is left 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful context beyond annotations: it says no app connection is required and describes the returned documentation structure, which helps the agent understand the tool’s 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?

The description is three tight sentences with zero waste. The purpose and scope are front-loaded, followed by return content and the optional parameter 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?

For a one-parameter documentation lookup with no output schema, the description supplies enough detail about what is returned: enums, grouped action names, and per-action arg signatures. Nothing needed to invoke it correctly 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?

Schema description coverage is 100%, so the action parameter is already well documented in the schema. The description confirms that passing action=<name> returns a single action doc instead of the full catalog, but adds little beyond the schema’s own explanation.

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 resource (firmware-config store actions) and explains exactly what the tool exposes: enums, grouped action names, and per-action arg signatures. It also distinguishes itself from the related sibling by naming firmware_config_edit as the surface it documents.

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 clearly situates the tool as documentation for the actions behind firmware_config_edit and explains how to narrow output with action=<name>. It does not explicitly state when not to use it or name a direct alternative for discovery, but the context is sufficient for an agent to choose it correctly.

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 assert readOnlyHint/idempotent/non-destructive, but the description adds real value beyond them: it discloses that the check mirrors the app's checkDeviceConfigSync, that 'Nothing is written', and the subtle caveat that upgradeTargets is authoritative while the app log may report a loader upgrade that is then skipped. That last point is a behavioral nuance no annotation could convey.

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-loaded with the core dry-run statement, then caveats and the consent use case in tight order. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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?

There is no output schema, and the description compensates by explaining what upgradeTargets contains and warning about its divergence from the app log. With annotations covering safety and the schema covering the two inputs, only minor details (error behavior, latency) are absent.

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 50% and the description contributes no parameter-level meaning — it never mentions firmwareListId or hardwareMappings, and 'upgradeTargets' is a return field, not an input. The half-documented parameters are adequately covered by the schema's own descriptions, so baseline 3 applies rather than a penalty.

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 and resource ('Dry-run of flash_config's hardwareMappings path') and states exactly what is produced: per-board firmware / MPY / loader upgrades that runSendConfigTask would execute. An agent can distinguish it from flash_config and the flash_* siblings without reading any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly scopes usage: run this before sending config and pairing, and specifically 'to get the user's consent for upgrades first' — a clear precondition. It stops short of naming when NOT to use it (e.g. when no upgrades are expected or when the user already consented), so no exclusions 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?

Goes well beyond the annotations: discloses the refusal behavior for ambiguous/unmatched targets, the error-code-to-remedy mapping, the exact return shape ({ok, verified, bytes, chunkSize, blocks, md5, readback}) with the meaning of verified, the failure shape {stage, ...}, the requirement for a sender board on the second path, and that the second path 'never creates a project'. Safety profile is stated outright ('Executes immediately — OVERWRITES the board's stored config. MUTATING / writes to hardware'), which aligns with readOnlyHint=false; destructiveHint=false is a mild tension with 'OVERWRITES' but not a direct contradiction since the change is a rewrite, not a deletion.

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?

The purpose and default path are front-loaded, and every sentence carries information (paths, preconditions, return shape, side effects). However, the content is packed into a dense block of parentheticals and arrows, so an agent must parse carefully to separate the two paths; minor structural cost, 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?

For a 5-parameter, nested-schema mutation tool with no output schema, the description covers what is needed: which params belong to which path, the connectivity prerequisite, the confirm approval requirement, the overwrite side effect, the success return fields, and the failure shape. Nothing an agent needs to invoke it safely 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real routing meaning the schema cannot express: firmwareConfig is 'file-protocol path only' while confirm and firmwareListId are 'runSendConfigTask path only', and hardwareMappings is the flag that opts into that path. It also restates the exactly-one-target/ambiguity rule from the schema rather than adding to it, keeping it short of a 5.

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 ('Write a firmwareConfig to the board') and immediately distinguishes two execution paths: the default SET_DEVICE_CONFIG file protocol versus the runSendConfigTask path selected by hardwareMappings. It also separates itself from flash_check (preview), connect_bluetooth (prerequisite), and implicitly from flash_firmware/flash_mpy by saying the config-burn path only 'can also upgrade firmware / MPY / loader first'.

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?

Explicitly names when to use each path ('Default: ...', 'Passing hardwareMappings switches to ...'), the preconditions ('The device must be connected (else DEVICE_NOT_CONNECTED → call connect_bluetooth)'), and the approval gate ('preview with flash_check and pass confirm=true only after the user approved'). Alternatives and exclusions are stated rather than inferred.

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 flag destructiveHint=true, but the description goes well beyond them: immediate execution, multiple reboots, bricking risk if interrupted, and the fact that the MCP does not replicate the app's authenticated cloud package fetch. That last point is exactly the kind of behavioral constraint an agent cannot get from any structured field.

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-loaded with the operation and its danger, then the required inputs, then the confirmation rule. Nearly every clause carries new information; the trailing 'DESTRUCTIVE.' is mildly redundant given the brick warning and destructiveHint annotation.

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 5-parameter destructive mutation with no output schema, the description covers the essential risk profile, the calling prerequisite (user approval), and the surprising input requirement (agent-supplied base64 image). Device targeting rules live in the schema. Nothing critical for a correct call 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?

Schema coverage is 80%, so the baseline would be 3, but the description adds real meaning: it explains *why* firmwareBinaryB64 must be supplied (no cloud fetch, base64 .bin) and that confirm must follow explicit per-device approval. Those are motivations the schema descriptions only partially convey, though target/targetVersion handling in the description is thinner.

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 ('Run a full system firmware flash (SYSTEM_UPGRADE)') and names the underlying app routine (updateLoaderFirmwareMpy with shouldUpgradeFirmware=true), which pins down exactly which operation this is. It implicitly distinguishes itself from the partial/MPY flash siblings by insisting on the 'full system' scope, but never names flash_mpy or flash_check as the alternatives.

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 gives a clear precondition (explicit user approval before confirm=true) and explains why the binary must come from the caller rather than the app's cloud fetch. However, it never says when to prefer this over the closely named siblings flash_mpy, flash_check, or flash_config, leaving the agent to infer the boundary from the word 'full'.

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?

The annotations already declare destructive=true, non-read-only, non-idempotent, and open-world behavior, but the description adds critical operational context: it writes mpy.img, reboots the board, requires confirm=true after explicit user approval, and warns that the built-in path is experimental pending live validation. These details go meaningfully beyond the annotation flags without contradicting them.

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?

The description is compact and front-loaded: it names the operation, states the destructive consequence, gives the confirm gate, explains the two MPY paths, and adds the experimental caveat. Every sentence carries operational or safety-relevant 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?

For a destructive, high-complexity firmware update with nested target parameters and no output schema, the description covers the essential safety and path-selection behavior. It leaves some parameter details to the schema, such as region, designId, and eraseFirmwareConfig, and does not describe success/failure reporting, but the core call context is present.

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 75%, so most parameters are already documented structurally. The description adds useful path-level semantics around mpyType=1 default behavior and userMpyConfig, but it does not explain region or designId and mostly repeats what the schema already says about confirm and mpyType.

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: running a MicroPython firmware update via updateLoaderFirmwareMpy / START_MPY_UPDATE. It also clarifies the built-in RC MPY versus design MPY paths. It does not explicitly differentiate this from sibling tools such as flash_firmware, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool's use for MicroPython firmware updates and gives prerequisite guidance for confirm=true and explicit user approval. It also explains the default built-in RC path versus userMpyConfig design path. However, it does not explicitly state when to use this tool instead of related siblings like flash_firmware or flash_config.

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, idempotentHint=false, destructiveHint=false; the description adds genuine context beyond them by stating the command executes immediately and physically drives an actuator/output on the board, warning that a harmless-looking destructiveHint=false does not mean no side effects. It omits whether the call awaits an ack, what happens if the board is disconnected, or whether the effect is reversible.

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 tight sentences, front-loaded with purpose then hazard. Minor waste: 'MUTATING' largely restates readOnlyHint=false already supplied by annotations, though it serves as salience for a risky 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 output schema, the description should say what an immediate command returns (ack, result payload, or nothing) and what failure looks like on a disconnected or ambiguous device. It covers the mutation semantics but leaves the response contract of an 'executes immediately' action unspecified.

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 100% and the nested target/command descriptions already explain 'pass exactly one field', the ambiguous-target refusal, and the sendTestCommand payload shape. The description adds only the passing reference to sendTestCommand, no extra semantics for target selection modes or valid command keys — baseline 3.

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: sends a control/test command to a connected device, and clarifies it drives an actuator/output on the board. This usefully counteracts the misleading name 'flash_test' (which sounds like flash-memory testing) and separates it from flash_firmware/flash_config/flash_check. It does not explicitly name a sibling to differentiate against, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Executes immediately — drives an actuator/output' implies this is for live device actuation rather than configuration, but there is no explicit when-to-use/when-not statement and no alternative named (e.g., vs flash_check or device_config_set). The agent must infer selection criteria.

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?

The annotations already declare readOnlyHint=false and destructiveHint=false, so calling the tool 'MUTATING' restates what the annotations already say. The description does add the concrete side effect, that a project is added to the app's list, and the internal flow of template config plus addFirmware. It does not say what happens on failure, how duplicate names are handled, or whether the new project is opened afterward.

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 sentence, with the action and resource front-loaded, and every clause either names templates or states the side effect. There is minimal waste.

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 description covers the creation action and its side effect, but it leaves out the result of the call entirely: there is no output schema, so the agent cannot tell whether the call returns a project id, the project object, or nothing, which matters if the agent must subsequently call project_open_editor or project_load. The template-list mismatch also undercuts completeness.

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 100%, so the schema already documents both parameters, including the 31-character limit and the default name behavior. The description repeats the template keys but does not add format or semantics beyond the schema, and it lists 'none' as a template even though that value is absent from the enum, which could mislead an agent about accepted input.

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 has a specific verb and resource, 'Create a new CyberBrick project from a built-in template', and names the concrete templates the tool accepts, so an agent can tell it apart from project_list, project_load and project_import. It stops short of explicitly naming those siblings as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Use is only implied: creating a project from a built-in template. The description gives no explicit rule for when to choose this over project_import or project_load, and it never states preconditions such as whether a window or app session must already be active.

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 destructiveHint=true and idempotentHint=false, but the description goes further: it specifies that deletion is permanent, that the config is removed from the app's persisted list, and that no confirmation is added by MCP. These are meaningful behavioral details beyond structured fields.

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 'DESTRUCTIVE,' and every sentence contributes a distinct, useful fact (irreversibility, persistence removal, no confirmation). No waste.

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 one-parameter destructive mutation with an output schema absent and annotations already covering the safety profile, the description supplies the critical missing context: irreversibility, persistence effect, and absence of confirmation. An agent has everything needed to call it correctly and cautiously.

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 100% and the only parameter's description ('Project configId from project_list') is already in the schema. The description adds no additional meaning about the id parameter, so the baseline 3 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 and resource ('permanently deletes the project') and even names the underlying mechanism ('deleteFirmware'). It is clearly distinguishable from siblings like project_create, project_rename, and project_save, though it does not explicitly contrast itself with any 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?

Provides strong context for when this tool applies: permanent, irreversible deletion with no confirmation added by MCP. It does not name alternatives or explicitly exclude scenarios, but the destructive/irreversible framing gives the agent clear usage 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower; the description still adds real value by disclosing that runtime fields are stripped and a version is stamped, matching the app's export serialization. It stops short of covering failure modes such as an unknown project id or payload size, which 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 dense sentences front-load the action and the key caller responsibility, with zero filler in between. The trailing 'Read-only.' merely restates the readOnlyHint annotation and is the one piece that does not earn its place.

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 one required parameter, full schema coverage, and no output schema, the description does the necessary work: it explains what the returned content is and that the caller must write it to a file. Only error/edge-case behavior is unaddressed, which is a minor gap for a simple read 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?

There is a single parameter with 100% schema description coverage ('Project configId (from project_list)'), so the schema already carries the semantics. The description adds no further detail about the id, making the baseline 3 appropriate.

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 names a specific verb and resource ('Export a project's config as JSON content') and immediately clarifies the scope of the output versus the app's own save flow. The line 'No save dialog; write the returned content to a file yourself' implicitly separates it from the mutating project_save sibling, so an agent can pick correctly without opening schemas.

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 makes clear that this returns content rather than persisting it, which implies the usage context (agent wants the JSON payload). However, it never explicitly says when to prefer this over project_save, nor does it name any alternative or exclusion — the routing has to be inferred from behavior.

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?

Beyond the annotations it discloses concrete behavior: config_version is validated and newer files are rejected, design_id/region are silently forced to app defaults, and the project is added to the project list. It also restates the mutating nature in caps, aligning with readOnlyHint=false and destructiveHint=false (add-only, no overwrite).

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?

Purpose is front-loaded in the first clause and the trailing 'MUTATING' flag is well placed. The parenthetical app-internal method name is slightly incidental for an agent, but the remaining clauses all carry operational weight.

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 two-parameter, non-idempotent import with no output schema, the description covers validation, forced defaults, and side effects. The only gap is what is returned on success (new project id/handle), which an agent must discover empirically.

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 already 100%, so the baseline is 3; the description still adds value by telling the agent the content string must be the exported project file read from disk by the caller. That closes the practical gap about what format/content to supply, though the name parameter's defaulting rule is left to the 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 and resource (import a project) and pins the input form (JSON content passed as a string), which separates it from project_create/project_load/project_export siblings. It also names the underlying app flow (importProjectFromFileContent), leaving no ambiguity about what operation occurs.

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 gives clear preconditions: the caller must read the file itself and pass content as a string, which is the key procedural guidance. It does not explicitly say when to prefer this over the sibling project_load or project_create, so it stops short of full alternative routing.

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, idempotentHint, non-destructive and closed-world, so the description's 'Read-only' is pure repetition. Beyond that it offers the internal call names and the field list, but the one behavioral rule it does state (include=full) references a parameter that does not exist in the schema, which misleads an agent trying to trigger the full-record path.

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 short and front-loaded with the verb and resource, so nothing is wasted on filler. However, the content is dense with implementation jargon (getShowList, configId, getFirmwareById) and combines two distinct operations into one run-on sentence, hurting readability more than length does.

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 output schema, the field enumeration is a genuinely useful addition. But the description leaves the core invocation ambiguous, since the only documented switch (`include=full`) does not match the actual `id` parameter, so an agent cannot reliably reach the full-config behavior it describes.

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 100% and the sole parameter is `id`, documented in the schema as returning the full record for that configId. The description instead names a different parameter, `include=full`, which contradicts the schema and gives an agent a wrong invocation path; this actively subtracts value rather than adding it.

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 verb+resource is stated ('List CyberBrick projects') and the returned fields are enumerated, but the second sentence muddies the purpose by describing a single-project fetch ('fetch one project's complete config body'), so it is unclear whether the tool is a lister or a getter. Internal function names (getShowList, getFirmwareById) add noise rather than clarity and do nothing to distinguish it from siblings such as project_state or project_load.

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?

Only 'Read-only.' hints at usage context. There is no guidance on when to pick this over project_state, project_load, or project_open_editor, and no statement of prerequisites. The only conditional ('Pass include=full') is attached to an undocumented, contradictory mechanism.

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 idempotentHint=false, but the description adds the key consequence the annotations cannot express: it replaces the current editor config. That is precisely the fact an agent needs before calling. It stops short of saying whether unsaved changes are recoverable or what happens if the id is invalid.

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, purpose and mutation warning front-loaded, workflow next. The internal function-name aside (setFirmwareConfig(getFirmwareById(id)) + setConfigType) is implementation detail that costs reading effort without helping an agent decide or call, but the rest earns its place.

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 single-parameter mutation with no output schema, the description covers purpose, mutation effect, and the follow-up workflow. Only missing pieces are failure behavior (unknown id) and whether the prior editor state is lost or restorable.

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 100% and the id parameter already documents its origin ('from project_list'), so the description adds no new parameter meaning. The parenthetical getFirmwareById(id) hints at lookup semantics but repeats little of practical value. Baseline 3 applies when the schema carries the parameter burden.

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 ('Load a project's config into the app's firmware editor store') and disambiguates scope from siblings by tying it to the user action 'the same thing the app does when you open a project'. An agent can distinguish it from project_open_editor and firmware_config_get from the text alone.

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 an explicit call sequence: load, then firmware_config_edit to change parameters, then project_save to persist. It names both follow-up siblings and their roles, so there is no ambiguity about ordering or alternatives.

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 readOnly=false and idempotent=false; the description goes beyond them by naming the side effects (config loaded into editor store, new window created) and the default new-window behavior. It stops short of saying what happens if a window already exists or how failures surface.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence covering purpose, mechanics, and mutation status with little waste. Internal implementation names (openProjectEditor, createWindowWithPath) add marginal value for an agent.

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 two-parameter tool with full schema coverage and annotations present, the description covers what it does, both parameters' behavior, and mutation impact. No output schema exists, so return values are the only unaddressed gap.

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 100%, so baseline is 3, but the description adds value by linking id to the firmwareId query parameter and spelling out that target=new is the app default versus navigating the current window. The enum values themselves are already documented in the 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?

Specific verb+resource: opens the project editor, loads config into the editor store, and routes to /project/edit?firmwareId=<id>. It is clearly distinct from project_load/project_list siblings, though it never names them 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?

Usage is implied by the action itself and the target choice is explained, but there is no explicit when-to-use versus project_load or window_list, and no stated preconditions such as the need for an existing project id.

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, idempotentHint=false, and destructiveHint=false. The description adds 'MUTATING' and notes that the 31-character limit comes from app validation, which is modest additional context, but it still does not explain permissions, reversibility, or side effects beyond what the annotations imply.

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?

The description is very short and front-loads the core action. However, the 'Max 31 chars (app validation)' detail overlaps with the schema's maxLength and name description, making it slightly redundant rather than purely additive.

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 simple two-parameter rename operation with full schema coverage and annotations covering safety semantics, the description is largely complete. It could be richer about behavior around invalid names or the response, but no output schema exists and annotations cover the key safety profile.

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 100%, so both parameters are already documented in the input schema, including the 31-character maximum for 'name' and the source of 'id' from project_list. The description does not add meaning beyond what the schema provides.

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 and resource ('Rename a project') and identifies the underlying operation ('renameFirmware'). It clearly distinguishes renaming from creation, deletion, or loading, but does not explicitly contrast itself with all sibling project tools.

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 states that the operation is mutating and enforces a 31-character limit, but gives no guidance on when to use this tool versus alternatives such as project_save, project_create, or project_delete. An agent must infer the usage 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?

Annotations already declare a non-idempotent, non-destructive write; the description adds real value by naming the write target (the project list) and the upsert semantics ('updates by id, adds if new') plus the side effect of marking the editor saved. It does not say what happens on failure or whether an existing project entry is overwritten in detail, keeping it below 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 sentences, front-loaded with the action and followed by the mutating warning. The parenthetical referencing the app store's 'updateFirmware' is opaque jargon that costs a little clarity without adding actionable meaning.

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 mutation with full annotation coverage and no output schema, the description covers what is written and the upsert behavior. It could note the resulting project identity or state change on the editor, but nothing essential is missing 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly signals that the tool acts on implicit editor state rather than arguments.

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: persist the current editor config into the project list and mark the editor saved. The 'adds if new' clause distinguishes it from a pure create (project_create) without naming that sibling, so it is clear but not explicitly differentiated.

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 editor must be open with a current config, and this is the persist step. There is no explicit when-to-use vs project_create/project_list guidance, and no stated preconditions or failure situations.

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 readOnly/idempotent/non-destructive, so the trailing 'Read-only.' is redundant, but the description adds real behavioral context the annotations can't: the tool returns a nextTools routing list of currently relevant tools, making it a discovery entry point rather than a plain snapshot.

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-loaded with the payload definition, followed by the usage directive. Tight overall, with only minor waste in the trailing 'Read-only.' which merely restates the annotations.

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?

No output schema exists, so the description carries the burden of describing returns and does so for the main fields (route hash, project summary, isModified, configType, nextTools). Nested shapes of the project list summary and nextTools entries remain unspecified, but the essentials are covered.

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 there is nothing to document and the baseline is a 4. The description correctly implies a parameterless snapshot call with no filtering options.

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 ('Read the app's current context') and enumerates the payload: active route hash, project list summary, editor state fields. An agent knows what it gets back. It doesn't explicitly contrast with neighbors like project_list or device_pool_state, so the difference has to be inferred from the 'call this first' framing.

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 directive: 'call this first when working with CyberBrick projects, then act', which tells the agent both ordering and trigger context. It stops short of naming when-not-to-use or which sibling to prefer for narrower questions.

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?

Goes well beyond the annotations by disclosing the exact execution path (app's own closeSubWindow via window:close-sub-window IPC, same as the close button), that unsaved changes trigger the app's own confirm dialog which the MCP does not bypass, and the refusal error code for the current window.

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?

Purpose is front-loaded in the first clause and every subsequent sentence adds real constraints. It is dense with parentheticals and the trailing 'MUTATING.' largely restates readOnlyHint=false, which keeps it just short of fully tight.

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 single-parameter mutation with no output schema, everything needed to call it correctly is present: ID source, the refusal case, the confirmation-dialog behavior, and the cleanup rationale.

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 100% and the schema already says the id comes from window_list and must not be the current window, so the description mostly repeats structured data rather than adding new format or semantics for windowId.

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 (close an app sub-window) plus the identifier it operates on (windowId from window_list), and the 'sub-window' qualifier distinguishes it from window_close_others and from closing the main window.

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 an explicit when-to-use (each project_open_editor with target="new" creates one of these; close them to avoid buildup), an explicit when-not (the MCP-connected window cannot be closed, REFUSE_CLOSE_CURRENT), and points to window_list as the ID source.

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 non-read-only, non-idempotent, non-destructive, so the keyword 'MUTATING' is partly redundant. The genuinely additive information is that unsaved changes surface the app's own confirm dialogs, which tells the agent that a blocking user prompt may occur mid-call — something no annotation conveys.

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 operation, then the use case, then the behavioral caveat. Every sentence adds something new and nothing is 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?

For a parameterless window-management tool with no output schema, the definition covers what it closes, why to call it, and the confirm-dialog caveat. It does not say what the agent should expect if the user cancels a confirmation or whether any summary of closed windows is returned, which is the remaining gap.

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 carries nothing to explain and the baseline of 4 applies. The description correctly implies the target set is derived from session identity rather than an argument, which is the only semantic question a parameterless tool raises.

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 ('Close every CyberBrick app window') plus an explicit scope boundary ('except the one this MCP session is connected to'). That scope clause is what distinguishes it from the sibling window_close, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use to clean up editor windows accumulated from project_open_editor' names a concrete triggering scenario, which is real usage guidance rather than implied context. It stops short of an explicit exclusion or naming window_close as the alternative for single-window cases, so it is not a 5.

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 readOnly/idempotent/non-destructive, and the description repeats 'Read-only' but adds real value beyond that: it discloses staleness semantics (openWindows is live truth, storeWindows 'may be stale') and reports unsaved-editor state. That staleness caveat is exactly the kind of behavioral context annotations cannot express.

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 (plus 'Read-only') that front-loads the tool's purpose and then defines each returned field. Every clause carries information, though the backtick-heavy inline glossary makes it slightly harder to scan than a short bulleted breakdown would be.

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?

There is no output schema, so the description must and does explain the return shape: live page list with titles and hash routes, the persisted id map, the current window id, and unsaved-change status. An agent can act on this without further discovery.

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 there is nothing to disambiguate and the baseline is 4. The description spends its words on return semantics instead, which is the correct allocation for a param-free tool.

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?

Specific verb 'List' plus a precise resource 'the CyberBrick app's open windows', and it enumerates the three data sources returned (openWindows, storeWindows, currentWindowId). This is clearly distinguishable from siblings like window_close or project_state.

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 establishes the key usage context by noting that storeWindows ids 'are what window_close accepts', which implicitly tells the agent to call this before closing a window. It does not explicitly state when not to use it or name an alternative tool, so it stops short of a 5.

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