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 clearly states the tool is headless, parses GCC output into structured diagnostics, returns a summary and flash/RAM usage from size output, and warns against raw log dumping. This gives the agent accurate expectations for execution and 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?

The description is two sentences with no wasted words. 'Headless build' is front-loaded, followed by the return contract and a direct handling instruction. Every sentence contributes meaningful 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?

The schema fully documents all three parameters, and the description supplies the return format, including diagnostics structure, summary, and size usage. Since there is no output schema, the explicit return details are especially valuable. Nothing critical for correct invocation 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 projectPath, clean, and configuration are already fully documented in the input schema. The description adds no parameter-specific meaning beyond the overall build behavior, so it meets the baseline but does not enhance parameter understanding.

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 starts with 'Headless build', identifying a clear action and the STM32 project context, then explains what the tool returns: structured diagnostics, summary, and flash/RAM usage. It doesn't explicitly distinguish itself from sibling tools like stm32_clean or stm32_flash, but the core 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 when to use it: for headless builds where structured diagnostics are desired, and it explicitly tells the agent not to dump raw logs into model context. However, it doesn't contrast this tool with siblings such as stm32_clean or stm32_flash, so alternative selection 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?

With no annotations provided, the description carries the behavioral disclosure burden. It clearly reveals that deleting files requires confirm:true and that the default is refusal, which is essential for a destructive operation. The mention of 'flashing hardware' is slightly out of scope for a clean tool, but the core deletion behavior is transparent.

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 short and front-loaded with the primary purpose. The second sentence is slightly muddied by referencing 'flashing hardware' in a clean tool, but overall it is compact and readable with no significant 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 two-parameter tool with full schema coverage, the description plus schema is sufficient to invoke it correctly. It does not describe output or side effects beyond deletion, but the lack of an output schema makes that less critical. The main missing piece is explicit usage context, which is already scored separately.

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 projectPath and confirm are already documented. The description adds that the default is 'refuse,' which merely mirrors the schema's default:false. It does not meaningfully extend parameter understanding beyond 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?

The description states the action and target clearly: 'Clean build artifacts.' It is specific enough to distinguish from siblings like stm32_build and stm32_flash, though it does not explicitly name alternatives. It stops short of a 5 because the differentiation is implicit rather than stated.

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

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

Usage is implied: this tool is for removing build artifacts, and the confirm warning signals that deletion requires explicit consent. However, there is no explicit when-to-use guidance or comparison with alternatives, leaving the agent to infer the appropriate 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 provided, the description carries the full burden and discloses the two most important behaviors: it mutates a file ('patches') and triggers a regeneration side effect. 'Idempotent' adds material safety context—re-running with the same inputs yields consistent results. It doesn't specify overwrite behavior or prerequisites, but it goes well beyond a bare 'configure pins' statement.

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-load the action ('Patches pin config in an existing .ioc') and place the idempotency note second. There is zero filler—'Patches,' 'existing .ioc,' 'regenerates,' and 'Idempotent' each carry distinct, necessary 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?

The core invocation contract is present—what it patches, where, and that it regenerates—sufficient for a 2-parameter call. However, with no output schema and no annotations, gaps remain: return behavior, whether regeneration implies a build, and conflict/error handling for pin modes are all undisclosed. Adequate for basic invocation, but thin for a mutating tool with side effects.

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%, with both projectPath and pins described in the schema, so the baseline is 3. The description confirms projectPath points to an existing .ioc but adds no detail on pin naming conventions, mode values, or label usage for the nested objects, which remain undocumented.

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

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

The description uses the specific verb 'patches' with a precise resource ('pin config in an existing .ioc') and discloses the regeneration side effect. This clearly distinguishes it from siblings like stm32_create_project (which would not target an existing .ioc) and stm32_patch_user_code (which targets user code, not pin config).

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

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

