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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so 'Read-only.' in the description is redundant. The one genuinely additive behavioral detail is the conditional cross-check against the compiler-generated .pin report when present, but error behavior and result shape are unaddressed.

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 primary action and followed by the conditional cross-check. No filler or repetition beyond the minor 'Read-only.' restatement of 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?

For a read-only extraction tool with no output schema, the description covers the source artifact, the scope (device and pin assignments), and the optional verification step. It could say more about what the returned pin data looks like, but nothing essential to 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 description coverage is 100%, so both parameters (project, workspace) are fully documented in the schema, including ambiguity resolution and env-var defaults. The description adds no parameter-level meaning beyond that, 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 ('extract') and precise resources: device and pin assignments from the .acf CHIP block, plus a secondary cross-check against the .pin report. This is distinguishable from siblings like acf_read_sections or acf_validate 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 implies when the tool applies (reading .acf CHIP pin data) and notes the conditional .pin cross-check when that report exists. However it gives no explicit guidance on when to prefer this over acf_read_sections, acf_validate, or project_inspect, leaving selection 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 and destructiveHint=false, and the description's 'Read-only' merely repeats that. It does add useful return-shape context (sections/entries carry line numbers), but says nothing about scoping, limits or how entries are delimited.

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 capability and immediately followed by the routing purpose and safety note. 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?

For a read-only inspection tool with a fully documented schema and no output schema, the description covers the essential return shape (sections/entries with line numbers) and intended workflow. Only finer output detail is absent, which is minor.

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 all four parameters (project, section, workspace, includeEntries) are already documented in the schema. The description's mention of 'sections/entries' aligns with but does not extend the schema, 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: reads the .acf as structured sections/entries with line numbers. That distinguishes it from the pin-oriented sibling acf_read_pins and from write tools like setacf_apply, though it never explicitly names an alternative.

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

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

Gives a clear use case: 'Use to discover which section holds a setting before writing,' which positions it ahead of the setacf write tools. It stops short of stating when-not-to-use or naming specific alternative readers.

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?

Adds real behavioral context beyond the annotations: dry-run preview by default, a confirm gate for the actual write, and a backup of the .acf file. This meaningfully softens the destructiveHint=true profile. It does not explain what happens on repeated runs despite idempotentHint=false, so not quite 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?

Three tight sentences with no filler: the action and targets come first, followed by the setacf rationale and the safety workflow. Every sentence 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 destructive, no-output-schema mutation tool, the description covers the key agent needs: what it rewrites, the preview/write gate, and the backup. Return details are unnecessary with no output schema; only the non-idempotency behavior 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%, so all five parameters are already documented. The description restates the confirm and backup semantics already present in the schema and adds no new syntax or format detail, making baseline 3 correct.

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 (Rewrite) plus the exact resource and the malformed forms it targets (bare "CHIP " or shell-escaped names) and the canonical output form. It also distinguishes itself from the setacf siblings by explaining that setacf is append-only and cannot perform this fix.

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?

Clearly signals when to reach for this tool (malformed CHIP headers that setacf cannot repair) and establishes the preview-first workflow with confirm:true required to write. It stops short of naming explicit alternatives or when-not-to-use conditions, but the routing context is strong.

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 readOnly, idempotent, non-destructive and closed-world, so 'Read-only' in the description is redundant. What adds value is the disclosure of what it checks (the bare "CHIP " header setacf leaves behind) and the downstream failure mode, which goes beyond the annotation profile.

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 action ('Statically validate an .acf...'), and the parenthetical defect detail earns its place by explaining the target. It is a single dense sentence, though the nested quoting makes it slightly heavy to parse.

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 should ideally indicate the shape of the validation result (pass/fail, list of defects). It explains what is checked but not what comes back, leaving a gap for a validation tool.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds no syntax, resolution, or ambiguity-handling detail beyond that, making the baseline 3 correct.

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 (validate) and resource (.acf) plus the exact class of defect it targets (the bare "CHIP " header) and why it matters (MAX+PLUS II compile failure). However, it does not distinguish itself from the sibling acf_repair_chip_headers, which addresses the same defect, so the boundary is left to inference.

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

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

Usage is only implied: the mention of 'defects that block compilation' suggests a pre-compile check, but there is no explicit when-to-use, no exclusion, and no pointer to acf_repair_chip_headers as the fix path. The agent must infer the workflow.

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, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it distinguishes implemented entry points from operations verified on this specific machine and from physical programming requirements, which is a machine-state nuance the annotations do not capture. It still says nothing about response shape, but the added distinction earns credit above baseline.

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, front-loaded sentences with no filler. The wording is jargon-heavy ('precise routes', 'implemented entry points') but every clause carries information, and the distinct mode it returns is stated first.

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 bears full responsibility for telling the agent what it receives, and it only gestures at this ('routes and runtime requirements', 'distinguishes... verification'). For an agent trying to act on the result, the actual contents and format remain under-specified, leaving a real gap for a zero-param tool whose entire value is its return payload.

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 to document and the baseline of 4 applies. The description correctly implies a no-argument query rather than any input-driven 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?

The description signals a capability-discovery tool that returns routes and runtime requirements across authoring, compilation, simulation, and GUI-only workflows. However, 'precise routes' is jargon that doesn't concretely say what a caller gets back, and it draws no boundary against discovery-oriented siblings like installation_status, probe_executable, or desktop_status. Purpose is inferable but not sharply stated.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. The closest siblings (installation_status, probe_executable) are equally discovery-flavored, yet the description gives the agent no rule for choosing between them.

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 destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds real context beyond that: it executes exactly one input, uses MCP-owned Win32/UIA rather than host-specific calls, and always returns a fresh screenshot/tree, telling the agent state must be re-inspected after each action.

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 sentences, front-loaded with the action scope, followed by implementation note, preconditions and the inspect loop. Dense but mostly economical; 'no host-specific calls' is a slightly opaque phrase that does not fully 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?

For a 6-parameter, nested-object mutation tool with no output schema, the description covers the essential call contract: prerequisites, one-action scope, and the fresh screenshot/tree return value. It leaves operationId retry/caching semantics entirely to the schema, but those are documented there.

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 the nested 'parameters' property documents each action's arguments in detail. The description only restates the observationId/windowId freshness requirement, adding little syntax or format meaning beyond the schema, 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?

Specific verb ('Directly execute') plus a precise resource and scope ('ONE click, hover, key chord, Unicode text entry, value change, drag, scroll, secondary UI action or activation'). The single-action framing plus 'return a fresh screenshot/tree' cleanly separates it from the observation-oriented siblings like desktop_observe.

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?

States the precondition ('Requires latest observationId/windowId') and the workflow expectation ('Inspect after every input'), which tells the agent to re-observe between actions. It does not explicitly name desktop_observe as the alternative, so the routing is implied rather than spelled out.

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, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the independent-backend isolation, the allowlist restriction, and the crucial caveat that a successful launch does not imply readiness.

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

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

Three short sentences, front-loaded with the action and scope, then constraints, then the readiness caveat. 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?

With no output schema, the description carries the return-value burden and does so: it states it returns real windows and tells the agent to observe the returned window. It leaves some gaps, such as behavior when an instance is already running or what happens on failure, but is adequate for the task.

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% with only two optional parameters (root, program) and an enum fully documented in the schema. The description adds the notion that programs are allowlisted, which contextually frames the enum, but offers no syntax or default detail beyond what the schema already 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?

States a specific verb (Launch), a bounded resource (allowlisted MAX+plus II GUI), and the mechanism (independent Windows backend returning real windows). 'No shell or arbitrary executable' distinguishes it from a generic process launcher and from pipeline siblings like maxplus2_run.

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 when-not ('No shell or arbitrary executable') and a follow-up directive ('Launch does not prove readiness; observe the returned window'), which effectively routes the agent to desktop_observe/desktop_windows. It does not name those siblings explicitly, so it falls short of full alternative-naming.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the observation lifecycle note ('each input consumes its observation') and a diagnostics caveat, but the latter references a 'diagnostics' concept absent from the schema, so the added signal is thin.

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

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

