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

With no annotations, the description carries the full behavioral burden. It states what the tool does but omits important traits: whether simulation must be running, what happens when the breakpoint triggers, whether breakpoints persist across steps, and required permissions or session state.

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

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

The description is a single concise sentence with no wasted words, but it is under-specified rather than complete. It is front-loaded but too terse for a tool with behavioral side effects.

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

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

The tool modifies simulation state and has two parameters, yet the description lacks context about the simulation session, signal path conventions, breakpoint behavior, and condition defaults. No output schema exists, so the description should do more to explain the effect of adding a breakpoint.

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

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

Schema description coverage is 0%, so the description must compensate. It loosely references 'edge or change' but does not explain the signal parameter format or the exact condition enum values (posedge, negedge, change) or the default behavior when condition is omitted.

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

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

The description states a specific verb and resource: 'Add a breakpoint'. It also clarifies that the breakpoint applies to a signal edge or change. This is clear enough to distinguish from remove_breakpoints, though it does not explicitly name alternatives.

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

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

The description gives no guidance on when to use this tool versus alternatives such as step_simulation or remove_breakpoints. It does not mention prerequisites like an active simulation session or loaded design.

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

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

No annotations are provided, so the description must carry the full burden of disclosure. It implies that the operation changes project state ('Add'), but it does not say whether the files must already exist, whether a new fileset is created or the fileset must already exist, what happens on a partial failure, or what the response is. For a write operation with no annotations, this leaves significant gaps.

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

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

The description is a single sentence with no filler, and it presents the action first. Nothing is wasted. However, the brevity comes at the cost of all the missing information noted above.

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?

This is a write tool with no annotations and no output schema. The description does not state the project-state prerequisite or the relationship to load_board_xdc and add_sources. Therefore, it is not complete enough for an agent to call it confidently without inspecting other tools.

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

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

Schema description coverage is 100%: 'files' is documented as absolute paths to .xdc files, and 'fileset' is documented with a default of constrs_1. Because the schema already explains all parameter meaning, the baseline is 3. The description adds no extra detail, such as validation or ordering rules.

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

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

The description names a specific verb and resource: 'Add XDC constraint files to the current project.' An agent can understand the action. However, it doesn't distinguish this tool from the sibling tool load_board_xdc, which has a similar role (loading XDC files), or from add_sources; therefore, an agent facing similar tasks must guess.

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 guidance on when to use this tool versus alternatives such as load_board_xdc or add_sources. It also does not state a prerequisite—for example, that a project must already be open—or explain when adding constraints to a fileset is appropriate. The meaning must be 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?

With no annotations, the description carries the full burden; it does disclose the mutation mechanics (cell creation plus set_property -dict for CONFIG.*), which is genuinely useful. However it omits prerequisites (open BD), failure behavior (duplicate cell_name), and whether the design is saved.

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 core action, then the conditional config behavior. Nothing is wasted.

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

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

No output schema and no annotations, so the description should cover more: the required open-block-design context, the returned cell handle, and error cases are missing. For a 3-parameter mutation tool it is adequate but leaves clear 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 baseline is 3, but the description adds real meaning: it explains that the 'config' object is applied as CONFIG.* properties via set_property -dict, which goes beyond the schema's bare 'Dict of CONFIG.* properties' wording.

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 ('Add an IP core to the current block design') and even gives the equivalent Tcl command, so the operation is unambiguous. It does not explicitly distinguish itself from close siblings like add_module_to_bd (RTL module) or create_ip.

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 'to the current block design' implies a block design must already be open, but that prerequisite is never stated. No when-to-use vs. alternatives (add_module_to_bd, create_ip, configure_bd_cell) guidance is given.

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

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

With no annotations, the description carries the disclosure burden well: it names the underlying Tcl operation, explains how `config` maps to module parameters, and notes the non-obvious quoting behavior for string parameters. It does not mention failure modes, duplicate cell-name behavior, or side effects, which keeps it from a 5.

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

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

Two tight sentences front-load the core action and follow with only the config syntax needed to invoke the tool correctly. Every sentence adds usable information without 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 three-parameter mutation tool with no output schema and no annotations, the description covers the main invocation details: source prerequisite, target context, underlying command, and config syntax. It could be slightly more complete by stating that a block design must be open or what happens if the cell already 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 coverage is 100%, so the baseline is 3, but the description adds meaningful detail: `config` sets module parameters in `CONFIG.*` form, with a concrete example and an important rule about preserving quotes for string values. This goes beyond the schema’s brief 'Dict of CONFIG.* parameters'.

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

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

The description states a specific action—adding an RTL module to the current block design—and names the underlying Vivado command (`create_bd_cell -type module -reference`). It clearly distinguishes the resource as an RTL module rather than an IP, which helps separate it from siblings like add_ip_to_bd.

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 useful context by pointing to add_sources for getting the RTL into the project and specifies that the module is added to the current block design. However, it does not explicitly compare itself to add_ip_to_bd or state prerequisites such as an open block design.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether this requires an active simulation, whether it modifies simulation state, how duplicate signals are handled, or what errors occur for invalid signal names.

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

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

The description is a single front-loaded sentence with no wasted text. However, it is under-specified for the tool's context rather than optimally concise.

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

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

Given no annotations, no output schema, 0% parameter documentation, and many sibling simulation tools, the description is not complete enough. It omits required session state, signal-path format, and expected behavior when signals cannot be resolved.

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

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

Schema description coverage is 0% for the single `signals` parameter. The description repeats that signals are added but does not explain the expected string format, such as hierarchical signal paths, wildcards, or scope qualification.

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: adding signals to a waveform viewer. An agent can understand the basic action, but the description does not distinguish it from nearby simulation tools such as get_signal_value or get_simulation_objects.

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

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

Provides no guidance on when to use this tool versus alternatives, whether a simulation session must already be running, or what prerequisites apply. The waveform-viewer context is implied, but no explicit usage conditions or exclusions are given.

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

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

With no annotations, the description carries the burden of disclosing behavior. It does flag two consequences beyond simple file addition: setting the top module and updating compile order. It does not state permission/precondition requirements (open project), duplicate-file handling, or error behavior, leaving meaningful gaps for a mutation tool.

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

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

Two short sentences, zero waste, with the primary action front-loaded and the optional side effects in the second sentence. Nothing needs trimming.

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 mutation tool with no annotations and no output schema, the description covers the core action and side effects but omits prerequisites (open project) and any indication of what is returned or how failures surface. Adequate but with clear 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% and every parameter is documented in the schema, so the baseline is 3. The description adds only the accepted file extensions for 'files'; it does not clarify fileset semantics (what a fileset is, what happens to the default sources_1) beyond the schema text.

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 (add) and resource (HDL source files) with accepted formats (.v/.sv/.vhd), which separates it from siblings like add_constraints or add_ip_to_bd. It does not explicitly name sibling alternatives, so a 4 rather than a 5.

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

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

The phrase 'current project' implies a project must already be open, and 'optionally' signals that set_top is discretionary. However there is no explicit when-to-use vs. when-not guidance, no mention of what to do if files already exist in the fileset, and no pointer to alternatives.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the concrete wiring effects (FIXED_IO / DDR / clocks) but omits whether existing configuration is overwritten, whether the operation is reversible, and what prerequisites are required.

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

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

The description is two sentences, front-loaded with the core action and followed by concrete effects and a GUI analogy. 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?

Given the fully documented two-parameter schema and no output schema, the description is largely complete for invoking the tool correctly. It could still mention block-design prerequisites or side effects on existing PS7 configuration, but the core context is present.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description implies the cell target and board-preset behavior but adds no syntax or meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: apply the Zynq-7000 processing_system7 board preset to a PS7 cell. It adds concrete effects (wires FIXED_IO / DDR / clocks per board definition) and a GUI equivalent, making it distinguishable from generic BD configuration 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?

It gives clear usage context: apply to a freshly added PS7, equivalent to Run Block Automation. However, it does not explicitly name alternatives such as configure_bd_cell or state when not to use this 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?

