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

With no annotations provided, the description carries the full burden. It discloses that the tool connects and retrieves information, but does not mention any side effects (e.g., halting the core), preconditions (e.g., probe connected, target powered), or failure modes. The listed outputs provide some transparency about expected results.

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, concise sentence that front-loads the action and specifies the retrieved data. There is no redundancy or 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 connection/info tool with no output schema and no annotations, the description lists the returned data but omits workflow context (e.g., that this is likely a first step before flashing) and behavioral caveats. The schema covers parameters thoroughly, but the tool's place among siblings and failure conditions are unclear. It is minimally viable but lacks completeness for an agent deciding when to use 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 input schema already provides descriptions for all 5 parameters with 100% coverage, so the baseline is 3. The description does not add any extra meaning about parameters like sn, freq, mode, port, or reset, leaving the schema to do the heavy lifting. No additional context is provided.

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 clearly states the tool connects to an STM32 MCU and retrieves specific device details (Chip ID, Flash size, Revision ID, CPU Core), distinguishing it from sibling tools that flash, erase, read, write, or reset. The verb 'connect' and the listed outputs make the purpose unambiguous.

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 usage when you need to identify or connect to a target MCU, but it does not explicitly state when to use this versus alternatives like stm32_list_probes for probe discovery or stm32_read_memory for reading memory. No exclusions or prerequisites are mentioned.

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

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

No annotations are provided, so the description must carry the burden of disclosing behavioral traits. While it names the operation, it fails to explicitly warn that this is a destructive, irreversible operation that will erase all data in the target flash. It also does not mention potential side effects like requiring a stable power supply or handling of sector vs. mass erase. This is a significant gap for a high-risk tool.

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

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

The description is a single sentence of 11 words, front-loaded with the primary verb and resource. It achieves clarity without any wasted words, and the parenthetical clarifies the two operational modes. This is an exemplary concise 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?

The tool has no output schema, no annotations, and a minimal description. The operation itself is complex (destructive, with two modes), but the description does not explain expected outcomes, error handling, or the relationship with other operations like flashing or resetting. An agent would lack critical context for safe and correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions; it only reiterates the two erase modes already covered by the 'erase_type' enum. Since all parameters are already well-described in the schema, a neutral score 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?

The description clearly states the tool's function: 'Perform Flash memory erase operation' with specific scope (Full Chip Mass Erase or Sector/Page Erase). It uses a specific verb ('erase') and resource ('Flash memory'), and the two modes effectively distinguish it from sibling tools like stm32_read_memory and stm32_write_memory.

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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisite steps (e.g., connect, read option bytes), safety precautions, or that erasing is typically required before flashing firmware. The usage context is entirely implied by the tool name and sibling 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?

With no annotations, the description carries the behavioral disclosure burden. It mentions optional verification, mass erase, reset, and run, which are important side effects. However, it does not explicitly warn that mass erase is destructive, that reset_and_run defaults to true (per schema), or address failure modes or connection prerequisites, leaving significant behavioral details unspoken.

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, well-structured sentence that front-loads the primary action and resource, then lists supported file formats and key optional behaviors. There is no redundant or filler content; every element 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?

Given the tool's moderate complexity (7 parameters, destructive operations, no annotations), the description and schema together cover the core function but lack explicit warnings about destructive overwrite and default behaviors. The agent must infer important operational context such as the effect of erase_first and reset_and_run defaults, making it adequate but not complete.

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

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

All 7 parameters are fully described in the input schema with 100% coverage, so the baseline is 3. The description only echoes file formats and optional behaviors without adding new semantic detail about parameters like sn, port, address, or the meaning of default values. It does not need to compensate because the schema already provides comprehensive descriptions.

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 clearly states the tool flashes/programs firmware files (.bin, .hex, .elf, .srec) to an STM32 MCU, which is a specific verb+resource. This distinguishes it from sibling tools like stm32_write_memory or stm32_erase_memory, as it targets complete firmware images with optional post-flash operations.

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 is for programming firmware files and mentions optional verification, mass erase, reset, and run, giving a clear use case. However, it does not explicitly contrast with alternatives such as stm32_write_memory or stm32_erase_memory, nor provide when-not guidance. The decision to select this tool over siblings 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?

No annotations are provided, so the description must carry the full burden. It conveys a read-only operation via the verb 'List' and specifies the device types scanned, but it does not disclose prerequisites (e.g., drivers), return format, or behavior when no devices are found.

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, information-dense sentence with no redundant words or filler. It covers the full scope of the tool in minimal space.

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 discovery tool with one optional parameter and full schema coverage, the description adequately conveys the core function. However, it lacks explicit mention of output format or error behavior, and no output schema exists to compensate.

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

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