Three sentences, front-loaded with the return payload, then the pre-action guidance, then a caveat. Tight and mostly waste-free, though the trailing diagnostics sentence is vague and slightly muddies the close.

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 correctly carries the return-value burden and lists the key outputs, plus the pagination model lives in the schema. It is complete enough to call correctly, though the one-shot observation semantics could be stated more explicitly.

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 eight parameters (windowId provenance, pagination offsets, includeText/includeScreenshot) are already documented in the schema, including the 'never invent one' warning. The description adds no parameter meaning beyond that, making the baseline 3 correct.

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 (observe/return) and resource (a MAX+plus II window) and enumerates the returned artifacts: native screenshot, UI Automation tree, focus, window bounds, and observationId. This lets an agent know exactly what it gets. It does not, however, distinguish itself from the adjacent desktop_status / desktop_windows siblings.

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

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

'Inspect before acting' implies the tool is a read step preceding desktop_action, which is useful guidance. But it names no alternatives, no explicit when-not conditions, and does not clarify how it differs from desktop_windows or desktop_status, leaving the agent to infer 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the cache TTL rules (ten minutes, twelve entries, server restart) and the fact that no separate host execution step is involved. It does not describe the shape or failure mode of a cache miss, 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?

Three tight sentences with the core purpose front-loaded and the cache constraints following. 'No separate host execution step exists' is slightly oblique but still earns its place by clarifying the architecture.

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 read-only retrieval tool with no output schema and full schema coverage, the description supplies the key missing context (cache expiry and the fact that no re-execution occurs). A brief note on what happens when the result is gone would complete 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?

Schema coverage is 100%, and the schema already documents both requestId (source of the ID) and root (installation root default). The description adds no parameter-level detail beyond that, 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 (Retrieve) and resource (a cached completed desktop result and its MCP image blocks), and qualifies it with 'without executing input again,' which differentiates it from the launch/observe/action siblings. It stops short of naming which sibling produced the result, so an agent must infer the pairing.

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 cache lifetime ('up to ten minutes, twelve entries, or server restart') implies when this tool is valid to call, i.e. only for recent operations. However, it never explicitly states when to prefer this over desktop_status/desktop_observe or what to do if the result has expired, so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real value by disclosing a build side effect ('Builds the bundled helper locally if needed'), that it runs locally with standard Windows components, and that it reports interactive desktop availability. The build step sits in mild tension with readOnlyHint but is disclosed rather than hidden.

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

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

Four short sentences, front-loaded with the primary purpose and the scope exclusion at the end. Each sentence carries distinct information (what it checks, build behavior, execution locality, boundary), with 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?

For a no-parameter-required diagnostic with no output schema, the description covers purpose, side effects, and scope adequately; return-value detail is not required. It could be stronger by stating the expected usage trigger, but nothing essential 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 single 'root' parameter is fully documented in the schema. The description adds no syntax or default-precedence detail beyond the schema's own note about MAXPLUS2_ROOT/discovery, so the baseline of 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 ('Check the MCP-owned Windows UI Automation/Win32 backend') and clarifies scope by excluding window manipulation. This distinguishes it from desktop_launch/desktop_action without opening their schemas, though it never names a sibling 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 negative boundary ('Does not launch or manipulate a MAX+plus II window') implies this is a pre-flight/diagnostic check, which is useful context. However, it gives no explicit 'use this before desktop_launch' routing or when-to-use statement relative to installation_status or capability_matrix.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the discovery semantics and disclosed return fields (HWND, PID, bounds, title). It does not say what happens when no windows are found or whether an active desktop session is required, but it goes beyond the annotations meaningfully.

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 high-value content (what is discovered and returned) followed by the ordering rule. The closing sentence, 'All agents call this standard MCP tool,' is promotional filler that does not help an agent decide or call correctly.

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-param read tool with annotations and no output schema, listing the returned fields and the required next step is sufficient to call it correctly. Minor gaps remain around empty-result and environment-precondition behavior.

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?

One parameter with 100% schema description coverage, so the schema already fully explains 'root' and its MAXPLUS2_ROOT default. The description says nothing about the parameter, which is acceptable at this coverage level but adds no extra meaning.

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: 'discover real windows/dialogs of installed MAX+plus II executables,' and even enumerates what each entry carries (HWND, PID, bounds, title). This clearly separates it from siblings like desktop_observe or desktop_action, though it never names those siblings directly.

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

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

Gives a concrete sequencing rule: 'Select exactly one returned windowId before observing/input,' which tells the agent this is a prerequisite step for the observation/input tools. It stops short of naming those alternatives or stating exclusions, so it is clear context rather than full when/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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds useful context: it reports stored rather than live colors, and warns that GDF color bits and custom previews cannot prove native display — genuine evidence caveats beyond 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?

Four dense sentences, front-loaded with the core action before the caveats and verification guidance. Every sentence carries information, though the domain jargon ('native Symbol Pinstub Names') makes it slightly heavy for the tool's simple one-parameter nature.

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 read-only inspect tool with annotations carrying safety and no output schema, the description covers purpose, scope, evidence limitations, and verification alternatives. It hints at the grouped role output without detailing return format, which is a minor gap given no output schema exists.

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% for the single optional 'root' parameter, which already documents that invalid explicit roots are refused. The description adds nothing further 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 only the [Colors] section of installed maxplus2.ini.' It also delimits scope precisely (the Colors section only) and clarifies the roles it separates, so an agent can tell it apart from other inspect tools like gdf_inspect or scf_inspect.

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 sets an explicit boundary ('Reports stored preferences, not live unsaved colors') and routes the agent to alternatives ('Verify visible colors using original Color Palette Preview and desktop_observe'). Clear selection context, though the routing is somewhat indirect and one named resource isn't a sibling tool.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds real context on top: it is paginated, it emits crossings/driver/dangling diagnostics, it expands bus ranges and WIRE mappings via bitTopology, and unresolved widths are surfaced explicitly rather than silently resolved. That is meaningful disclosure of output behavior, though it never states the response shape or limits.

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 is front-loaded and there is no filler, but the remaining text is a dense semicolon-chained stream of domain jargon (pin-on-wire, transparent WIRE, remote-name rules, driver/dangling diagnostics) that resists quick parsing. Compact, but readability is sacrificed for density.

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 and seven parameters, the description should carry more of the return-value burden; it hints at nets plus crossing/driver/dangling diagnostics but never describes the pagination envelope or what a net record contains. Adequate orientation for a complex EDA tool, 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?

Schema description coverage is 100%, so the schema already documents path, limit, offset, project, workspace, childLimit, and childOffset. The description adds nothing about any parameter except an oblique 'Paginated' nod to limit/offset, 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 concrete verb+resource pair ('Build source nets') with a clearly scoped domain object, and the title's 'Inspect original source connections' aligns with that intent. It does not, however, differentiate itself from nearby siblings like gdf_inspect, gdf_geometry, or acf_read_pins, so an agent gets the what but not the why-this-one.

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

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

There is no when-to-use, when-not-to-use, or alternative-routing guidance anywhere in the text. The agent is left to infer from jargon that this is the net-connectivity reader, with no pointer to siblings such as gdf_inspect or gdf_geometry that also inspect GDF content.

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, idempotentHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: preview/backup/atomic-apply semantics, that deleted symbols leave their wires behind, that duplicate wire names can connect remote geometry, and that legacy/ambiguous parameter records are preserved and refused for edits. It stops short of describing rollback behavior on partial failure.

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 dense but efficient paragraph: the core purpose leads, operands and prerequisites follow, and caveats close it out. Every sentence carries information, though the run-on enumeration of operations is somewhat heavy to parse in one pass.

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 12-operation, destructive, offset-addressed construction tool with no output schema, the description covers prerequisites, transactionality, verification caveats, and edge-case semantics (orphaned wires, legacy records). Return-value information is absent but no output schema exists, leaving response shape unspecified — 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?