The phrase 'existing .ioc' implies this tool is for modifying already-created projects rather than initial setup, pointing away from stm32_create_project and stm32_generate_code. However, it never explicitly states when to prefer this tool over alternatives or what conditions exclude it, leaving routing mostly 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 carries the full burden. It mentions that it 'writes' and 'generates' files, but does not disclose potential side effects such as overwriting existing projects, whether it is destructive, or any other state changes. This is insufficient for a tool that creates project files.

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 extremely concise, fitting in two sentences, and is well-structured with the argument list first followed by the action. No unnecessary words 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?

Given the tool's complexity (6 parameters, nested objects, enum), the description provides a sufficient high-level overview of inputs and outputs. It lacks details about presets (e.g., what clock presets are available) and does not mention return values or error cases, but these are not critical for a creation tool and are not specified in the schema either.

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 provides full coverage (100%) with descriptions for each parameter. The description adds minor structural detail (e.g., pins[] format and clock object fields) but does not significantly enhance understanding beyond the schema. Baseline of 3 applies due to 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?

Clearly states the tool's function: 'Writes a valid .ioc and generates the CubeIDE project.' It lists all arguments in a structured way and distinguishes itself from sibling tools like stm32_configure_pins or stm32_generate_code by focusing on project creation.

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 creating a new project but does not explicitly state when to use it versus alternatives (e.g., when to use stm32_configure_pins instead). It lacks explicit guidance on context or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It presents the operation as a reporting/diagnostic action and enumerates concrete output categories, including problem types such as missing packages and non-ASCII home paths. It does not explicitly state 'does not modify anything,' but 'Reports' strongly implies a non-mutating health check, which is sufficient for a zero-parameter 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 two sentences with no filler. The first sentence front-loads exactly what the tool reports, and the second sentence gives crisp operational guidance. Every word 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 parameterless diagnostic tool with no output schema, the description is nearly complete: it lists the categories of information returned and when to run it. It leaves minor gaps such as the exact return format or how problems are represented, but an agent can reliably invoke and interpret this tool with the given information.

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 has zero parameters, so there are no parameter semantics to clarify. Per the baseline for 0-parameter tools, a score of 4 is appropriate; the description does not need to compensate for undocumented arguments because none exist.

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 'Reports' and clearly identifies the resource: the STM32 development environment's resolved paths, versions, installed firmware packages, and detected problems. It is unmistakably distinct from the sibling tools, which create, configure, generate, patch, build, clean, flash, or read projects.

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 explicit usage guidance: 'Run this first' and 'every other tool should suggest it on failure.' This tells the agent exactly when to invoke this tool relative to all alternatives, which is strong usage guidance for a diagnostic entry point.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a safety behavior: 'Default is refuse' and confirm must be true, and it exposes a reset flag (-rst). However, it does not mention that flashing overwrites target memory or other potentially destructive side effects, which is a notable gap for a hardware-programming 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 extremely compact, conveying the operation and a key safety requirement in two short sentences. However, the command-line snippet is not front-loaded with a plain-language purpose statement, making it less accessible. Still, there is no wasted content.

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 destructive potential and the presence of many sibling tools, the description is incomplete. It omits prerequisites, side effects, when to invoke it in the workflow, and what happens on success or failure. The confirmation gate is helpful but does not compensate for the missing context around a hardware write operation.

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 covers 100% of parameters with descriptions and defaults, so the baseline is 3. The description adds minimal semantic value: it maps port/elf/reset to command-line flags but does not explain parameters beyond what the schema already states. No extra meaning is provided for 'confirm' beyond repeating its importance.

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 command-line invocation ('STM32_Programmer_CLI -c port=SWD -w <elf> -rst') which implies writing an ELF to a target, but it does not explicitly state 'flash' or 'program' in natural language. It is specific to STM32 but may be opaque to an agent unfamiliar with STM32_Programmer_CLI flags, so it is more vague than 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?