The single parameter interface_type is fully documented in the schema with enum values and a description. The tool description adds no additional parameter-level detail, so it does not exceed the baseline set by the high schema coverage.

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 the specific verb 'List' with a clear resource: 'connected ST-LINK debug probes, J-Link programmers, USB bootloaders, and COM serial ports.' This unambiguously identifies the tool as a discovery/enumeration tool and distinguishes it from sibling tools like stm32_flash_firmware or stm32_connect_info.

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 implies the tool is for enumerating connected hardware before other STM32 operations, by listing the specific device types it scans. However, it does not explicitly state when to use this over alternatives or provide any exclusions, 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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states parameters are run 'directly', hinting at a raw passthrough without validation, but it fails to disclose potential risks, error behaviors, or the fact that invalid arguments could have serious consequences on the target device. This is notably insufficient for a raw CLI passthrough tool.

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

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

The description is a single, focused sentence that front-loads the verb and resource. It is appropriately concise for a simple passthrough tool, though it could benefit from a brief caution or pointer to the underlying CLI's documentation. Overall, it is well-structured with no wasted words.

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

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

Given the single parameter and high schema coverage, the description is adequate for a basic understanding. However, it lacks context about the underlying STM32_Programmer_CLI, potential risks, or when to prefer this over sibling tools. Since there is no output schema and no annotations, the description should provide more safety context to be fully complete for an AI agent.

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 already describes the 'args' array with an example, providing high coverage. The description adds value by emphasizing that parameters are passed 'directly' and 'raw', clarifying that no transformation or validation occurs. This semantic nuance is important for the agent to understand the tool's behavior and complements the schema well.

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 clearly states the tool runs raw parameters against STM32_Programmer_CLI, distinguishing it from the high-level sibling tools. It specifies the verb 'run' and the resource 'STM32_Programmer_CLI', making the purpose unambiguous and differentiating it as a low-level escape hatch.

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

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