Schema description coverage is 100%, so the schema already documents path, offsets, SHA-256, operations and their sub-fields. The description echoes the offset/SHA-256 requirements but adds no format or syntax detail beyond what the schema states. Baseline 3 is appropriate when the schema carries the load.

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 (construct) and resource (GDF v6) and enumerates the operation families: inserting SYM instances, naming wires/buses, editing parameter maps, normalizing NET_IDs, adding/deleting wires, symbols and annotations. An agent can tell this is a schematic-writing tool. It does not, however, distinguish itself from overlapping siblings such as gdf_edit, gdf_create, or gdf_wire_cleanup, which is the only missing piece for 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 supplies prerequisites (existing offsets and current SHA-256 required; preview unless confirmed; atomic apply) which imply the intended context, but it never says when to reach for this tool versus gdf_edit, gdf_create, or gdf_wire_cleanup. Usage is inferable from the operation list rather than 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?

Adds substantive behavior beyond the annotations: confirm=false yields a preview rather than an apply, and an existing file is never overwritten. Neither fact is derivable from destructiveHint=false/idempotentHint=false alone, so this is genuine added value; it stops short of describing what the call returns or any write-side effects on the target directory.

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 the action, then the safety default, then the workflow handoff. No filler; every clause carries decision-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?

With no output schema, the description should ideally say what a preview returns relative to an applied create, and it does not. It otherwise covers the mode toggle, the overwrite guarantee, and the follow-on tooling, which is close to sufficient for a 6-parameter creation tool.

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

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

Schema description coverage is 100%, so path, width, height, confirm, project, and workspace are already documented in the schema. The description only reinforces the confirm preview semantics already stated on that parameter, adding no syntax, defaults, or constraints beyond the structured fields.

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 ("Create a version-6 GDF sheet") with the concrete flavor that distinguishes it from other gdf_* writers, and explicitly names the sibling it is not: "Use gdf_construct for symbols/wires." An agent can pick between gdf_create and gdf_construct 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?

Gives clear context for use (blank sheet creation) and routes the agent to alternatives for the adjacent task (gdf_construct for symbols/wires, compiler/simulator for verification). It stops short of explicit when-not-to-use conditions, so it falls just below the top band.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral value by saying it reports writable and ambiguous/unsupported legacy forms, telling the agent what the result distinguishes. It omits pagination/budget behavior despite limit/offset/childLimit parameters.

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 primary action and resource. The final sentence earns its place by disambiguating from generic instance parameter assignments rather than padding.

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 read-only tool with no output schema, the description conveys what the output classifies (writable vs ambiguous/unsupported legacy forms) and the scope of the declarations. Nothing critical is missing, though pagination/budget semantics for the four paging parameters are left entirely to the 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?

Schema description coverage is 100%, so all seven parameters (path, limit, offset, project, workspace, childLimit, childOffset) are already documented in the schema. The description adds no additional parameter meaning, so the 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 ('Read') and resource ('native CONSTANT h/51/52 and PARAM h/53/54 declaration pairs'), and explicitly excludes a confusable concept ('not generic instance parameter assignments'). It implicitly distinguishes from the gdf_declarations_edit sibling via the read verb, but never names the edit tool as the write counterpart.

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 'Read existing' plus the clarification that these are source declarations/defaults rather than instance parameter assignments, which is a soft when-not signal. There is no explicit statement of when to call this versus gdf_declarations_edit or gdf_inspect.

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 destructive=true and non-idempotent. The description adds genuine context beyond them: what is preserved (native IDs, aliases, geometry, fonts), that a recoverable backup exists, and that a compiler/simulator must validate the result. It does not detail failure/rollback behavior, keeping it short of 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?

Four tight sentences, front-loaded with the edit scope followed by preservation guarantees and preconditions. Every sentence contributes; wording is dense but not 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 destructive, non-idempotent mutation with no output schema, the description supplies the key missing pieces: preservation semantics, backup/recoverability, and the requirement for a fresh hash and compiler validation. It is largely complete, though it could state what happens on validation failure.

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 and nested edit fields are already documented. The description reinforces 'requires both name and value' and 'fresh hash' but adds no syntax or format detail beyond the schema, matching 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?

States a specific verb+resource ('Edit... existing... CONSTANT/PARAM name/value pair') and scopes it tightly with 'only an existing unambiguous native'. The 'only existing' qualifier implicitly contrasts with creation siblings like gdf_create/gdf_declarations, but no sibling is named, so differentiation is inferred rather than explicit.

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

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

Gives clear usage constraints: only existing, unambiguous, native declarations, and mandates both name and value plus a fresh hash. It does not explicitly name what tool to use instead for creating or deleting declarations, so the when-not side is implied rather than enumerated.

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 (destructiveHint/readOnlyHint) by disclosing the SHA-256 freshness precondition, rejection of unsupported targets and overflow, lossless preservation of unrelated bytes, pre-write backup, atomic replacement, and the important caveat that moving a symbol does not move its wires. These are exactly the side-effect and safety facts an agent needs before mutating binary geometry.

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 with the operational mode (preview/apply) and target set front-loaded, followed by the safety preconditions and the gotcha warning. No filler or repetition 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 destructive, no-output-schema mutation tool the description supplies the missing contract: how preview differs from apply, the integrity precondition, what is preserved, and how to verify the result. Nothing needed to invoke it correctly appears to be 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 schema already documents every parameter, including recordOffset provenance and the maxItems one-operation-per-offset rule. The description echoes the SHA-256 requirement but adds no format, range, or interaction detail beyond the schema, 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 a specific verb pair (preview/apply) and enumerates the exact editable resources: GDF v6 root line coordinates, translations, symbol orientation, free annotation text. 'Existing records only' cleanly distinguishes it from creation siblings like gdf_create and gdf_construct.

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 when-not ('Existing records only') and valuable post-edit guidance ('recompile/export to verify circuit behavior'). It stops short of naming alternatives, e.g. gdf_move_connected for symbol+wiring moves or gdf_text_edit for text-only changes, leaving the agent to infer which sibling to reach for.

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 the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context the annotations do not: pagination semantics for root records and nested collections preserving offsets/counts, and that no compiler or GUI is required. It does not state return shape or error behavior, but the added pagination detail is meaningful.

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 dense sentences, front-loaded with the core verb, each carrying distinct information (what is decoded, operating requirements, paging model, and the connectivity caveat). Minor flourish in 'Strictly' and a slightly list-heavy first sentence, but 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 complex eight-parameter tool with no output schema, the description communicates scope, paging behavior, and a key semantic caveat (geometry != connectivity). It could go further on what the returned records look like or how the views differ, but it covers enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the view enum and the limit/offset/childLimit/childOffset paging fields. The description's mention of 'paginated root records and nested collections' corroborates the paging model but adds no syntax or defaults beyond the schema. 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?

The description names a specific verb ('strictly decode') and an explicit resource set (GDF/SYM v2..6 coordinates, wires/buses, symbol definitions, instances, pin positions, text anchors), which is far more informative than the title. It carves out a boundary by stating geometry does not prove connectivity and routing that need to netlist_export. It stops short of distinguishing itself from near siblings like gdf_inspect or gdf_connections, so it is clear but not fully 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?

There is one genuine exclusion ('use netlist_export for circuit connections'), which is useful. However there is no guidance on when to choose this over gdf_inspect, gdf_symbol_library, or sym_inspect, or what scenario (original vs compiled schematic) warrants it. Usage is largely implied by the enumerated data types.

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 destructive/not-idempotent/not-read-only, so the safety profile is covered. The description goes further by disclosing preservation semantics ('original unknown flags/shared symbol definitions retained') and prerequisite workflow ('original offsets/current hash, preview and backup required'), which are genuine behavioral facts not in 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?

Three dense sentences with the primary action front-loaded and no wasted filler. Each clause either scopes the operation, prevents operator confusion (wires vs lines) or states a prerequisite.

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 multi-operation tool, it covers the key risks: preservation of unknown data, hash-based concurrency, preview-then-apply, and re-inspection after applying. With 100% schema coverage and annotations covering safety, little is missing; only deeper detail on operation semantics and error behavior 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 coverage is 100%, so the baseline is 3 and the schema carries the field-level detail. The description adds conceptual meaning for several parameters by tying offsets to the original input and calling out the current hash and preview/backup requirements, mapping loosely onto recordOffset, expectedSha256 and confirm.

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 specific verbs (add/delete/resize/restyle) against a precise resource (root drawing lines, circles, arcs). It explicitly distinguishes itself from siblings by contrasting drawing lines with electrical wires and naming gdf_construct for connections, so an agent can route correctly without 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?