The description mentions 'Requires confirm: true' as a necessary condition, but gives no guidance on when to use this tool versus siblings like stm32_build or stm32_generate_code. There is no mention of prerequisites (e.g., a built ELF) or use cases where flashing is appropriate.

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

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

No annotations are provided, so the description carries the full burden. It states 'generate' which implies file writing, but does not disclose potential overwriting or other side effects. It is neither fully transparent nor misleading.

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 with no redundancy or irrelevant content. It is well-structured and front-loads the core action.

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 tool with one parameter and no output schema, the description is complete enough. It specifies the prerequisite (existing .ioc) and the action, though it does not explain post-generation behavior. This is acceptable given the simplicity.

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 a description for the sole parameter, projectPath, indicating it can be a directory or .ioc file. Since schema coverage is 100%, the baseline is 3; the tool description adds no extra semantic beyond 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?

The description clearly states the tool's function: loading CubeMX config and generating the project. It specifies the target (an existing .ioc file) and distinguishes it from siblings like creating a new project or configuring pins.

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 (when an existing .ioc file is present) and differentiates from creation tools. It does not explicitly mention alternatives, but the context of sibling tools and the direct wording make the usage clear enough.

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 description goes well beyond the schema by disclosing that writes are strictly confined to marked regions, that it must fail loudly on missing/unbalanced markers, and that generated init functions must never be touched. Since no annotations are provided, this behavioral disclosure is especially valuable for an agent deciding whether the operation is safe.

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 information-dense: it lists the arguments, states the exact write boundary, and specifies failure and safety constraints in only two sentences. Every sentence earns its place with no filler.

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

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

The description covers the essential invocation details, marker behavior, and failure constraints for a moderately complex patching tool. It does not describe return values or handling of non-existent files, but for a write-oriented tool with no output schema these are minor gaps given the strong behavioral guarantees provided.

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 value by giving concrete section examples (PD, 2, WHILE, 4), clarifying the mode options, and tying the content parameter to insertion between markers, which enriches the otherwise minimal schema 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 writes content only between USER CODE BEGIN/END markers, giving a specific verb and resource. This distinguishes it from sibling tools like stm32_generate_code and stm32_flash, which perform broader generation or flashing 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 usage context is implied: use this tool to safely modify user-editable sections in STM32-generated files. However, it does not explicitly name alternatives or state when not to use it, such as when regenerating code or modifying generated initialization logic.

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 behavioral burden, and it does so well: 'summarises' and 'reads' convey a non-mutating, read-only operation, and the source-of-truth scope (.ioc vs generated code) is explicit. It does not disclose failure behavior for invalid paths or missing .ioc files, but for a simple inspection tool these omissions are minor.

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 of roughly 25 words total, with the action and output list front-loaded and the scope clarification second. Every clause earns its place; there is no filler, repetition, or redundant restating of the tool name.

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 low-complexity tool with one parameter, no enums, and no output schema, the description is nearly complete: it states the action, the input, the data source, and the content of the summary, which partially compensates for the missing output schema. It omits edge-case behavior (missing .ioc, invalid project) and exact return format, but nothing essential to a correct first invocation is 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 description coverage is 100%, so the parameter is fully documented structurally. The description adds only marginal nuance — 'existing project' implies a precondition that the path must already point to a real project, and 'Reads the .ioc' reinforces the schema's .ioc-file option. This is a small addition over the baseline set by complete 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 ('Summarises') against a specific resource ('an existing project') and enumerates the exact deliverables: MCU, clock tree, configured pins, enabled peripherals, FreeRTOS status. It further distinguishes itself from siblings by scoping the input source to the .ioc file, making it clearly the inspection tool among create/configure/generate/build/flash peers.

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 clause 'Reads the .ioc, not the generated code' gives a clear when-not boundary and implies this is the inspect-before-modifying step in the STM32 workflow. It does not explicitly name alternative tools for inspecting generated code, so it falls short of full sibling routing, but the context is strong enough for an agent to place it correctly.

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