The phrase 'for advanced/custom operations' implies when to use it (when standard sibling tools don't suffice), but it doesn't explicitly mention alternatives or exclusions. There's no explicit statement like 'use when other tools do not cover the needed operation', so usage context is implied rather than clearly delineated.

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

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

No annotations are present, so the description carries the full burden. It does disclose the output format (hex dump or binary file) and that it is a read operation, but does not explicitly state side effects, prerequisites like an active debug connection, or error behavior. The read-only nature is implied but not confirmed.

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 that states purpose and output with no filler. Every word earns its place, and the key verb and resource are front-loaded.

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

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

The tool is moderately simple; the schema covers parameters, and the description covers the return type. However, it lacks operational context such as requiring a connection setup, addressing limitations, or interpretation of the hex dump. Since there is no output schema, a bit more detail would round out the picture.

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 input schema provides comprehensive descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds no additional parameter-specific detail beyond what the schema already offers.

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 clearly defines the tool's role: reading memory/registers from an STM32 target and returning a hex dump or saving to a binary file. It uses a specific verb ('Read') and resource ('target MCU memory or register contents'), and distinguishes from sibling write/erase/flash 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 implies usage for memory reads but does not explicitly state when to prefer this over alternatives like stm32_read_option_bytes or stm32_raw_cli. No exclusion criteria or context about prerequisites (e.g., established connection) is provided.

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

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

With no annotations, the description carries the full burden. The verb 'Read' clearly implies a non-destructive operation, and listing specific configuration fields adds context. However, it does not disclose return format, required probe state, or any potential side effects beyond the implied read-only nature.

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, front-loaded sentence that directly states the tool's function and examples. Every word earns its place with no fluff or redundancy.

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

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

For a simple read tool with two optional parameters and no output schema, the description covers the core purpose and the specific configuration data returned. It lacks details about prerequisites (e.g., probe connection) or output formatting, but overall is sufficient for a user to understand what the tool does.

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?

Input schema coverage is 100%, with both parameters having descriptions. The tool description adds no additional meaning about parameters, so baseline 3 is appropriate. The schema sufficiently documents 'sn' and 'port'.

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 (Read) and identifies a clear resource (target MCU Option Bytes configuration), then enumerates the specific contents (RDP protection level, BOR, Watchdog, Boot flags). This distinguishes it from sibling tools like stm32_write_option_bytes and stm32_read_memory.

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 when to use the tool by naming the exact configuration area, but it does not explicitly contrast with alternatives or state exclusions. Context signals include stm32_write_option_bytes, so a user could infer the read/write pairing, but no direct guidance is provided.

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

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

No annotations are provided, so the description must disclose side effects, but it only says 'trigger reset signal' without explaining consequences like halting execution or affecting the debug connection. The reset_type enum is defined in the schema, but the description adds no behavioral detail.

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, lean sentence with no filler words. It is appropriately concise for a simple tool, though it sacrifices some behavioral clarity for brevity.

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?

Despite the simple tool, the description does not explain when to use it or what happens after a reset. With no annotations or output schema, the minimal text leaves the agent without enough context for confident 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?

The schema provides 100% coverage for both parameters, including descriptions for 'port' and 'reset_type'. The description adds no additional parameter details, so it scores at the baseline of 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?

The description clearly states the action ('Trigger'), the object ('reset signal'), and the target ('MCU'). It distinguishes this tool from siblings like stm32_run_mcu, which is about execution rather than reset.

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

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

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusions. The only hint is the tool name, so the agent must infer 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?

With no annotations, the description carries the full burden but only says 'start or resume,' which implies the MCU will begin running. It does not disclose whether this halts an existing debug session, whether it requires the device to be connected, or what happens if the address is invalid. This is a minimal disclosure without side-effect information.

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, front-loaded sentence with no fluff. It is efficient and to the point, earning full marks for conciseness.

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 tool, the description gives the core action but lacks context about preconditions (e.g., a live connection) and post-execution behavior. There is no output schema, and annotations are absent, so this description is minimally viable but not rich.

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 description adds little beyond what the schema already provides. The phrase 'address or entry point' aligns with the 'address' parameter but adds no new format or semantic details; the 'port' parameter is also not elaborated.

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 clearly states the action ('start or resume program execution') and the target ('specified address or entry point'). It differentiates from siblings like stm32_reset_mcu by focusing on execution at a custom address rather than reset.

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

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

No guidance is provided on when to use this tool versus alternatives like stm32_reset_mcu or after flashing. It does not mention prerequisites (e.g., prior connection) or when 'resume' applies rather than 'start'. The lack of context means an agent must infer usage 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states the action ('Connect and stream'), but it does not reveal important behavioral traits such as whether the operation blocks, how to terminate the stream, or that it may alter target trace settings. This is a moderate gap.

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

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

The description is a single sentence that delivers the essential purpose and action without unnecessary words. It is front-loaded and every word contributes to understanding.

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 core purpose and the schema documents parameters, but it lacks context about the streaming behavior (e.g., ongoing capture, stopping method) and does not describe return values or output format. Since there is no output schema, this is a noticeable 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 the schema already documents all three parameters. The description adds no additional meaning beyond the schema, such as usage examples or relationships between parameters. This hits the baseline for high schema coverage.

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 ('Connect') and resource ('Serial Wire Viewer (SWO/ITM)') and clearly states the action ('stream printf log outputs'). This distinguishes it from sibling tools like stm32_connect_info, which focuses on connection details, and stm32_raw_cli, which is a general CLI. The purpose is unambiguous.

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 is used when you need to view printf logs over SWO/ITM, providing clear context. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full when/when-not/alternatives explanation.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It states the write is 'directly' to memory, implying low-level access, but does not warn about potential destructive overwrites, invalid address crashes, or required connection state, which are critical for a memory-write tool.

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

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

The description is a single, front-loaded sentence with no filler words. It efficiently communicates the core function in ten words.

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

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

The tool has a simple 3-parameter schema with 100% coverage and no output schema, so the description need not explain return values. However, it omits important contextual safety information about the consequences of direct memory writes, making it only minimally complete.

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

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

The input schema provides complete descriptions for all three parameters, including address format and data/file payload. The description's 'value or file payload' adds no substantive meaning beyond the schema's own documentation, so this is baseline.

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 clearly states the action ('Write value or file payload') and the target ('memory address or peripheral register'), using a specific verb and resource. It distinguishes from sibling tools like stm32_read_memory, stm32_erase_memory, and stm32_flash_firmware by focusing on direct memory/register writes.

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 does not provide any guidance on when to use this tool versus alternatives like flash_firmware or write_option_bytes. No exclusions or prerequisites are mentioned, leaving the user to infer usage from the tool 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?

With no annotations provided, the description must carry the behavioral disclosure burden. It does indicate this is a write operation via 'Modify', and the examples imply changes to security settings. However, it lacks warnings about potential risks (e.g., bricking the MCU, irreversible changes) or prerequisites, leaving the agent with minimal safety context.

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, front-loaded sentence that immediately states the tool's purpose. The examples are concise and informative, with no unnecessary words or repetition.

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?

Given the tool's simplicity (2 parameters, no output schema, straightforward purpose), the description is largely complete. It explains what it does and gives usage examples. However, given the potentially destructive nature of modifying option bytes, a note about caution or side effects would have made it fully complete, but this is not a critical 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 the baseline is 3. The description adds value by providing concrete example formats for the 'option_bytes' parameter (e.g., 'RDP=0xAA'), which goes beyond the schema's generic 'key-value pairs' text. The 'port' parameter is adequately covered by 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?

The description clearly states the tool modifies target MCU Option Bytes, with a specific verb ('Modify') and resource ('Option Bytes'). It also provides concrete examples (RDP, nBOOT0) that distinguish it from the sibling tool stm32_read_option_bytes.

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 when to use the tool by giving examples like removing read protection, which suggests it's for changing MCU configuration. It doesn't explicitly mention alternatives, but the sibling stm32_read_option_bytes is distinctly for reading, providing context. 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.