Names one explicit alternative and the condition that selects it: 'Use gdf_construct for connections.' Combined with the 'not electrical wires' caveat, this gives clear when-to-use guidance. It does not differentiate from other close siblings like gdf_geometry or gdf_edit, so it stops short of a full 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 closed-world scope, so the safety profile is covered. The description adds useful context beyond that: the read is strictly validated, the returned content is summarized rather than raw geometry, and connectivity is deliberately out of scope. It does not discuss limits or pagination behavior for this specific read, 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?

A single dense sentence-pair, front-loaded with what is read before the sibling routing. No filler, though the middle clause packs four sibling disambiguations which makes it feel dense rather than 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?

There is no output schema, so the description must convey what comes back; it does list the summary categories (labels, fonts, title fields, geometry counts) and notes connectivity must come from netlist_export. What it omits is the shape or size of that summary (e.g. counts vs. full lists), which leaves a small gap for a tool with no documented return structure.

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 all three parameters (path, workspace, compareWith) are already documented, including extension auto-append and workspace default resolution. The description only restates the compare behavior ('Optionally compare labels with another drawing'), adding no syntax or semantics beyond the schema. 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 (Read) and resource (strictly validated GDF/SYM schematic summary) and enumerates the payload: labels, fonts, title fields and geometry counts. It also names the sibling tools it is not (gdf_geometry, gdf_edit, netlist_export), so an agent can distinguish it 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?

Explicitly routes the agent: gdf_geometry for paginated original coordinates/instances/pin positions, gdf_edit for modifying existing v6 geometry, netlist_export for electrical connectivity. This covers both when-to-use-this and when-to-use-alternatives, with the deciding condition attached to each.

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

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

Annotations declare destructiveHint=true and non-idempotent, and the description adds real value beyond them: refusal conditions, precondition that compilation/export/simulation exist, wire-splitting behavior, and hash/preview/backup transaction semantics. Strong disclosure of mutation consequences.

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?

Dense and largely front-loaded, but the telegraphic fragment style ('Hash/preview/backup transaction', 'Bus bundles/unknown topology refused') sacrifices readability. Every clause carries information, yet the compression hurts comprehension.

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 complex destructive mutation tool with no output schema, the description covers preconditions, refusals, wire behavior, and transaction semantics. Safety profile is covered by annotations. Fairly complete, though alternative tools are not addressed.

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 parameters are fully documented in the schema. The description mentions orientation0..7, grid8, and the transaction model, adding marginal color but no syntax beyond schema. 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?

Specific verb+resource: move/rotate GDF6 placements on a grid with reconnection awareness. Distinguishes from gdf_edit/gdf_geometry siblings by emphasizing connectivity-preserving move. Title restates but description leads with the actual operation.

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?

Refusal conditions (bus bundles, unknown topology, changed terminal partition) imply when the tool will not work, but there is no explicit guidance on when to use this versus gdf_edit, gdf_geometry, or gdf_wire_cleanup. Usage context is implied rather than 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 (destructiveHint=true, readOnlyHint=false): it discloses the inspect→preview→apply workflow, the backup on apply, the exact removal scope ('only exact visible duplicate free DOC, preserving native pin labels'), that alignment moves anchors only, and the refusal behavior when space is insufficient. It even states what the tool will NOT infer, giving strong boundary transparency.

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?

Five dense sentences, but each carries distinct information and the scope statement is front-loaded. Slightly jargon-heavy, but no sentence is redundant; it is appropriately sized for a dual-mode diagnostic/cleanup tool.

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

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

For a 10-parameter, annotation-light mutation tool with no output schema, the description is largely complete: modes, apply/backup behavior, removal scope, and negative scope are all covered. It does not describe the inspection output shape, a minor gap given there is no output schema to lean on.

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 real semantics on top: the meaning of omitting vs supplying expectedSha256, that confirm=true applies-with-backup, and that alignOverlappingRightPins only relocates right-edge label anchors. These interpretations help beyond the raw 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 pair (inspect/clean) and resource (pin labels) scoped to GDF/SYM files, and names the exact phenomena it targets: 'pin/DOC duplicates and fixed-font same-row pin collisions.' This meaningfully differentiates it from generic siblings like gdf_text_format_inspect or gdf_symbol_refresh. It stops short of naming a sibling directly, keeping 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?

Gives explicit mode-selection conditions: 'Omit expectedSha256 to inspect' vs 'Supply a fresh hash to preview cleanup; confirm=true applies with backup.' That is clear when-to-use-this-mode guidance. It does not, however, point to an alternative tool for cases outside its scope, so the alternatives clause is missing.

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 'Read-only' sentence is largely redundant. The description adds modest context: inspection preserves default instance/parameter attributes and hashes/original bytes are used for insertion independently of an agent SDK. That is useful but thin against an already-complete annotation set.

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 two capabilities (list vs. inspect) in one sentence, then the read-only fact and downstream-usage note. Efficient overall, though the 'independently of any agent SDK' clause is jargon that slightly dilutes the close.

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 usefully previews return content (hashes, names, pins, extent, preserved default attributes). All parameters are optional and fully schema-documented, so the definition is largely self-sufficient, though the hash-vs-'original bytes' distinction and downstream use remain a bit 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?

Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description only maps path loosely to 'inspect one prototype' and hints at pagination via 'List', adding no syntax or format detail beyond the schema. 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 specific verbs and resource: 'List installed max2lib SYM files' and 'inspect one prototype' with named fields (SHA-256, pins, extent, default attributes). The two modes are clearly distinguished by the path parameter. It does not name any sibling (e.g., sym_inspect or gdf_symbol_refresh) to differentiate, so it falls short of a 5.

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

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

The description implies the two usage modes (list all vs. inspect one via path), but never states when to use this tool over sym_inspect, gdf_symbol_refresh, or sym_create, nor any exclusion condition. Usage is inferable but not explicit.

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

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

Annotations already declare destructive/not-read-only/not-idempotent, but the description adds substantial behavior the annotations cannot: shared definitions are split so unselected instances retain original bytes, retained fields (instances/NET_ID/parameters/placement/rotation), and that pin/interface and geometric contact changes are reported and require explicit allow flags. It stops short of stating auth/rate/undo specifics.

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

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

Four dense sentences, each carrying distinct information (mutation semantics, preservation guarantee, reporting/allow flags, verification path), with the primary action front-loaded. No filler, though the first sentence is slightly packed.

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 complex 15-parameter destructive mutation with no output schema, the description adequately covers the mutation, its preservation guarantees, the change-reporting/allow-flag contract and the verification expectation. Complete enough for correct invocation without explaining return values.

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 schema already documents all 15 parameters, and baseline is 3. The description adds only light cross-parameter meaning (hashing of templates implies the two SHA-256 checks; 'explicit allow flags' ties to allowDisconnected/allowInterfaceChanges) rather than new per-parameter semantics.

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/action (preview or apply a hashed SYM) against a specific resource (explicitly selected GDF instances/embedded symbols). The 'refresh embedded symbols from SYM' intent is unambiguous, but it never names or contrasts a sibling such as sym_edit or gdf_symbol_library, so the agent must infer the boundary.

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 context is implied ('explicitly selected GDF instances', preview default vs apply) and it adds a useful post-condition workflow ('Compile/export/simulate to prove actual connectivity'). However there is no explicit when-to-use-this-vs-alternative guidance compared with the many nearby edit tools.

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?

Adds substantial context beyond annotations: preservation of font/metrics/alternative text/opaque bits, refusal of certain label types, original-offset semantics for sequential operations, and printable Latin-1 restriction. Complements destructiveHint without contradicting it.

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

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

Four tight, front-loaded sentences that each earn their place: purpose, preservation, exclusion, ordering, encoding. 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 6-parameter mutation tool with no output schema, the description covers scope, side effects, ordering, and encoding constraints. Minor gap: destructive behavior and confirmation/preview semantics are left to annotations and 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?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description reinforces offset semantics but adds no parameter syntax or format detail 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?