No annotations are provided, so the description carries the full burden. It does not say that this mutates the block design, that it is effectively an all-or-nothing operation over every addressable interface, whether existing manual address assignments are overwritten, or that a BD must be open with connected cells. With zero parameters, 'auto' implies no targeting, but nothing confirms the side effects.

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

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

One short sentence, front-loaded with the action. The trailing parenthetical duplicating the tool name is wasted characters but the overall length is appropriate.

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?

A state-mutating, zero-argument block-design operation with no annotations and no output schema needs at least prerequisites (open BD, existing cells/connections) and a note on what changes. The description supplies neither, leaving the agent unable to predict or verify the effect.

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 per convention the baseline is 4. The description does not need to explain parameter meaning, though it could have made the implicit 'no arguments = all interfaces' contract explicit.

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 verb (auto-assign) and resource (addresses in the BD address editor), but the parenthetical '(assign_bd_address)' simply restates the tool name, and 'BD address editor' is only marginally more context than the name itself. It is more than a pure tautology but not a clean, specific statement of what gets assigned (slave segments, memory ranges) or to what.

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 adjacent BD tools such as auto_connect_axi, connect_bd_net, connect_bd_intf_net, or configure_bd_cell. An agent must guess that this is the post-connection step to run after wiring a BD with addressable interfaces.

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

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

With no annotations, the description carries the full burden and does disclose meaningful side effects: it inserts an AXI interconnect and adds clock/reset hookups, which is real context beyond the name. It does not say whether existing connections are overwritten, what happens on failure, or whether a block design must be open, which matters for a design-mutating operation.

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 sentence with no filler, and the effect plus its side effects are front-loaded. Leading with the underlying Tcl invocation rather than the outcome is slightly less agent-friendly, but it is efficient overall.

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 three-parameter, design-mutating tool with a nested options object, no annotations, and no output schema, the description should say something about the result (whether the created interconnect is returned or named) and about preconditions. It covers the core action and side effects but leaves those 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 master, slave, and the options key/value object. The description reinforces the master/slave roles but adds nothing about the options object, such as which -config keys are meaningful or what the defaults are.

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 action (wire an AXI master to a slave) and the mechanism (apply_bd_automation with the axi4 rule), so the effect is unambiguous. It does not name the closely related siblings connect_bd_intf_net or connect_bd_net, so the agent must infer the distinction between automated AXI connection and a raw pin-to-pin connection.

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 tool is for AXI master/slave pairs and does the interconnect plus clock/reset work automatically. There is no explicit 'use this instead of connect_bd_intf_net when…' guidance, no stated preconditions (e.g. both IP must already be in the block design), and no when-not case such as already-connected interfaces.

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

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

With no annotations, the description carries the full burden, and it does disclose the key behavioral trait: auto_recover=true can restart the session. However, it omits what counts as 'unhealthy', whether a restart discards in-memory state or unsaved work, and how long the check takes, all of which matter for an operation that may restart a session.

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

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

Two short sentences with no waste, and the core purpose is front-loaded before the conditional behavior. 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 zero-annotation, no-output-schema, single-parameter tool this is only partially complete: the agent knows what it checks and that it may restart, but not the health criteria, the return shape, or the consequences of restarting. Adequate but with clear 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% and the single parameter is already documented as 'Restart session if unhealthy (default: true)'. The description restates this with slight added nuance ('if it hangs'), so it does little 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 and resource: verify the Vivado process is responsive, which is clearly a health-check operation. It does not differentiate itself from overlapping siblings such as session_status or get_host_status, so an agent must guess which check to use.

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 'if it hangs' implies the scenario for calling it, but there is no explicit when-to-use, when-not, or named alternative among session_status, get_host_status, or restart_simulation. Usage must be inferred from the surrounding tool list.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses non-destructiveness ("without deleting"), but the biggest behavioral risk for a close operation — whether unsaved edits are discarded or prompted for — is unaddressed, as is the error behavior when nothing is open.

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

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

A single short sentence with the key qualifier front-loaded in parentheses. Nothing is padded and nothing needs trimming.

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

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

For a parameterless session-state mutation with no annotations and no output schema, the definition covers the basics but omits the two things an agent most needs: the fate of unsaved changes and the outcome when no design is open.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the target design is implicit session state rather than an argument.

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

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

States a specific verb and resource ("Close the currently open block design") and adds a clarifying parenthetical that rules out deletion. An agent can distinguish it from create_block_design and save_bd_design, though it never names those siblings explicitly.

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

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

"The currently open block design" implies a precondition (a BD must be open) but gives no explicit when-to-use guidance, no statement about what to do if no design is open, and no routing to alternatives such as save_bd_design beforehand.

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

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

With no annotations, the description carries the full behavioral burden for a teardown/mutation operation. It does not say whether this disconnects from the hw_server, invalidates device handles or sessions, fails if nothing is open, or is safe to call repeatedly.

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

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

A single short sentence with no filler or redundancy. It is appropriately sized, though the brevity contributes to the missing behavioral and usage detail rather than reflecting deliberate compression.

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 annotations, no output schema, and no parameters means the description is the only source of behavioral information, and it provides none about side effects, failure modes, or post-conditions. For a teardown tool in a session-managed workflow this leaves meaningful 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already conveys. Baseline for a 0-parameter tool applies.

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

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

The description names a specific verb and resource ('Close' + 'Hardware Manager'), which reads clearly as the inverse of the sibling open_hw_manager. It does not explicitly reference that sibling, so the pairing must be inferred from the tool list rather than the text.

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 call this, what state must exist first (e.g. an open Hardware Manager session, an active hw_server connection), or what happens to dependent operations like program_device. The agent must guess at prerequisites and ordering.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing. It does not say whether unsaved changes are discarded, whether the call prompts or fails when no project is open, or whether the action is reversible.

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

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

One short sentence, front-loaded with the action and scope, with no filler. Nothing is wasted, though the same brevity is also the source of the coverage gaps.

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

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

For a zero-parameter lifecycle tool with no output schema, the description is minimally viable: the agent knows what it does. However, it omits outcome information that matters in a stateful IDE session, notably what happens to unsaved work and what state the session is left in.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the implicit 'currently open' target correctly conveys that the caller supplies no identifier.

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

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

States a specific verb and resource ('Close ... project') and clarifies scope with 'currently open', which explains why no parameter is needed. It does not explicitly contrast itself with siblings like close_bd_design or close_hw_manager, so the 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?

No when-to-use guidance, no prerequisites, and no exclusions. The description never says when closing is appropriate versus leaving the project open, nor what to do instead if the wrong project is loaded.

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

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

With no annotations, the description carries the full burden of behavioral disclosure and does not meet it. 'Close' implies a state-changing operation, but it never says whether waveform/signal data is lost, whether unsaved results are discarded, whether an error is raised if no simulation is open, or whether the enclosing session/project stays intact. Only the bare mutation is named.

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

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

One short, front-loaded sentence with zero filler. Nothing is repeated and the resource being acted on is stated immediately.

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

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

The tool is structurally simple (no params, no output schema, no annotations), so a short description is defensible. However, even for a no-arg lifecycle tool the agent needs to know what 'close' does to simulation state and whether it is safely re-callable, and the description leaves both open.

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 (empty properties, no required fields), so there is nothing for the description to disambiguate. Baseline of 4 applies for a no-argument tool.

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

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

States a specific verb ('close') and a specific resource ('the current simulation'), so the agent can tell it apart from launch_simulation, run_simulation and restart_simulation. It stops short of explicitly contrasting with the closest sibling, restart_simulation, which would have earned 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 word 'current' implicitly signals the precondition that an active simulation must exist, which is a usable usage cue. But there is no explicit when-to-use guidance, no statement of what to do instead if you want to keep the session alive (restart_simulation), and no 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?