States specific verbs (create, reposition, restyle, delete) and resource (root free DOC annotations), distinguishing it from siblings like gdf_geometry or gdf_declarations. Lacks explicit contrast with closest siblings such as gdf_text_format_edit.

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?

Description implies usage through scope constraints ('root free DOC annotations', 'refuses electrical labels or instance/pin text') but gives no explicit when-to-use guidance or named alternative tools for those excluded cases.

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

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

Annotations already declare this is a destructive, non-read-only, non-idempotent write, so the safety bar is partly met structurally. The description adds real behavioral context: it preserves electrical labels, shared definitions and opaque tails, states the encoding is exact/reversible for Chinese bytes, notes Chinese requires a Windows font, and recommends verifying glyphs in the original editor. It does not describe write ordering/failure behavior on a SHA mismatch, 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?

Four dense sentences, front-loaded with the scope/verb and then the encoding constraints; essentially no filler. Density of jargon makes it slightly harder to scan but every sentence carries information.

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

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

For a complex, destructive, no-output-schema edit tool this covers scope, alternatives of font selection, encoding rules, preservation guarantees and a verification recommendation. Remaining gaps (error/precondition behavior around expectedSha256, relationship to gdf_text_format_inspect workflow) are minor given annotations cover the 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 schema already documents syntax and defaults (baseline 3). The description adds cross-parameter meaning not present in the schema — that Chinese bytes in Windows-936 require a Windows font face — and reinforces width/height as explicit glyph/layout metrics rather than font size.

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 — 'Create/change only free root DOC text in GDF6 or standalone SYM2..6' — plus the font/metrics scope, which is more precise than the title alone. The scope restriction ('only free root DOC text', 'Preserves electrical labels...') helps separate it from broader edit tools, but it never names or contrasts with the close siblings gdf_text_edit and gdf_text_format_inspect.

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 through the scope constraint and the choices offered ('built-in font0..3 or Windows font face,size', 'Verify glyphs with original editor'), which tells the agent the intended operation shape. However, there is no explicit when-to-use vs gdf_text_edit / gdf_text_format_inspect guidance or prerequisite statement (e.g., run inspect 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real value beyond them: explicit latin1/windows-936 decoding with 'no guessed encoding' and malformed-encoding diagnostics. This tells the agent how results are produced and what edge cases surface. It stops short of describing output shape or access requirements.

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

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

Two compact sentences front-loaded with the inspected artifacts before the decoding and diagnostics notes. Dense but no wasted phrasing; the semicolon-packed second sentence is slightly terse but 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 an 8-parameter read tool with no output schema, the description names the returned categories (records, font strings, codes, metrics, raw bytes) and flags pagination plus malformed-encoding diagnostics. Adequate, though it does not explain result structure or the project/workspace scoping tradeoff.

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 all eight parameters (including the encoding enum and pagination) are already documented in the schema. The description reinforces the decoding choice and pagination but adds no syntax or meaning beyond the structured fields, 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 (Inspect) and clearly enumerates the resources: GDF/SYM q records, original font strings, built-in font codes, stored metrics, and raw text bytes. This distinguishes it well from generic gdf_inspect, though it never names the edit counterparts (gdf_text_format_edit) as its siblings.

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

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

The description explains what is inspected but never states when to prefer this over gdf_inspect, sym_inspect, or the text edit tools, nor any prerequisites. The agent gets no routing guidance despite a crowded 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?

Annotations declare destructive=true and idempotent=false, and the description meaningfully adds to that: it enumerates exactly what is destroyed (unannotated leaves only) versus what survives (named wires, pins, isolated nets, overlapping conductors), and discloses refusal and compile/simulate/backup behavior. This is real depth beyond the annotation flags.

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?

Dense but front-loaded: the removal scope leads, followed by preservation, invariants, refusal, and transaction semantics in tight sentences. No filler, though the telegraphic phrasing borders on terse.

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, non-idempotent mutation with no output schema, the definition covers the destructive surface, safeguards (preview/backup/fresh hash), and refusal boundaries. Return values need no explanation absent an output 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?

Schema description coverage is 100%, so path, confirm, expectedSha256, maxPasses, maxComparisons, project and workspace are already fully documented. The description gestures at the budget and hash (via 'fresh hash', 'exceeded budgets') but adds no syntax or format detail beyond the schema, which is the correct 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?

States a specific verb ('Remove') and a tightly scoped resource ('unannotated electrical leaf segments in GDF6 pin-bearing physical nets'), which cleanly separates it from gdf_edit and gdf_construct. The jargon is heavy but the intent is unambiguous to a domain agent.

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 'Remove only...' scoping and the preserve list implicitly tell the agent when this is appropriate, and the refusal conditions (unknown topology, exceeded budgets) bound its use. However, it never names an alternative tool or an explicit when-not condition, so routing versus siblings like gdf_edit remains 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 declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful context beyond that by naming the executables it locates and the specific information it reports from maxplus2.ini and bundled tools, though it does not discuss failure modes or permissions.

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 tight sentence front-loaded with the primary action and scope. Every clause adds specific, non-redundant information, and the trailing 'Read-only' note is short and clearly framed.

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 rich annotations and no output schema, the description adequately summarizes the return information an agent can expect. It does not elaborate on the optional root parameter or error cases, but the schema covers parameter semantics and the annotations cover safety, making the description nearly complete for this simple tool.

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

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

Schema description coverage is 100%, and the single optional 'root' parameter is fully documented in the schema, including default behavior. The description adds no additional meaning about this parameter, so the baseline of 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 uses a specific verb+resource pattern ('locate the MAX+PLUS II installation') and details what is reported (version info, device families, bundled tools). It clearly identifies the tool's focus, though it does not explicitly contrast itself with nearby siblings such as capability_matrix or probe_executable.

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 what the tool does and notes that it is read-only, but gives no guidance on when to use it versus alternatives. It does not mention prerequisites, context, or sibling tools that might also report environment or capability information.

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: it discloses what is destroyed (child process), what is preserved (build artifacts already written), what happens if you don't call it (abandoned job keeps running and holding the project directory), and that the action is not reversible. This is consistent with destructiveHint=true and adds real operational 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?

Three short sentences, front-loaded with the action and mechanism, followed by the usage rule and the consequence caveat. No filler 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?

For a one-parameter mutation tool with annotations covering safety profile and no output schema, the description supplies everything needed: what it does, why to prefer it, and the side-effect boundary. Nothing material 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 (jobId) and schema description coverage is 100%, so the schema already documents it fully. The description adds no format, source, or id-acquisition guidance beyond the schema, 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?

States a specific verb and resource — 'Terminate a running background job by killing its child process' — with the mechanism included. An agent can immediately distinguish this from job_status or any of the project/file editing siblings.

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

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

Gives explicit when-to-use guidance ('Use this rather than abandoning a job') and explains why the alternative is bad. It does not name a sibling tool (e.g. job_status) as the counterpoint, so routing is slightly inferential, but the condition that selects this tool is unambiguous.

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 adds genuinely new operational facts: the returned status set, elapsed time, live child-process count, and a 30-minute post-settlement retention window. It also explains the non-obvious semantic that a client timeout does not stop the underlying work, which is exactly the kind of behavior an agent cannot infer from the 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?

Four sentences, front-loaded with the action, then the rationale, then return contents, then retention. Every sentence carries distinct information and 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?

With no output schema, the description correctly carries the return-value burden by enumerating the status values and describing what accompanies them. For a one-parameter read tool, the retention window and timeout semantics close the remaining gaps an agent would need.

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 the single jobId parameter is already documented there as 'the jobId returned when the job was started with async:true.' The description restates the async:true provenance but adds no format, lifecycle, or error semantics beyond the schema, 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 ('Poll a background job started with async:true') and immediately scopes it to async-started jobs, which cleanly separates it from job_cancel and the synchronous plan/run siblings. An agent can tell what this returns (running/done/failed/cancelled plus timing and child-process counts) without opening anything else.

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 condition for use ('started with async:true') and a rationale that functions as a when-to-use rule: polling is the only way to retain a long compile after a client timeout. It stops short of naming job_cancel as the alternative for stopping work, so the routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the trailing 'Read-only' largely restates structured data. The description does add a behavioral detail beyond the annotations, namely that discovery is recursive and that per-project compiled artifacts are surfaced, but says nothing about ordering, truncation behavior when limit is hit, or scan cost.

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 filler, with the core action front-loaded and the safety note as a brief trailing clause. Every sentence 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?

With no output schema, the description does need to convey what comes back, and it does so at a high level (each project's already-compiled artifacts). Defaults and parameter semantics live in the schema, so nothing critical is missing, though a hint about result shape or ordering would help.

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 root, limit and maxDepth are already fully documented with defaults. The description corroborates 'root directory' and the recursive nature (maxDepth) but adds no syntax, format, or edge-case meaning beyond the schema. 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?

The description states a specific action and resource: recursively find .acf projects under a root and list compiled artifacts per project. That is distinguishable from generic sibling tools like project_files or project_inspect in spirit, but it never names or contrasts with those siblings explicitly, so an agent must infer the boundary.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives among the many project-related siblings (project_inspect, project_files, project_search). The only usage signal is implicit in the scanning 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds genuine value by clarifying that the output is the constructed command line itself, not side effects. It doesn't mention validation errors or what the returned plan looks like, but annotations carry most of the burden here.

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 efficient sentence, front-loaded with the verb and resource, and the key non-execution constraint is stated immediately. No waste, though the very terse style leaves no room for additional orientation that a 28-param tool might benefit from.

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 28 parameters, no output schema, and a sibling apply/run tool, the description covers the core non-execution behavior but says nothing about what the returned plan is, whether it validates inputs, or how it relates to maxplus2_run/setacf_plan/job_status in a workflow. Adequate given full schema coverage and annotations, but thin for a tool of this complexity.

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 schema does the heavy lifting and baseline is 3. The description's explicit framing of the mode categories (compile / timing analysis / simulation / object conversion) helps an agent mentally group the 28 parameters, adding real orientation value beyond the flat 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 (build the command line), resource (maxplus2.exe), and critically distinguishes itself from the sibling maxplus2_run by emphasizing 'WITHOUT running it.' That is exactly the distinction an agent needs to choose between plan and run.

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 the plan-vs-execute distinction clear through the phrase 'WITHOUT running it,' and the sibling maxplus2_run is implied as the alternative. It doesn't explicitly name maxplus2_run nor lay out when planning is preferred over direct execution, so it falls 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?

Annotations establish it is not read-only and not idempotent, but the description adds materially beyond them: a hard timeout, the fact that it reports which artifacts changed plus a parsed report summary, and the significant warning that the 2002-era Win32 process can block on modal dialogs. That blocking risk is exactly the kind of behavioral trait an agent needs and cannot get from 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?

Two sentences, front-loaded with the action and the modes, followed by the reporting behavior and the risk warning. No filler; every clause 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 30-parameter, non-idempotent execution tool with no output schema, the description covers purpose, output reporting, timeout, and a critical failure mode. The remaining gap is routing context against sibling tools, which keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already annotates all 30 parameters thoroughly (including per-flag notes like 'REJECTED by this build'). The description adds no parameter-level meaning of its own, which is acceptable at full coverage but earns only the 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 names a specific verb (Execute) and resource (maxplus2.exe), enumerates the four modes (compile/simulate/timing/convert), and states the reporting behavior (artifacts changed + parsed report summary). It is unambiguous what the tool does, though it never explicitly contrasts itself with the similar-looking siblings maxplus2_plan or simulate_and_verify.

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 no when-to-use/when-not guidance relative to siblings like maxplus2_plan, probe_executable, or simulate_and_verify. The only caveat offered is the modal-dialog warning, which is a risk note rather than routing guidance. The useful async guidance ('a client timeout does NOT stop the child process') lives in the schema, not the description.

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 mark this as a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds genuine behavioral context beyond that: that apply mode performs hash checking and creates backups, that unused addresses are initialized, and that a dry-run preview is returned when confirm is false. It does not describe failure behavior or rate/scope constraints, keeping it out of 5 territory.

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 sentences with the verb and resource front-loaded. The middle sentence about integer strings for arbitrary widths is slightly cryptic and could be read as conflicting with width being an integer, but overall there is little 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 file-writing tool with no output schema, the description does explain what is returned in preview mode and that apply is guarded by hash checking and backups. It is nearly complete for an agent to invoke correctly; only edge-case behavior (overwrite conflicts, error returns) is left 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%, so the baseline is 3 and the schema already documents all nine parameters in detail. The description adds marginal semantic value by tying 'initialized unused addresses' to the defaultValue parameter and noting that width/depth are explicit rather than inferred, though the 'integer strings' remark largely restates the values 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 (Generate) and resource (Intel/Altera MIF memory image), and the description of explicit WIDTH/DEPTH and initialization makes it clear this produces a memory-init file rather than a stimulus or netlist artifact. It does not name a sibling tool to differentiate from, but the resource is concrete enough to disambiguate from stimulus_write or project_edit_file.

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 'Preview or apply to a .mif with hash checking/backups' implies a preview-then-apply workflow, which is useful guidance, but there is no explicit statement of when to choose this tool over stimulus_write or project_edit_file, and no stated prerequisites beyond the schema's project/workspace scoping.

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: it discloses that work happens in a fresh temporary directory, that original files remain untouched, what is returned (source hashes, compiler evidence, exported files), that the netlist is synthesized logic with possible placement/identity changes, and that async/cancel are supported. The untouched-original-files claim is consistent with destructiveHint=false, though it does not explicitly reconcile non-idempotent repeated compiles. Since annotations are present, the bar is lower and this adds substantial 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?

Three dense sentences, front-loaded with the core action and followed by return values and caveats. Every sentence carries information, though the enumeration of return artefacts and caveats is somewhat packed.

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 having no output schema, the description enumerates return values, discloses the temp-directory mutation strategy, async/cancellation behavior, and the synthesized-logic caveat. Nothing an agent needs 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 schema already documents every parameter including path scoping, root, async, project, workspace, and timeout. The description only gestures at async/cancellation and adds no syntax or format detail beyond the schema, 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?

States a specific verb chain (copy, enable writers, compile) and the exact resource produced (structured port/instance/net connectivity). The mention of GDF/HDL/ACF/EDIF inputs and the original MAX+plus II writers clearly separates it from siblings like maxplus2_run or gdf_connections.

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: it is the tool that yields structured netlist connectivity, and it notes async jobs/cancellation, which hints at the async parameter. However, it never names when to prefer this over maxplus2_run or a plain compile, nor any exclusions.

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.' restates structured data rather than adding to it. What the description does add beyond annotations is the nature of the returned content (severity counts, statuses, device, diagnostics), which is useful given there is 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 short sentences, front-loaded with the verb and file types, with no filler. The trailing 'Read-only.' is redundant with the annotations and could be dropped, but the overall size is proportionate.

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 usefully enumerates what the parser returns (severity counts, statuses, device, diagnostics), which is the main thing an agent needs to know. For a zero-required-parameter read tool with full schema coverage and complete annotations, this is close to sufficient.

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

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

Schema description coverage is 100%, so all four parameters (path, project, workspace, maxDiagnostics) are already documented, including the 'optional if path is given' relationship and defaults. The description adds no syntax, format, or fallback detail beyond that, 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 precise verb (Parse) and the exact resource types (.rpt/.summary/.pin) plus the shape of the result (severity counts, statuses, device, diagnostics). It is clear what it does, though it does not differentiate itself from the sibling parse_tbl or explain why an agent would choose one parser over the other.

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 versus the many neighboring read/parse/inspect tools (parse_tbl, project_parse_file, project_inspect). The only usage-adjacent statement is 'Read-only', which is a safety note rather than a routing rule, so the agent must infer the context entirely.

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 and the trailing 'Read-only' largely restates it. The description does add one genuine behavioral trait: optional expected-value checking against the trace, though the mismatch-is-reported-not-thrown detail lives in the schema rather than here.

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

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

A single dense sentence with the core action, the input artifact and the output shape front-loaded, plus a two-word safety tag. No filler or redundancy.

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

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

With no output schema, the description correctly compensates by characterizing the return value as a time-indexed trace of inputs, outputs and buried nodes. It omits error behavior for a missing or malformed .tbl file and the interaction between full and limit, which is a minor gap given full schema coverage.

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 every parameter including the nested expect object and tolerance already carries its own documentation; the baseline is 3. The description only echoes this by mentioning 'optional expected-value checking' and adds no formatting or resolution detail 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?

States a specific verb (Parse) and resource (MAX+PLUS II Simulator result table, .tbl) and describes the shape of the result: a time-indexed trace of inputs, outputs and buried nodes. This is clearly distinguishable from sibling tools like parse_report and project_parse_file, which target different artifacts.

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 file-type scoping ('an existing ... result table (.tbl)') implies when the tool applies, but there is no explicit guidance on when to prefer it over parse_report, project_parse_file, or simulate_and_verify, and no stated prerequisites such as a completed simulation run.

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 asserts 'Read-only,' while the annotations declare readOnlyHint=false — a direct contradiction of a declared safety property, which the rubric treats as a score of 1. The valuable behavioral detail it does add (the binary can block forever on a modal dialog, and the probe is idempotent per the annotation) is undercut by the conflicting safety claim, which could lead an agent to skip the timeoutMs guard.

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 sentences, and the operative command and the pre-flight rule are front-loaded, which is good structure. However, the middle sentence ('Read-only and project-independent') is both the source of the annotation conflict and less load-bearing than the timeout/modal-dialog warning that follows it.

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

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

For a four-parameter, zero-required probe with no output schema, the definition covers the invocation, the working-directory expectation, the failure mode it exists to catch, and the default timeout. The remaining gap is what a successful probe yields back to the agent (version string vs. exit status), which matters for deciding whether to proceed to a compile.

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 semantics the schema does not carry: why cwd matters (MAX+PLUS II expects to run in the project directory) and that mode maps to the -v/-h flags. It does not explain what distinguishes the version and help probes behaviorally, but the extra project-layout context is real value.

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 and the exact underlying command: run `maxplus2 -v` (or -h) to verify the binary starts and returns. It also distinguishes scope ('project-independent') and separates itself from the compile-loop siblings like maxplus2_run by positioning itself as the prerequisite gate.

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 conditional trigger: 'Run this before trusting any headless compile loop,' with a rationale (blocking on a modal dialog) that tells the agent when the probe is worth the call. It stops short of naming the alternatives it should precede or stating when it is unnecessary, so it falls just under 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?

Adds real behavioral context beyond annotations: SHA-256 verification of each copied file, 'Preserves originals', 'excludes backup stores', and the caveat that it does not infer external hierarchy dependencies. This is consistent with destructiveHint=false and adds meaningful edge-case disclosure, though it omits failure/rollback 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?

Front-loaded with the core purpose and reasonably tight at three sentences. Minor awkwardness from the telegraphic 'Default all;' fragment, but 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?

For a clone tool with no output schema and fully documented params, the description covers the copy semantics, integrity checking, exclusions, and required follow-up steps. It does not describe the return/preview payload, but otherwise an agent has enough to invoke it correctly.

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

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

Schema description coverage is already 100%, so the schema fully documents all six parameters. The description restates the profile enum behavior (already in schema) and adds only the 'avoiding old SCF/TBL/reports' rationale, which is marginal added value. 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: 'Copy the project directory into a new directory'. An agent can immediately distinguish this from sibling project_create or project_restore_file because the copy-into-new-directory behavior is stated up front.

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 profile selection ('Default all; sources selects design extensions ... avoiding old SCF/TBL/reports in large projects') and suggests a follow-up workflow ('inspect and compile the copy'). Clear context, but it never explicitly states when NOT to use this tool or names an alternative.

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-readonly, non-destructive, non-idempotent behavior. The description adds useful context beyond that: it previews by default, refuses existing directories, creates an isolated directory, and sets END_TIME=0.0ns. It does not cover authorization or rate limits, so it stops short of 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 with no wasted words. The first sentence front-loads the creation action and artifact, and the second quickly covers default preview, refusal behavior, and the one-directory-per-design rule.

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 an 8-parameter creation tool with no output schema, the description adequately covers the key novel behaviors: preview default, refusal on existing directories, and the one-design-per-directory constraint. It could still say more about the non-idempotent nature or how the preview result should be consumed, but nothing critical 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 schema already documents all 8 parameters, including confirm, encoding, directory, workspace, device, and sourceExtension. The description adds only marginal parameter meaning (optional HDL source, isolated directory) and mentions END_TIME=0.0ns, which is not a parameter. Baseline 3 applies when the schema does the heavy lifting.

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 action (Create) and the resource (an isolated directory with a named CHIP .acf, optional HDL source) and mentions a constraint (END_TIME=0.0ns). It clearly tells the agent what artifact is produced, but it does not explicitly differentiate itself from sibling creation tools like project_clone or project_restore_file.

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 behavioral context — preview by default, refuse existing directories, one directory per design — which implies how to use the tool. However, it does not state when to choose project_create over alternatives such as project_clone or project_restore_file, so the guidance is only partial.

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, so the safety profile is partly covered; the description still adds material non-annotated behavior: preview-by-default semantics, the mandatory expectedSha256 concurrency guard for existing files, recoverable backups on writes/moves/deletes, and the binary-write refusal. Nothing here contradicts 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?

Three sentences, front-loaded with the operation set, then the default behavior, then the constraints and sibling routing. No filler and no repetition of the title or schema field text.

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 10-parameter mutation tool with no output schema, the description covers the important preconditions (SHA check, backup, preview) and the escape hatches (scf_edit, desktop tools). The gap is the return surface: with no output schema, the shape of a preview versus an applied result is left implicit, which is the one thing an agent cannot infer elsewhere.

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, but the description adds cross-parameter semantics the schema cannot: preview behavior is governed by confirm (default off), expectedSha256 is mandatory only for existing source files, and backups apply per operation type. It does not, however, add distinctions between write vs patch payloads beyond the schema's own field docs.

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 first sentence names the specific resource (one file) and enumerates the five concrete operations (write, exact-patch, copy, move, delete), so an agent can distinguish it from project_create, project_clone, or project_restore_file. It also explicitly separates itself from scf_edit and the desktop/GDF tools, which is exactly the differentiation a sibling-heavy tool needs.

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 affirmative conditions (preview by default; existing files need expectedSha256) and negative routing rules: general binary writes are refused, SCF scalar inputs belong in scf_edit, GDF drawing changes belong in desktop tools. This is explicit when-to-use / when-not-to-use / alternative guidance rather than implied 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, destructiveHint=false and openWorldHint=false, so the description is not burdened with the safety profile. It still adds real value by disclosing deterministic offset pagination and that byte sizes and supported text formats are returned — behavioral detail beyond the structured fields, and important given there is 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 tight sentences with no filler; the what-it-lists information is front-loaded and the pagination/return details follow immediately. Every clause carries information the agent can use.

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 covering the safety profile and no output schema, the description usefully characterizes the return payload (byte sizes, supported text formats, paginated offsets). It stops short of describing result shape or whether listing is recursive, which leaves a small gap for a tool whose output shape is otherwise undocumented.

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% (limit, offset, project, workspace all documented inline), so the baseline is 3. The description only restates the project/workspace scoping and mentions pagination generically, adding no syntax, defaults, or format guidance beyond what the schema already 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?

Specific verb (List) plus resource (project files) with an explicit enumeration of the file categories covered (sources, memories, schematics, waveforms, build artifacts) and the scoping context (selected project/workspace). It does not, however, differentiate itself from close siblings such as project_search or project_read_file, so an agent must infer the distinction.

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 by the name and the phrase 'under the selected project/workspace' — the agent can infer this is the enumeration tool versus a content-search or single-file reader. There is no explicit guidance on when to prefer it over project_search or list_projects, and no stated prerequisites or exclusions.

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 'Read-only' is largely redundant with structured data. The description does add value by naming what is inspected (compiled artifacts with timestamps, .rpt cleanliness), giving a sense of the operation's scope, but it discloses nothing about cost, failure modes, or behavior when the project is missing.

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

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

A single front-loaded sentence that leads with the verb and resource, then compresses the inspection contents into a tight list ending with the read-only note. 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?

With no output schema, the description carries the burden of describing returns, and it does so by enumerating the summarized artifacts, which is adequate for an inspect tool. Safety is covered by annotations. Minor gaps remain around error/precondition handling, but nothing essential to 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 description coverage is 100%, so both 'project' (name or .acf path) and 'workspace' (resolution directory) are fully documented in the schema. The description adds no parameter-level detail, 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 (summarize/inspect) and resource (one project), and enumerates the concrete contents returned: .acf sections, CHIP blocks, device, pin count, compiled artifacts, and .rpt cleanliness. It is clearly distinct from list_projects and the various editors, though it never explicitly contrasts itself with siblings like acf_read_sections or scf_inspect.

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

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

The phrase 'one project' implicitly signals single-project use as opposed to list_projects, and the enumeration of coverage hints at what questions it answers. However, there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. acf_read_sections for section-only reads), leaving the agent to infer the 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that: it discloses the returned artifacts (original path, bytes, SHA-256) and the presence of 'explicit limitations', which is meaningful output behavior given no output schema exists.

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 sentences: what it parses, what it returns, and which siblings to prefer instead. Front-loaded with the highest-value information and no filler or restatement of the title.

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 15-parameter multi-format parser with no output schema, the description covers formats, return metadata, limitations, and sibling alternatives. It does not map which parameters apply to which format, but the 100%-covered schema carries that burden, so nothing critical 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% across all 15 parameters, so the schema already documents pagination limits, time ranges, and format enum semantics in detail. The description adds only the passing hint of 'events in ns' and the paginated-symbols reference; with the schema doing the heavy lifting, baseline 3 is correct.

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 (parsing) and enumerates the exact resource classes it handles: GDF text/geometry, SCF logic events, ACF assignments, TBL traces, reports and EDIF connections. It also names sibling tools (gdf_geometry, netlist_export) and the cases they own, so an agent can separate this general parser from format-specific tools 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?

Explicitly routes two cases to alternatives ('Use gdf_geometry for paginated symbol definitions/placements and netlist_export for GDF circuit connections'), which is strong when-not guidance. It never states the positive trigger condition in so many words, so the 'when to use this' half is implied rather than spelled out.

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, and non-destructive, so the safety profile is covered. The description usefully adds that reads are bounded and return a SHA-256, but the 'expectedSha256 to avoid overwriting concurrent edits' phrase imports a write-protection concept into a read-only tool and references an absent parameter, muddying rather than clarifying behavior.

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

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

Two sentences, front-loaded with the core read action and file scope. However, the second sentence is spent on two parameters that do not exist in the schema, which is wasted and misleading content rather than earning 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 read tool with a fully documented 6-parameter schema and no output schema, the description covers the essentials (bounded reads, SHA-256 return). But its references to non-existent continuation and concurrency parameters leave an agent unable to reconcile the description with the actual interface.

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 all six parameters are well documented in the schema itself, so the schema carries the semantic load. The description adds no parameter detail and instead names two parameters (nextLine, expectedSha256) that are not in the schema, so the baseline of 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 (Read) and resource (a bounded line range plus exact SHA-256) and enumerates the supported file types (HDL, ACF, MIF, HEX, VEC, reports). This lets an agent distinguish it from mutation siblings like project_edit_file, though it never names an alternative tool 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?

It gives a small amount of usage context ('Use nextLine to continue and expectedSha256 to avoid overwriting concurrent edits'), but neither nextLine nor expectedSha256 exists in the schema, so the guidance points at non-existent parameters. There is no statement of when to choose this over project_files, project_parse_file, or project_edit_file.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds meaningful context beyond those: preview is the default behavior, binary bytes are supported, and an existing destination is backed up before restoration, which is important for understanding the safety model.

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 tightly written sentences with no filler. The core action and default behavior are front-loaded, followed by the required credential-like inputs, making it easy to scan.

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, 7-parameter tool with no output schema, the description covers the essential call behavior: default preview, required SHA-256 values, and backup-before-restore. It does not explain failure modes (e.g., SHA-256 mismatch) or the preview response shape, but the annotations carry the 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 every parameter is already documented in the input schema. The description restates the backup SHA-256 requirement and the current-destination SHA-256 condition but adds no syntax, format, or interpretation details beyond what the schema provides. 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?

The description states a specific verb (restore) and resource (file from this project backup store), and notes it handles binary GDF/SCF bytes. It implicitly distinguishes itself from sibling read/edit tools by focusing on backup restoration, but it does not explicitly name an alternative or contrast 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?

The description covers operational context: preview by default, backup SHA-256 required, and current destination SHA-256 required if the file exists. However, it does not explicitly say when to choose this tool over siblings like project_edit_file or project_read_file, leaving usage 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are bounded, truncation and oversized-skipped files are surfaced explicitly, and binary bodies are not inferred — all useful for interpreting 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?

Two tight sentences that front-load the core action and evidence format, with no filler. Every clause adds a distinct constraint or 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 read-only search with no output schema, the description covers the key result-handling behaviors (bounded output, explicit truncation/skips) and scope limits, which is enough for correct invocation. It stops short of naming alternatives or describing matching semantics, leaving minor gaps.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including the nonempty-literal and case-sensitivity semantics. The description's 'literal string' wording only mildly reinforces the query semantics beyond the schema, 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 (search a literal string across project text files) plus the evidence format (file/line). It also scopes what it does NOT cover by noting binary GDF/SCF content is excluded, which differentiates it from gdf/scf and project_read_file siblings, though no sibling is named outright.

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 'supported project text files' and 'binary GDF/SCF content is not guessed' phrases implicitly delimit when it applies, but there is no explicit when-to-use guidance or named alternative for reading a known file or searching binary content.

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 the safe read-only/idempotent/non-destructive profile, so the bar is lower. The description still adds real behavioral context: the 32MiB file ceiling and the explicit set of unsupported cases (internal EDIF nets, ambiguous arrays, INOUT), which an agent needs to anticipate partial 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?

Three sentences, no filler, with the core action front-loaded and the workflow hint last. Minor typo ('up to32MiB') and slight density but overall efficient.

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, so the description carries some burden, but for a read/inspect tool it adequately conveys input source (.edo), transformation (port→simulator name mapping, vector ranges, flattening), and unsupported cases. Only the return shape is left implicit.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters (path, limit, offset, project, workspace, childLimit, childOffset). The description adds no parameter-level detail such as path scoping or pagination syntax, so 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+resource ('Read an exported .edo file') and precisely what it produces: mapping top-level input/output ports to MAX+plus II Simulator names. This clearly distinguishes it from siblings like scf_ports_import or scf_inspect, which handle different stages.

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 prescribes the workflow: 'Use netlist_export then inspect this fresh file,' which names the producer/alternative. It gives clear context for when this tool applies but does not state exclusions or contrast against other inspect tools beyond the netlist dependency.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), but the description adds the crucial behavioral fact that it will never overwrite an existing file, which explains the non-idempotent hint concretely. It also ties into the verification workflow, which 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?

Three dense sentences that front-load creation and scope, then units/grid, then the overwrite and verification caveats. Little waste, though the verification sentence drifts slightly from the tool's own 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 6-parameter file-creation tool with no output schema and fully documented inputs, the description supplies format version, time units and grid, event-value domain, overwrite policy, and a verification recommendation. It omits the confirm preview/apply default, but the schema already states 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?

Schema description coverage is 100%, so all six parameters are already documented, including the 0.1ns grid and the 0/1/X/Z value domain. The description restates input names and event values without adding syntax or constraints 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: create a version4 SCF waveform file directly, explicitly bypassing the VEC and GUI pathways. That distinguishes it from sibling tools like scf_from_compiled_create, though the sibling is not named outright.

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 'directly without VEC or GUI' implies when this creation path applies, and it prescribes using a matching compiled netlist plus original simulator for verification. However, it never names an alternative tool or an explicit when-not condition, so routing between it and scf_from_compiled_create 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.