With no annotations, the description carries the full burden: it discloses that this is a mutation of an existing cell and reveals the underlying set_property -dict mechanism, which is genuinely useful. It does not say whether an open block design/session is required, whether unknown CONFIG.* keys error out or are silently ignored, or whether the change is reversible — significant omissions for a mutating tool with zero annotation coverage.

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 packed sentences with the purpose front-loaded and the usage condition following immediately; nothing is filler. The PS7 example earns its space by showing the config dict shape, though it slightly muddies routing by invoking a scenario that has its own sibling 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 2-parameter mutation tool with a nested object parameter, no annotations, no output schema and only 50% schema coverage, the description covers purpose, timing and value format but leaves prerequisites (open design? active session?) and failure semantics unexplained. Adequate to start a call, not complete enough to call confidently.

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 only 50% (cell_name has no description), but the description compensates: it clarifies that config is a dict of CONFIG.* properties and gives a concrete key/value example showing the expected string format. cell_name is implicitly defined by 'on an existing block-design cell', though its naming/format convention is never spelled out.

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 ('Set CONFIG.* properties on an existing block-design cell') and even names the underlying Tcl command (set_property -dict), so the operation is unambiguous. It never names a sibling to differentiate from, however, and its PS7 example overlaps with the dedicated apply_ps7_preset tool without acknowledging 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?

Gives clear context: 'Use for settings that must be applied after creation or in a separate step', which tells an agent when this is the right entry point versus passing properties at creation time. It stops short of exclusions or alternatives — notably it does not mention apply_ps7_preset, which is the sibling an agent would most plausibly confuse with this one.

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

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

No annotations are present, so the description carries the full behavioral burden, and it discloses almost nothing: not whether changes persist to the project file, whether synth_ip/regeneration is required afterward, whether the project must be open, or how invalid CONFIG keys are handled. Only the mutation mechanism (set_property -dict) is revealed, which is minimal for a write operation with zero annotation coverage.

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

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

A single tight sentence with zero filler, front-loading the action and target. It is efficiently sized, though the terseness leaves gaps that are penalized under other dimensions rather than here.

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 mutation tool with no annotations, no output schema, a nested-object parameter, and an undocumented required string, one sentence is insufficient. An agent cannot tell what module_name means, what happens on success or failure, or what follow-up steps the configuration change requires.

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 only 50%: the config object has a description with an example, but module_name is bare. The description explains the CONFIG.* key/value shape for config but adds nothing about module_name — critically, it never clarifies whether that is an IP instance name, a VLNV, or a module type.

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 ("Set CONFIG.* properties on an existing IP") plus the underlying mechanism (set_property -dict), which is more than a restatement of the name. It does not name or contrast with any sibling such as create_ip or configure_bd_cell, so an agent must infer the boundary itself.

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

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

The phrase "on an existing IP" implies a precondition (the IP must already exist, i.e. create_ip first), but there is no explicit when/when-not guidance and no alternatives named. The agent must infer whether to use this versus create_ip, upgrade_ip, or configure_bd_cell.

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

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

No annotations are provided, so the description carries the full burden. It says nothing about whether this modifies the design in memory, whether it errors on already-connected pins, whether save_bd_design is required afterward, or what the call returns.

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

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

A single front-loaded sentence with zero filler. It is efficient, though so terse that it borders on under-specification for a mutation 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?

With two params, no annotations, and no output schema, the description should at least cover prerequisites (open BD) and mutation side effects. It covers neither, leaving the agent to guess how this fits into the save_bd_design/validate_block_design workflow.

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 schema already supplies concrete path examples for both intf_from and intf_to. The description adds only the notion that arguments are pins, not nets — 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 (Connect) with a specific resource class (AXI/interface pins) and scope (current block design), which implicitly separates it from connect_bd_net and auto_connect_axi. It never names those siblings, so a newcomer must infer the distinction from wording alone.

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

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

No explicit when-to-use or when-not-to-use guidance. It does not tell the agent how this differs from connect_bd_net (scalar nets) or auto_connect_axi (bulk AXI wiring), nor does it state prerequisites such as an open block design.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It says what the tool connects but does not disclose mutation side effects, required design state, error behavior, or return values.

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

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

The description is a single, front-loaded sentence with no redundant or filler content. It is appropriately sized for the tool's apparent simplicity.

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

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

For a two-parameter tool with fully described schema fields, the description is sufficient to identify the operation. However, with no annotations and no output schema, it omits design-state prerequisites and failure behavior that would help an agent invoke it reliably.

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 schema already documents both parameters with examples. The description only restates that two pins/ports are connected and adds no further parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: connect two scalar pins/ports in the current block design. It implicitly distinguishes itself from interface-net tools by specifying 'scalar pins/ports,' though it does not explicitly name the sibling connect_bd_intf_net.

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 no explicit when-to-use guidance, prerequisites, or alternatives. An agent can infer that it is for scalar pin/port connections, but it is not told when to choose this over connect_bd_intf_net or auto_connect_axi.

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

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

No annotations are provided, so the description carries the full behavioral burden. It reveals the default URL, but it does not state whether connection is persistent, idempotent, authenticated, what happens if a server is already connected, or what the call returns.

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 definition is two short sentences with the core operation front-loaded. The default URL context is compact and does not distract from the main action.

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

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

For a connection tool with no annotations and no output schema, the description omits important lifecycle context: whether a handle is returned, how this relates to open_hw_manager, whether repeated calls are safe, and what errors may occur. It is too thin for an agent to invoke with full confidence.

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

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

Schema coverage is 100%, and the single optional url parameter is already documented in the schema. The description reinforces the default localhost:3121 value and adds minor Vivado context, but no additional syntax or format guidance beyond the schema.

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

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

The description states a clear verb and resource: connecting to a hw_server, also aliased as cs_server. It is not tautological, but it does not distinguish this operation from nearby siblings such as open_hw_manager or session-related tools.

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

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

The description gives the default URL but does not explain when to use this tool versus open_hw_manager, start_session, or other connection/session tools. There are no preconditions, exclusions, or workflow 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?

With no annotations, the description carries the full burden. It usefully discloses the XDC/board-constraint naming requirement and that supplying vlnv silently switches to an interface-port creation path. It omits error behavior (name collisions, invalid VLNV), whether a block design must be open, and whether the port is externalized to the wrapper.

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, front-loaded with the core action, then the mode branching, then the constraint caveat. Minimal waste; no filler or restatement of the 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 7-parameter mutation tool with no annotations and no output schema, the description covers the two creation modes and the naming constraint but leaves out prerequisites, side effects (wrapper externalization), and failure modes. Adequate but with clear 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 baseline is 3. The description adds a little framing by grouping from/to as the vector form and vlnv as the interface form, but it does not resolve the schema's confusing from/to (MSB/LSB) labeling, which is exactly where extra description value would help.

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 top-level port on the current block design') and describes two distinct modes: scalar/vector via from/to, and interface ports when vlnv is given. It distinguishes the two behaviors but does not differentiate from siblings like connect_bd_net or get_ports.

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

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

Usage is implied by the phrase 'on the current block design' and the vlnv branching, but there is no explicit when-to-use or when-not-to-use guidance, no mention of prerequisites (an open block design), and no naming of alternatives such as add_ip_to_bd or connect_bd_net.

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

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

No annotations exist, so the description carries the full burden. It does disclose two real behavioral traits: the design becomes the current one (a state mutation beyond mere creation) and board_part has an external dependency on BSP installation. It omits failure behavior on name collisions, prerequisite project state, and what is returned.

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, zero waste, and the primary action plus its 'make current' side effect are front-loaded ahead of the optional-parameter caveat.

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

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

For a 2-parameter creation tool with no output schema and no annotations, the description covers purpose, the main state side effect, and the one non-obvious dependency. Missing only the project-must-be-open prerequisite and duplicate-name behavior, which are minor for 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 coverage is 100%, so the baseline is 3; the description earns above that by adding meaning the schema does not have — that board_part is applied to the project beforehand and requires the BSP to be installed in Vivado. The 'made current' note also clarifies the effect of the required name parameter.

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?

Uses a specific verb+resource ('Create a new block design') and adds two concrete outcomes: the design becomes current and board_part may be set on the project. It is clearly distinguished in kind from siblings like save_bd_design, close_bd_design and validate_block_design, though it does not name an alternative 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 BSP-installed precondition for board_part is a useful usage hint, and 'make it current' implies this is a starting step in the BD flow. However, it never states that a project must already be open, nor does it say what to do if a design of that name already exists — 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?

No annotations are provided, so the description carries the full burden, and it does disclose the key side effect: a .xci file is written into the project's IP sources fileset, and the downstream workflow is named. It does not cover error behavior if the IP already exists, or what is returned, which keeps 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?

Three short sentences, each earning its place: creation, artifact produced, and the follow-up workflow. The core action is front-loaded with no filler.

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

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

With no output schema or annotations, the description supplies the artifact produced and the sequencing an agent needs to call it correctly. Minor gaps remain around return values and failure modes for pre-existing IP instance names, but nothing critical for 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% and every parameter (vendor, ip_name, library, version, module_name) has a description with defaults and examples, so the description needn't restate them. It adds no extra parameter semantics 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?

Specific verb+resource ('Create an IP from the Xilinx IP catalog') with a concrete artifact outcome ('Generates a .xci file in the project's IP sources fileset'). It clearly positions itself relative to related tools (configure_ip, generate_ip_target, synth_ip) so an agent can distinguish this creation step from the configuration and generation steps.

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 states the follow-up sequence ('Use configure_ip + generate_ip_target afterwards, then run synth_ip if you want out-of-context synthesis'), giving both the required next steps and a conditional branch. This is direct routing guidance rather than implied usage.

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

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

With no annotations, the description carries the full burden; it does disclose that a real project directory is written to disk and that the flow is project-mode (not in-memory). It omits important behavior: whether an active Vivado session (start_session) is required first, and what happens when a project of that name already exists (the force=true default in the schema implies overwrite, but the description never says so).

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 followed by workflow order; nothing superfluous. Minor redundancy in repeating the default part number already declared in the schema.

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 and no annotations, so the description should cover more: the return value (created project path/handle), the session prerequisite, and overwrite semantics are all absent. For a 5-parameter mutating tool it is adequate but leaves real 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% and every parameter is documented in-schema, including the <directory>/<name> path composition and defaults. The description's only added parameter content is restating the default part, 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 new Vivado project") plus the disk/project-mode scope, which distinguishes it from open_project, create_block_design, and the rp_* project variants. The default part is named concretely.

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

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

Gives an explicit follow-on workflow ("Call add_sources / add_constraints next, then run_synthesis"), which tells the agent where this sits in the sequence. It stops short of exclusions — nothing says when to prefer rp_create_custom_project or create_block_design instead.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses fail-fast semantics and a structured return payload, but says nothing about duration (this is a multi-minute FPGA build), whether it overwrites or requires an empty directory, whether it needs a running Vivado session, or whether partial artifacts are left behind on failure. That is a large gap for a mutating, long-running tool.

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

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

Two sentences, front-loaded with 'One-shot composite' followed by the stage order, then fail-fast behavior. There is essentially no waste; the only cost is that the arrow chain is dense and could have carried parameter meaning.

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

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

With no annotations and no output schema, the definition needs to explain both the environment prerequisites and the 11 parameters, and it explains neither. The pipeline sequence and failure behavior are genuinely helpful, but an agent still cannot safely call this without guessing at directory, timeout, and xdc_variant semantics.

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

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

Schema description coverage is only 9 percent across 11 parameters (only board has a default note in the schema), so the description needed to compensate and does not. It never mentions name, directory, top_module, verilog_files, xdc_variant, jobs, timeouts, synth_flags, or extra_xdc_files, leaving required and optional parameters equally opaque.

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 spells out a concrete pipeline (create project -> add HDL sources -> apply XDC -> synth -> impl -> write_bitstream -> .bit.bin), which makes the composite nature unmistakable and implicitly distinguishes it from the single-stage siblings like create_project, run_synthesis, and generate_bitstream. It never names those siblings as alternatives, keeping it just 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?

'One-shot composite' implies this replaces chaining the individual stage tools, and 'stops on the first failing stage' hints at a fail-fast use case. However, there is no explicit statement of when to prefer this over the granular tools, and no mention of prerequisites such as an open session or a valid board target.

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

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

With no annotations, the description discloses the transport (SSH/SCP), the two loader mechanisms and their OS support matrix, and that no Vivado session is required. It does not state that loading overwrites the currently running FPGA configuration or what happens on failure, which matters for a mutating remote operation.

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 core action, then mechanism, then the prerequisite clarification. Every sentence carries information; nothing is restated from the schema.

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 remote-deployment tool with no output schema and no annotations, the description covers transport, loader choice, OS versions and toolchain prerequisites. Missing are failure behavior and the fact that the existing FPGA image is replaced, which would complete the picture.

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

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

Schema description coverage is 100%, so the schema already documents host, port, user, password, method, keep_remote and remote_path defaults. The description only adds the method/OS compatibility nuance, which the enum description already largely covers. Baseline 3 applies.

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

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

States a specific verb+resource+transport: copy a .bit.bin to a Red Pitaya over SSH/SCP and load it into the FPGA. This clearly separates it from generate_cfgmem (which produces the artifact) and program_device (Vivado hardware manager path).

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?

Implicitly routes from generate_cfgmem ('the local .bit.bin produced by generate_cfgmem') and clarifies it needs no Vivado session, which distinguishes it from program_device. It does not explicitly say when NOT to use it, e.g. when a JTAG/Vivado hardware path is preferred.

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

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

With no annotations, the description carries the full burden and does well: it discloses that it generates a wrapper, adds it to sources_1 by default, sets it as top, and updates compile order. It omits overwrite behavior, required project state, and error handling.

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

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

Purpose and default behavior are front-loaded in the first sentence, and the second sentence efficiently documents the exact Tcl sequence being performed. There is no wasted 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?

The description is strong on side effects but lacks prerequisites such as needing an open project and an existing block design. With no output schema, it also does not say what the tool returns.

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 bd_name and set_top are already documented. The description adds only the default value of set_top, which is also present in the schema, 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 and resource: generate the HDL wrapper for a block design, with the default side effects clearly identified. An agent can distinguish this from sibling block-design creation or validation tools.

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

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

The description implies it is used after a block design exists, and describes the default behavior, but it does not explicitly state prerequisites, when not to use it, or which sibling tools should precede it.

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

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

With no annotations, the description carries the load and does reasonably well: it discloses that the call blocks on wait_on_run, that it returns ground-truth run status and the .bit artifact path, and the 3600s default timeout signals a long-running operation. It omits prerequisites (an open project with a completed implementation) and whether an existing bitstream is overwritten.

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

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

One dense sentence with the key artifact and outcome front-loaded; nothing is padded. The embedded Tcl is arguably slightly technical but contributes concrete meaning about what actually runs.

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 tool with no output schema, it covers the essentials: the operation performed, blocking behavior, and the returned values. Missing only workflow preconditions and output location, which an agent would need to call this confidently in sequence.

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 single optional `timeout` parameter is already fully documented with its default. The description adds nothing about timeout semantics (e.g., behavior on expiry), 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 artifact ('Generate bitstream') and backs it with the exact underlying operation (`launch_runs impl_1 -to_step write_bitstream` -> wait_on_run), plus what it yields (.bit path, run status). It is distinguishable from siblings like run_implementation or run_synthesis, though it never names them explicitly.

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

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

The Tcl equivalent implies this is the step after implementation, but there is no explicit statement of when to call it versus run_implementation, program_device, or generate_cfgmem. Usage must be inferred from the workflow name rather than read.

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

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

No annotations are provided, so the description must carry the behavioral burden. It usefully discloses the output format and target loader path, but says nothing about whether the output file is overwritten, whether it must be transferred to the device, or what happens if the .bit is missing or invalid.

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

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

Two compact sentences, front-loaded with the transformation and followed by the sequencing hint. Nothing is redundant or 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 simple two-parameter format converter with a fully documented schema and no output schema, the description covers what the tool does, why (.bit.bin for /dev/xdevcfg), and when to run it. Only failure/overwrite behavior and downstream handling of the produced file are 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%, with both bit_file and output fully described in the schema including the default '<bit_file>.bin', so the schema does the heavy lifting. The description adds no further parameter detail, 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 concrete verb and format conversion ('Convert a .bit into a raw binary image (.bit.bin)') plus the target loader '/dev/xdevcfg' and platform 'Red Pitaya'. It is clearly distinct from the sibling generate_bitstream, which produces the input rather than the converted image.

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

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

'Use after generate_bitstream' gives an explicit sequencing prerequisite, which is the main usage decision for this tool. It does not name when-not-to-use conditions or alternatives, but no sibling offers comparable conversion, so the gap is minor.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the key trait that output is written to a file and that a report_id is returned, but says nothing about whether output_file is overwritten, how long full reports take, or whether the generated file persists across sessions.

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

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

Three short sentences, each earning its place: purpose, triggering condition, and return value. The critical 'use when' clause is front-loaded right after the purpose statement.

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

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

No output schema exists, and the description correctly fills that gap by naming the return value (report_id) and the tool that consumes it (read_report_section). Combined with the schema's enum and options, 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 coverage is 67%, so the schema already documents output_file and options at a basic level. The description adds no parameter-level meaning at all—it doesn't explain the nine report_type values or what report-specific options are valid for which type—so it neither compensates for the gap nor subtracts from it.

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

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

States a specific verb and resource ('Generate a full Vivado report to a file') and contrasts it with the inline-report path used by siblings such as get_timing_summary or report_power. It falls short of 5 because it never names those sibling tools explicitly, leaving the discrimination implicit.

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 triggering condition ('when inline reports get truncated or you need the complete output') and names the follow-up tool read_report_section for consuming the result. No explicit when-not guidance or prerequisites (permissions, runtime cost) are provided.

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

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

With no annotations, the description carries the full burden but reveals little: it does not say this writes output products to disk, whether existing products are overwritten, whether an open project/open IP is required, or how long it takes. Only the default target behavior is disclosed.

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

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

One sentence, front-loaded and free of filler, but its brevity is closer to under-specification than efficiency. Nothing is wasted, yet more needed to be said.

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 mutation-style tool with no annotations and no output schema, the description leaves out prerequisites, the meaning of the required module_name, and any post-call expectations. It is not sufficient for an agent to call this confidently without guessing.

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

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

Schema coverage is 50%: targets has a schema default note that the description merely echoes, while the required module_name parameter is undocumented in both schema and description. The agent is never told whether module_name is a module identifier, IP VLNV, or project IP name.

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 ("Generate IP output products") and clarifies the default target scope. However, it does not differentiate from sibling tools like synth_ip, create_ip, or configure_ip, which an agent must distinguish when choosing among IP-related operations.

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

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

No guidance on when to use this versus synth_ip or upgrade_ip, and no prerequisites stated (e.g., that the IP must already be created/configured and a project open). The only implied usage is the default target list.

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

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

No annotations are provided, so the description carries the full burden. 'No Vivado session required' is a genuinely useful behavioral disclosure (no start_session prerequisite) and 'Get' implies read-only, but it says nothing about failure modes for unknown board identifiers or whether values are static vs. environment-derived.

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

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

Two short sentences with zero filler; the content enumeration is front-loaded and the session-free constraint and downstream usage follow immediately. 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?

With one parameter, no output schema, and no annotations, the description compensates well by listing the return payload fields and noting no session is needed. A minor gap remains: it doesn't point to list_boards as the source of valid board identifiers or address error 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?

Schema description coverage is 100% and the single `board` parameter is already documented with an example in the schema. The description adds no additional semantics about identifier format, accepted values, or where valid ids come from, 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+resource ('Get bundled metadata for a board') and enumerates the returned fields (part, LED pinout, absolute XDC paths, default synth flags), which clearly distinguishes it from list_boards. It never names a sibling explicitly, so it lands just 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?

'Use the returned absolute_path values with add_constraints' gives an explicit downstream workflow and names the consuming sibling. It doesn't say when to call this versus list_boards first, or what happens with an invalid board id, so exclusions are absent.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: "Search" implies a read but does not state read-only semantics, what scope is searched (current design? hierarchy depth?), whether results are capped, or what a match looks like. Only the schema's default limit hints at result size.

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

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

A single front-loaded sentence with zero padding — the verb and the discriminator (pattern) come first. It is efficient, though so terse that the brevity shades into under-specification rather than crispness.

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 tool with no annotations and no output schema, the description says nothing about the return shape, whether the search is hierarchical, or which design/session the search applies to. An agent could invoke it correctly but cannot predict whether it will see flat top-level cells or a full hierarchy.

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

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

Schema description coverage is 100%, with both properties documented (limit: max results, default 100; pattern: wildcard, default '*'), so the schema already does the parameter work. The description adds only the redundant word "pattern" and nothing about wildcard syntax or limit interaction, which is the expected baseline 3.

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

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

The description gives a specific verb ("Search") and resource ("cells/instances") with the key qualifier "by pattern", so the agent knows this is a pattern-based lookup rather than an enumeration. It does not, however, distinguish this from nearby siblings such as list_bd_cells, get_ports, or get_nets, and "instances" is ambiguous between netlist cells and block-design cells.

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

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

There is no statement of when to use this tool versus list_bd_cells, get_design_hierarchy, get_ports, or get_nets, and no prerequisites or exclusions. The only usage signal is the word "pattern", which the agent must infer means glob-style filtering against a netlist.

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

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

No annotations exist, so the description carries the full disclosure burden. It never states that this is a non-mutating query, what permissions or session state it requires, or what the response contains (clock names, periods, waveforms, uncertainty, generated clocks) — only the vague phrase "information and constraints."

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

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

A single, front-loaded sentence with no filler. The parenthetical command mapping is useful; the only minor waste is that "information and constraints" is vague rather than specific.

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 no annotations, the description is the only source of truth about results, yet it does not enumerate what clock data is returned. For a read-only zero-param getter this is minimally adequate but leaves the agent guessing at the 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 for the description to disambiguate; baseline 4 applies. The description cannot and need not add parameter detail.

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 ("Get clock information and constraints") and maps itself to the underlying Vivado command via the parenthetical. It is clear what the tool retrieves, but it does nothing to separate itself from closely related siblings such as get_timing_summary, get_timing_paths, or report_clock_interaction.

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 indication of when to call this versus the timing-report siblings, and no prerequisites or exclusions are given. An agent must guess whether clocks come from this tool or from get_timing_summary.

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

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

No annotations are provided, so the description carries the full disclosure burden; 'Get' weakly implies read-only, but nothing states scope (current project? elaborated vs synthesized netlist), the default depth behavior, or whether the result is truncated. For a read tool with zero annotation coverage and no output schema, this is a notable gap.

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

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

A single front-loaded sentence with no waste and the core resource stated immediately. It errs toward terseness rather than padding, but every word carries weight.

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

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

With no output schema and no annotations, the description should convey the return shape (nested tree vs flat list, naming of instances) and preconditions, neither of which appear. An agent knows what to ask for but not what it will get back or when it is valid to call.

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

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

Schema description coverage is 100%, so both parameters are already documented including the default depth and pattern syntax examples. The description's 'optionally filtered' adds only a mild framing hint and no syntax or default information 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 ('Get') and resource ('design hierarchy') and clarifies the payload as 'modules and instances', which distinguishes it from most siblings. It does not explicitly differentiate from related read tools like get_cells or get_scopes, which overlap conceptually with hierarchy traversal.

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?

'optionally filtered' is the only hint about when to supply a filter; there is no statement of when to use this versus get_cells/get_scopes or what state (open project, elaborated design) is required. The agent must infer usage from the name alone.

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

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

With no annotations, the description carries the behavioral burden alone. It implies a read-only status check and names the fields returned, but says nothing about permissions, cost, or whether the call affects session state.

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

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

Two short sentences with no wasted words. The return contents come first and the motivating use case second, which is well front-loaded.

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

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

For a simple zero-parameter read tool with no output schema, the description covers both what comes back and why to call it. Only minor behavioral details, such as latency or freshness, are absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and baseline 4 applies. No parameter details are needed or missing.

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

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

The description states a specific verb and resource ('Get host hostname, free memory, and session state') and enumerates the returned fields, so the agent knows exactly what it retrieves. It does not explicitly distinguish itself from nearby siblings like session_status or check_session_health, which is the only gap.

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-to-use: check RAM before launching synthesis/implementation. That is actionable context an agent can act on, but no exclusions or named alternative tools are offered for overlapping session-inspection needs.

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

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

No annotations are provided, so the description carries the burden. The verb 'Get' plus a severity filter reasonably conveys a read-only, non-destructive lookup, but it discloses nothing about buffer semantics, result limits, ordering, or whether messages accumulate across sessions — meaningful gaps for an unannotated tool.

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

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

One front-loaded sentence with no filler; the filter dimension and its allowed values are given immediately. Nothing here needs trimming.

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 read tool this is close to sufficient, but with no output schema the description could note what a returned message contains or whether results are capped/ordered. As written an agent can call it, but cannot predict the response shape.

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

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

Schema coverage is 100% and the single optional parameter is fully documented in the schema itself, including the 'all' default. The description restates the enum values without adding format, case-sensitivity, or fallback behavior, 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+resource ('Get Vivado messages') plus a filtering dimension, so an agent knows exactly what it retrieves. It does not distinguish itself from the closely-named sibling get_simulation_messages (or from get_synthesis_errors_parsed), leaving ambiguity about which message source to pick.

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 parenthetical enumerates the severity values, which implies when to filter by each, but there is no explicit guidance on when to use this tool vs. get_simulation_messages or get_synthesis_errors_parsed. Usage is inferable from the name 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?

With no annotations, the description carries the full burden and discloses almost nothing: it doesn't confirm the operation is read-only, doesn't state that an open project/design is required, and doesn't indicate what is returned or how 'limit' truncates 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?

One short sentence with the resource and default front-loaded and no filler. It is efficient, though the brevity borders on under-specification.

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

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

For a simple two-optional-parameter read tool with a fully documented schema and no output schema, the definition is minimally adequate. It still leaves an agent guessing about required session state and the shape of returned net records.

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 'limit' and 'pattern' are already documented with their defaults. The description merely restates the pattern default rather than adding syntax or matching semantics (e.g., whether the pattern matches hierarchical names).

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

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

Specific verb+resource: 'Search for nets' with a default wildcard pattern, which an agent can map to the Vivado get_nets concept. It does not, however, distinguish itself from near-siblings like get_ports, get_cells, or list_bd_cells.

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 guidance, no prerequisites, and never names an alternative such as get_ports or get_cells. The only usage signal is the implicit wildcard default, which the schema already states.

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

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

No annotations are provided, so the description must carry the behavioral burden. 'Get' implies a read-only query and 'top-level' scopes the result, but it does not disclose prerequisites, return format, or whether it requires an active design session.

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

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

A single front-loaded sentence with no wasted words. It is appropriately sized for a simple zero-parameter getter.

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

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

The description is minimally adequate for a low-complexity query with no output schema. However, it omits prerequisite context such as needing an open design, which an agent may need before invoking it.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter detail because none is needed.

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

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

States a specific verb and resource: 'Get top-level I/O ports of the design.' An agent can tell it retrieves ports, but the description does not distinguish it from related query tools like get_nets, get_cells, or get_design_hierarchy.

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 guidance on when to use this tool versus alternatives such as get_design_hierarchy or get_nets. It also does not state prerequisites like needing an open design or project.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the payload (name, part, target language, directory), which is meaningful behavioral context for a zero-param read, and 'Get' clearly implies read-only. However, it says nothing about failure modes when no project is open, or the shape of the returned value beyond a field list.

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

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

One sentence, front-loaded with the verb and immediately listing the returned fields. No filler, no repetition of the tool name as a standalone statement.

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 no annotations, the description is the only place return values can be described, and it does list the four fields returned. It falls short of fully covering edge cases (no project open, projects with missing target language) but is adequate for a simple zero-param getter.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The description correctly signals a no-argument call that reads state implicitly from the current session.

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

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

The description gives a specific verb (Get) and a specific resource (the open project), and enumerates the fields returned (name, part, target language, directory). It does not differentiate itself from neighboring read-only tools like session_status, get_host_status, or list_boards, but the purpose itself is unambiguous.

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

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

Usage is only implied: the phrase 'of the open project' signals the prerequisite that a project must already be open, which is the key precondition. There is no explicit statement of when to use this instead of siblings such as open_project or session_status, and no note on error behavior if no project is open.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It implies a read operation through 'List', but does not explain whether traversal is recursive, how deep it goes, what the default root behavior is, or what the result looks like. For a hierarchy-listing tool with zero annotation coverage, this is a significant gap.

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

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

The description is a single front-loaded sentence with no wasted words. It is efficient, though its brevity contributes to the vagueness noted in other dimensions.

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 annotations and no output schema, the description needs to explain return shape and traversal behavior. It does not clarify whether child scopes are returned as a flat list or tree, how deep the hierarchy goes, or how this relates to the simulation session lifecycle implied by other sibling tools.

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

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

Schema coverage is 100%, so the parent parameter is already documented in the schema, including its default of '/'. The description adds no additional meaning about how parent selects the hierarchy root or whether results are relative to it, leaving the schema to do all the work.

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

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

The description states a specific verb and resource: 'List child scopes (hierarchy) in the simulation.' However, 'scopes' is vague, and the tool is not distinguished from nearby siblings like get_design_hierarchy or get_simulation_objects. An agent can infer the general purpose but not precisely how this differs from those alternatives.

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

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

There is no indication of when to use this tool versus alternatives such as get_design_hierarchy or get_simulation_objects. No exclusions, prerequisites, or context for choosing this tool are provided.

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

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

No annotations are provided, so the description carries the full burden, yet it discloses nothing beyond the obvious read semantics. It omits that a launched/running simulation is required, how unknown or unset signals are reported, and how the radix affects the returned representation.

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

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

One sentence with zero waste, front-loaded with the verb and resource. It is terse to the point of under-specification rather than bloated, so it scores well on economy only.

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 only two parameters and full schema coverage the definition is workable, but there is no output schema and no statement of what the return value looks like or its dependence on radix. A running-simulation precondition would also be needed for an agent to call this reliably.

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 'signal' (hierarchical path) and 'radix' (enum with default hex) are already documented. The description adds no syntax or format 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?

States a specific verb and resource ('Get current value of a signal') scoped to simulation, which is clear. It does not distinguish itself from the sibling 'get_signal_values' (plural), leaving the agent to guess which retrieval tool to pick.

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

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

No guidance on when to use this single-signal getter versus get_signal_values, and no stated prerequisite such as an active simulation session. The agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the full burden. The 'max 50' limit is a useful behavioral detail, but it is ambiguous (truncation vs. error?) and the description never states the prerequisite of an active simulation or what the returned values look like, since there is no output schema either.

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

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

A single front-loaded sentence with the resource, matching mechanism, and limit in the right order. Nothing is padded, though the extreme brevity leaves gaps that additional clauses would have closed.

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 tool with no annotations, no output schema, and half its parameters undocumented, the description should explain prerequisites (live simulation session), truncation behavior at 50, and the role of radix. None of these are covered.

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

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

Schema coverage is only 50%: pattern is documented with an example, but radix has no description at all. The description never mentions the radix parameter or how it affects returned values, so it fails to compensate for the documented gap.

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 ('Get values of multiple signals') plus the matching mechanism ('wildcard pattern'), which implicitly separates it from the singular sibling get_signal_value. It never names that sibling, so the distinction relies on the reader noticing 'multiple' vs. singular.

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 'max 50' cap hints that this is a bulk read and suggests the single-signal sibling for narrower use, but usage is only implied. There is no explicit when-to-use, no statement that it requires an open/active simulation session, and no exclusion 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?

No annotations are provided, so the description carries the full burden and it discloses very little. It does not say what happens when severity is omitted, whether the result is truncated or paginated, whether it reads from a live or closed simulation session, or how messages are ordered.

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

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

One front-loaded sentence with zero padding, and the key noun phrase comes before the qualifier. It is efficient, though its brevity is part of why behavioral detail is missing.

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-optional-parameter read tool with no output schema this is close to adequate, but the agent still cannot tell the default severity behavior, the message volume/shape, or how it differs from get_messages. Those gaps matter more here because there are no annotations to fall back 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?

The single optional parameter has an enum covering all/error/warning/info, so the value space is self-documenting in the schema, but schema description coverage is 0%. The description adds only that the value acts as a severity filter; it never states the default when the parameter is absent.

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 ('Get') and resource ('simulation log messages') plus the scoping dimension ('filtered by severity'), so the operation is unambiguous. It does not distinguish itself from the sibling get_messages, which likely returns non-simulation messages, leaving the agent to 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 statement of when to use this versus the closely named sibling get_messages, nor any prerequisite (e.g., an open/launched simulation). The only usage signal is the implied 'filter by severity' from 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?

No annotations are provided, so the description carries the full disclosure burden, yet it only implies read-only via 'List'. It says nothing about permissions, whether results are paginated or capped, hierarchical vs flat listing, or what the default scope '/' means.

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

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

A single short sentence with no filler and the key noun up front. It is concise to the point of under-specification rather than verbose, so brevity is not the failing dimension.

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 tool with no annotations, no output schema, and partially undocumented parameters, the description should explain the scope-vs-filter relationship and the shape of results. None of that is present, leaving the agent to guess at call semantics.

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

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

Schema coverage is 50%: the filter parameter has a documented enum but no prose, and scope only has 'default: /'. The description's parenthetical ('signals/ports/internal') repeats the filter enum while being attached to 'scope', which risks misleading an agent into passing those values to scope.

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 verb and resource ('List simulation objects') and names the category values, but 'simulation objects' is left undefined and the parenthetical conflates the filter enum with scope. It does nothing to distinguish this from close siblings like get_scopes, get_ports, get_nets, or get_cells, which may return overlapping data.

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

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

There is no statement of when to use this versus get_scopes (to find valid scope paths) or get_ports/get_nets (to enumerate specific object kinds), even though those siblings clearly overlap. An agent has no basis in the description for choosing this tool over 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?

No annotations are provided, so the description carries the burden. 'Get' implies a read-only query and it discloses the return field (current_time), but it does not state that an active simulation session is required or what happens if none exists — the main behavioral risk for this tool.

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

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

A single short sentence with the resource front-loaded and no filler. Nothing could be removed without losing 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 trivial zero-arg getter this is close to sufficient, but with no annotations and no output schema, the description should at least say the call is only meaningful while a simulation session is active.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The parenthetical naming of the returned value adds a small amount of 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?

Names a specific verb+resource ('Get the current simulation time') and even identifies the returned field name (current_time). It is distinguishable from mutating siblings like step_simulation or restart_simulation, though it never explicitly contrasts itself with them.

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

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

Usage is only implied: an agent can infer this is a read used while a simulation is open, but there is no statement of when to call it versus siblings such as run_simulation or session_status, nor any precondition noted.

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

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

No annotations are supplied, so the description must carry the disclosure burden. It adds real context ('plus those of every failed run (e.g. out-of-context IP runs)') and implies a read-only error-digging operation, but never confirms it is side-effect free, how large the result can get (max_items default 50 is only in the schema), or what a 'structured error' record contains.

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

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

Two tight sentences, front-loaded with what is returned before the when-to-use instruction. Every clause carries information: default run, failed-run inclusion, and the triggering scenario.

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 characterize the return value; it does so at a high level ('structured errors and critical warnings', 'clean actionable list') though it never sketches the record shape. Covering both the default-run and failed-run-union behavior makes it complete 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 coverage is 100%, with both properties documented including their defaults, so the schema already does the work. The description reinforces the 'synth_1' default and explains that failed runs are implicitly included, but adds no syntax or meaning beyond what the schema states.

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: returns structured errors and critical warnings from a run's log, with a documented default (synth_1), and additionally aggregates errors from every failed run. This is meaningfully distinct from the generic sibling get_messages, though the description never names that sibling to sharpen 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?

Explicitly says 'Use after run_synthesis fails to get a clean actionable list,' which gives the trigger condition and the sibling it follows. It doesn't state when NOT to use it or name get_messages as the alternative for general log reading, so it stops short of full routing 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?

With no annotations, the description carries the full behavioral burden. It does disclose the default output shape (structured summary) and that higher detail levels add raw text, which is genuinely useful. It omits prerequisites (timing paths only exist after synthesis/implementation), the read-only nature is only implied by 'Get', and it doesn't warn that detail_level=full returns large raw text.

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 purpose front-loaded and the output-shape note immediately after. 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 an 8-parameter, zero-required tool with no annotations and no output schema, the description covers purpose and the detail_level axis but leaves the agent without prerequisites, expected return structure, or volume expectations. Adequate to invoke, not adequate to invoke confidently.

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 meaning the schema lacks: it explains what detail_level actually changes in the response ('the raw text too'), whereas the schema only enumerates the values. It still says nothing about clock/from_pin/to_pin/through filter interaction or num_paths/slack_threshold behavior 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 and resource (get failing/critical timing paths), which is concretely distinguishable from the sibling get_timing_summary in scope. However, it never names or contrasts with that sibling explicitly, so an agent must infer the boundary itself.

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

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

The second sentence gives useful guidance on the detail_level axis (default summary, escalate to standard|full for raw text), which is real usage direction. But there is no guidance on when to pick this over get_timing_summary, get_clocks, or report_qor_assessment, and no stated prerequisites such as requiring a synthesized/implemented design.

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

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

No annotations are provided, so the description carries the full burden. It discloses that results are parsed by default and points to an alternative for raw output, but does not state whether the tool is read-only, what permissions are required, or how errors/empty results are handled.

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

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

Two short sentences, zero waste, and the key behavioral default plus alternative are front-loaded. It is appropriately sized for a simple read/report 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 simple two-parameter read tool with a fully described schema, the description gives enough context to call it correctly and redirects to the raw-output alternative. It could say more about the returned timing metrics, but the acronyms and default behavior are sufficient for this complexity level.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description adds only that parsed metrics are returned by default, without explaining report_type choices or detail_level behavior 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 and resource (timing summary) and names the metrics it returns (WNS, TNS, WHS, THS). It also distinguishes itself from generate_full_report for raw output, though it does not clarify its relationship to get_timing_paths.

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 context: parsed metrics by default, and directs the agent to generate_full_report when raw output is needed. It does not explicitly exclude or compare against other timing-related siblings such as get_timing_paths.

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

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

No annotations exist, so the description carries the full burden, yet 'Parsed only by default' is unexplained — the agent cannot tell if this returns parsed numbers instead of a raw report, whether raw text is ever available, or whether results are cached/stale. It also omits the crucial precondition that utilization data only exists after synthesis or implementation.

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?

At two short fragments it is certainly compact and the metric list is front-loaded, but the second fragment is cryptic rather than economical. Brevity here comes at the cost of understanding, not from tight editing.

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?

A four-parameter reporting tool with no annotations and no output schema needs the description to explain return shape (percent vs. absolute counts), preconditions, and the detail_level behavior. None of that is present, so the definition is under-specified for the complexity of the 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 75% and three of four parameters carry their own descriptions, so the schema does the heavy lifting. The description adds nothing about any parameter, and notably leaves the undescribed 'detail_level' enum (summary/standard/full) entirely unexplained, which is the parameter most likely to change results.

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

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

The description names the resource explicitly ('Resource utilization') and enumerates the metrics (LUT/FF/BRAM/DSP/IO), which is enough to distinguish it from siblings like report_power or report_qor_assessment. It is a noun phrase rather than a verb+object, and the trailing 'Parsed only by default' muddies rather than clarifies what the tool actually returns.

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

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

There is no statement of when to call this versus alternatives such as report_qor_assessment, report_power, or get_design_hierarchy, and no prerequisites (e.g., design must be synthesized/implemented). 'Parsed only by default' hints at a mode distinction but never says what the other mode is or when to ask for it.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses that content is bundled/static rather than fetched live, that the return is markdown plus an upstream URL, and that the version parameter is merely cosmetic. The gap is undocumented behavior on an unknown topic (error vs. empty result).

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

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

Purpose and return shape are front-loaded in a single sentence, with the topic vocabulary following as a compact list. The topic enumeration is long but functional, effectively serving as an enum the schema lacks.

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

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

For a two-parameter read-only doc lookup with no output schema and no annotations, the description covers purpose, inputs (via the topic list), and output shape. Nothing essential to calling 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 coverage is 100%, so the baseline is 3, but the description earns more by actually supplying the enumerated topic vocabulary that the schema defers to ('see KNOWN_TOPICS in the tool description'). The version parameter's low stakes are also clarified.

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?

Uses a specific verb + resource ('Look up a topical Vivado documentation summary bundled with this server') and states exactly what comes back (markdown + upstream URL). It does not, however, distinguish itself from the sibling list_vivado_docs, which an agent would reasonably consider for the same intent.

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?

By enumerating the known topics it implicitly tells the agent when this tool applies, but there is no explicit 'use this when...' statement and no mention of how it differs from list_vivado_docs. It also doesn't say what the caller should do for a topic not in the list.

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

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

No annotations are provided, so the description carries the full behavioral burden and largely fails it. It does not say whether launching creates persistent state, what happens if a simulation is already open, whether it requires a prior synthesis/implementation run for post-synth/post-impl modes, or what it returns.

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

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

One short front-loaded sentence with no filler. Brevity is appropriate, though it is terseness rather than informative compression.

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

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

With zero annotations and no output schema, the description is the only place to explain state, prerequisites, and result, and it says none of that. For a stateful launch operation in a crowded simulation-tool family, this leaves real 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% and the single 'mode' parameter has an enum plus a documented default, so the schema does the work. The description's shorthand 'behavioral/post-synth/post-impl' is a coarser restatement of the five enum values and adds no meaning beyond them.

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

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

States a specific verb ('Launch') and resource ('xsim') plus the mode dimension, so the agent knows this starts a simulator. It does not differentiate from close-by siblings such as run_simulation, restart_simulation, or run_simulation, leaving the boundary between 'launch' and 'run' 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?

No when-to-use guidance, no prerequisites (elaborated design, synthesized netlist for post-synth modes), and no mention of alternatives like run_simulation or restart_simulation. The only usage hint is the implicit default mode carried by the schema.

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

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

With no annotations, the description carries the full behavioral burden and discloses almost nothing: not that it is a read-only operation, not that it requires an open block design, and not what happens if no BD is open. Only the optional filtering hint adds 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?

One front-loaded sentence with no filler. It is efficient, though arguably too terse given the missing prerequisite and return-info detail.

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

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

For a simple zero-required-parameter listing tool with no output schema, the core intent is conveyed. However, the missing prerequisite state (open block design) and absence of any note about what the listing contains leave real 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% and the single parameter is fully documented as a wildcard pattern defaulting to '*'. The description's '(optionally filtered)' merely restates 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 ('List') and resource ('cells in the current block design') with scope narrowed to the block design, which implicitly separates it from the sibling get_cells. It does not explicitly name that sibling or clarify the distinction beyond the 'bd' qualifier.

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

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

No indication of when to use this versus get_cells or other BD tools, and no stated prerequisite such as an open block design or project. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that no Vivado session is required and implies a read-only listing, but it does not describe return format, pagination, or any other operational 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 short sentences, front-loaded with the primary action and followed by the key operational constraint. There is no wasted 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 simple zero-parameter list tool, the description covers the core action and the no-session condition. But with no annotations and no output schema, it should say more about what 'bundled XDC + metadata' actually returns to be 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?

The tool has zero parameters, so the baseline is 4. The schema is empty and fully described by definition, and no additional parameter semantics are needed.

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

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

States a specific verb and resource: listing boards, with additional scope of bundled XDC and metadata. It is clear, but it does not differentiate from the sibling get_board_info, which an agent might reasonably consider for board-related information.

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 'No Vivado session required' gives useful context about when this tool can be called independently of session state. However, it does not explicitly say when to prefer this over get_board_info or list 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?

No annotations are provided, so the description carries the full disclosure burden. 'List all' implies a non-mutating, unfiltered read, which is useful, but it says nothing about who can see the requests, ordering, volume/pagination, or whether 'submitted' excludes drafts or closed items.

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 well-formed sentence with the scope qualifier ('all submitted') front and center and no wasted words. Its brevity is appropriate for a zero-argument call, though it could have used one more clause to route the agent to the sibling.

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 no annotations, the description is the only source of truth, and it does not describe what a returned feature request contains (id, title, status, votes, author) or the result shape. For a listing tool that is the key missing piece.

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, which is the baseline 4 case; there is no parameter meaning to document and the description correctly implies no filtering options exist.

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

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

Clear verb+resource: 'List all submitted feature requests' tells the agent exactly what it retrieves and that no filtering is applied. It does not, however, distinguish itself from its sibling request_feature (the write counterpart) or state how results relate to that tool.

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

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

No when-to-use guidance and no exclusions. The obvious alternative, request_feature (the sibling that submits a request), is never mentioned, so the agent must infer that this is the read side of that pair.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It implies a read-only listing of local bundled docs, but does not describe the return format, pagination, or whether any session/project state is required. For a zero-parameter list operation the behavior is simple, but the description remains minimal.

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 short sentence with the key operation and scope front-loaded. There is no wasted 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?

Given the low complexity, zero parameters, and no output schema, the description is minimally sufficient to call the tool. However, it does not explain what the listed topics look like or how they relate to get_vivado_doc, leaving a small but meaningful gap for an agent.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The description adds no parameter-level detail, which is appropriate given the empty input schema.

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

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

The description gives a clear verb and resource: 'List' plus 'bundled Vivado documentation topics.' An agent can understand the basic operation, but it does not explicitly differentiate this tool from the sibling get_vivado_doc, which likely retrieves a specific doc after listing.

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

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

There is no explicit guidance on when to use this tool instead of get_vivado_doc or other documentation-related tools. The listing intent is implied, but no conditions, prerequisites, or alternatives are stated.

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

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

No annotations are provided, so the description carries the full load. It does disclose meaningful behavior by revealing the tool's effect equals get_board_info + add_constraints, and "attach it to the current project" signals a state mutation. However, it omits key behavioral facts: whether a project/session must already be open, whether existing constraints are replaced or appended, and whether the operation is idempotent.

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, and the core action is front-loaded before the sibling relationship. Nothing could be removed without losing 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 simple two-parameter mutation with full schema coverage and no output schema, the essentials of what happens are covered. What is missing is the operational precondition (an open project/session, evidenced by "the current project") and the collision behavior when constraints already exist — both material for a mutation tool with no annotations.

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

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

Schema description coverage is 100% and both parameters carry their own descriptions including an example board id and the 'full' default for variant. The description adds nothing beyond "bundled board XDC", so the baseline 3 applies — the schema, not the prose, is doing the parameter work.

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

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

States a specific verb and resource ("Resolve a bundled board XDC and attach it to the current project") and then anchors it against two named siblings by declaring itself a wrapper over get_board_info + add_constraints. An agent can immediately tell what it does and how it differs from the primitive tools.

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

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

Naming get_board_info + add_constraints as the composed operations implicitly tells the agent to use this one-shot tool instead of chaining those two calls. There is no explicit "use when / do not use when" statement or exclusion (e.g. what to do if constraints already exist), 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?

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral boundary — that opening the manager does not establish a JTAG connection — which is genuinely useful. However, it says nothing about whether an active session is required, what happens if the manager is already open, or how to close it (the sibling close_hw_manager is never referenced).

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

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

A single short sentence with the essential scoping nuance front-loaded. Nothing is wasted and nothing extraneous is bolted on.

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

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

For a zero-parameter, no-output-schema state-setup tool, the definition is nearly complete. The only missing context an agent would want is the session prerequisite and the natural follow-up (connect_hw_server / close_hw_manager).

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a parameterless invocation.

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: 'Open the Hardware Manager'. The parenthetical '(no JTAG connection yet)' distinguishes it from connect_hw_server and close_hw_manager, making the scope of the operation clear without opening any schema.

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

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

Usage is only implied: the 'no JTAG connection yet' clause hints that connect_hw_server should follow, but there is no explicit when-to-use statement, no prerequisites (e.g. an active session), and no named alternative.

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