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

Annotations already declare the safety profile (readOnly=false, destructive=false, openWorld=false, idempotent=false), so the description's added value is the lifecycle and return contract: it says annotations clear when the design changes and that the call returns a local viewer URL and count. That ephemerality note is genuinely useful context an agent cannot get from the annotations, though permissions and size limits are only in the schema.

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

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

Three short sentences with zero filler; the action is front-loaded and each remaining sentence carries distinct information (return value, lifecycle). Nothing to trim.

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 write tool with no output schema, the description covers the essentials: what it replaces, what it returns, and that the effect is not persistent across design changes. It does not mention required permissions or confirm the clearing semantics of an empty list (that lives in the schema), so it is strong but not exhaustive.

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 `items` parameter is documented in detail (path/kind/severity/message, 200 cap, 2000 chars, pins/ports only, [] clears). The description adds nothing beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb ("Replace") and resource ("schematic annotations") plus the target objects ("instances or pins/ports"), so the agent immediately knows this is a mutation of annotation overlays. No sibling is named, but no other sibling tool does annotation work, so differentiation is implicit rather than stated.

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

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

Usage is only implied: you call it to set annotations on a schematic. There is no statement of when to prefer this over alternatives (e.g., get_schematic_selection for reading the current selection) or any precondition such as a design needing to be loaded first. Adequate but leaves routing and prerequisites to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the glob-dot path-switching rule and the return/pagination shape (matches with typed descriptors, count, has_more, next_cursor) in the absence of an output schema. It does not discuss result-ordering or cost, so it stops short of a 5.

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

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

Four tight sentences, front-loaded with the core action before usage guidance and return shape. Every sentence carries distinct information (purpose, routing, return structure) 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?

For a read-only search tool, the definition covers purpose, sibling routing, glob semantics, and the return/pagination contract. With annotations carrying the safety profile and no output schema, an agent has everything needed to call it correctly on the first try.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema (kind enum, limit default/cap, cursor origin, pattern dot rule). The description restates the pattern-dot behavior and explains pagination flow, but adds no syntax or constraints the schema lacks, so the baseline of 3 applies.

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

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

States a specific verb (search), resource (case-sensitive object names in the loaded design) and mechanism (glob), which is far more than the vague name 'find' conveys. It also names two siblings (resolve, get_hierarchy) and the conditions that select them, letting an agent distinguish it without opening a schema.

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

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

"Use this when an exact path is unknown; use resolve once a path is known or get_hierarchy to browse structure" gives explicit when-to-use, when-not, and named alternatives. Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description goes well beyond by disclosing the return shape (leaf FF/gate instances with pin, model, source ref; top-level ports), traversal behavior (lowered assign glue is traversed, not reported), edge-case encoding (constant 0/1/X/Z, bus bit entries), and pagination semantics (limit cap, truncated flag, no cursor). This is unusually complete behavioral disclosure.

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?

Well front-loaded — purpose first, then alternative routing, then return/pagination details. Dense but every sentence carries information, particularly the encoding details that would otherwise be undiscoverable without an output schema; slightly verbose but not padded.

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

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

There is no output schema, so the description must carry the return-value burden itself, and it does: it enumerates driver kinds, port endpoints, constant/bit encodings, and truncation signaling. Nothing an agent needs in order to call and interpret this tool 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; the description adds value beyond the schema by explaining that truncation is signaled via a `truncated` flag, that there is no cursor, and that raising `limit` is the only way to see more. That is meaningful operational semantics not present in 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 and resource ('List the immediate upstream endpoints that drive a term or net across hierarchy'), scoping it to direct/leaf drivers. It names the two neighboring tools it is not (get_loads for downstream, trace_cone for transitive fanin), so an agent can select it 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?

Explicitly says 'Use this for direct sources' and names both alternatives with the condition that selects each: get_loads for downstream readers, trace_cone for transitive combinational fanin. When-to-use and when-not-to-use are both fully specified.

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

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

Annotations already establish a safe read (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description goes well beyond them: it discloses that only non-assign children are listed, that `assign` glue is summarized as `assign_count`, that each child carries a `leaf` flag, that depth is capped at 5, and that root pagination uses limit/cursor with next_cursor/has_more while deeper levels report children_truncated. This is exactly the kind of result-shaping behavior an agent needs.

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

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

Front-loaded with the core action, and nearly every clause carries distinct information (sibling routing, assign handling, leaf flag, depth cap, pagination). It is dense and somewhat run-on, but there is essentially no filler to cut.

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

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

There is no output schema, so the description carries the full burden of describing return shape — and it does, covering assign_count, the per-child leaf flag, next_cursor/has_more, and children_truncated. Combined with the sibling routing and depth limits, an agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, and the schema already documents path, depth, limit, and cursor. The description adds genuine meaning the schema lacks: that depth is capped at 5, that pagination applies only at the root while deeper levels truncate, and that the cursor is a root-level opaque token. It does not add syntax/format detail for `path`, so it stops short of 5.

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

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

States a specific verb and resource ('Browse the instance tree below `path`') and immediately scopes it against siblings ('use find for design-wide name search or get_stats for aggregate model counts'). An agent can distinguish it from find/get_stats/get_module_card 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?

Explicitly names two alternative tools and the exact condition that selects each (design-wide name search vs aggregate counts vs structural children). It also clarifies the fallback behavior for `assign` children and where pagination applies, leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavioral context: the 'warm-only' precondition (requires the intent layer to be loaded) and the explicit degraded-return behavior ('returns a note') with a fallback instruction. This is meaningful disclosure beyond the annotations.

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

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

Front-loaded with the core concept, then scoped to specifics, then parameter guidance and fallback. Dense but each sentence carries weight; slightly heavy prose keeps it from a 5.

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, yet the description adequately characterizes what is returned (state names + encodings, symbolic parameter formulas) and the degraded-case behavior. An agent has enough to call it correctly and know when to switch 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 already 100%, so baseline is 3, but the description adds value by enumerating the ref forms (hierarchical path, package member 'riscv::PLEN', instance path for parameters) and clarifying that 'auto selects from the reference', which enriches the enum semantics.

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

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

States a specific verb+resource ('Retrieve source-level intent') and pinpoints exactly what it returns: enum/typedef state names with encodings and symbolic PARAMETER expressions. It clearly distinguishes itself from get_source and get_module_card by naming the 'type/declaration, not the flattened gates' scope.

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 when to use it ('when the answer is in the SystemVerilog type/declaration') and provides the alternative path: if the intent layer is not loaded it returns a note and you should fall back to get_source. Both the when and the when-not are covered.

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

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

Annotations already declare a safe read-only, idempotent, non-destructive operation, but the description adds substantial behavior beyond them: the exact return shape (leaf readers with pin/model/source ref, plus top-level ports), that lowered assign glue is traversed rather than reported, and the pagination contract (capped at limit, default 50/max 200, truncated flag, no cursor). These are genuine non-obvious traits that an agent could not derive from annotations or schema.

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

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

Front-loads the core purpose, then routes to alternatives, then covers return shape and pagination in a compact, well-ordered block. Every sentence earns its place with no filler, despite a slightly odd internal line break.

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 takes on the burden of explaining return values and does so (leaf readers, top-level ports, lowered glue handling), while also covering alternatives and pagination. Nothing an agent needs to call 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% — both path and limit are fully documented in the schema, including the same default/max values. The description reinforces the limit semantics and adds 'no cursor — raise limit to see more', which is minor incremental value. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 (immediate downstream endpoints that consume a term or net across hierarchy), and immediately distinguishes itself from siblings get_drivers (upstream) and trace_cone (transitive fanout). An agent can select it correctly 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?

Explicitly says when to use this tool ('for direct readers') and names the two alternatives with the conditions that select them ('get_drivers for upstream sources', 'trace_cone for the transitive combinational fanout'). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds critical non-structured context: clock/reset results are 'a name-based regex guess, not a structural result; verify before relying on it.' This discloses result reliability, which an agent cannot infer from annotations or schema.

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

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

Front-loaded with the payload contents, then the caveat, then the alternative routing — well ordered with no filler. It is dense and packs several distinct claims into two sentences, but every clause carries information.

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

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

No output schema, so the description correctly enumerates what is returned, flags the heuristic nature of part of it, and routes to the alternative tool. Combined with annotations covering safety, an agent has everything needed to call it and interpret results appropriately.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents that 'module' is the elaborated module/model name (not an instance path). The description reinforces 'one model's interface' but adds no syntax or format detail 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+resource (module summary) and enumerates the payload: ports, instance counts by model, sequential count, source ref, clock/reset candidates. It also explicitly contrasts itself with get_stats, so an agent can distinguish it from siblings without opening schemas.

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

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

Explicit routing: 'Use this for one model's interface; use get_stats for counts below an instance.' Names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds genuinely useful behavioral facts beyond that: the value reflects the *last* selection (state-dependent) and may be null, which an agent must handle. It stops short of explaining what a naja-scope path is.

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 return contract is front-loaded and the follow-up routing sentence immediately adds actionable value. Every clause earns its place.

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

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

For a zero-param getter with no output schema, the description fully covers the return contract (path or null) and next steps. The only omission is any explanation of the naja-scope path format, which an unfamiliar agent would have to infer from the referenced consumer 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter guidance is 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?

States a specific verb and resource ('Return the last browser-selected instance'), specifies the output format ('as a naja-scope path, or null'), and distinguishes itself from siblings that consume its output. An agent knows exactly what this returns without opening anything else.

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

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

Explicitly directs the agent to feed the result into module-card, source, or hierarchy tools, which is a concrete usage path. It doesn't state when the tool should NOT be called or note that it depends on prior browser interaction, but no true alternative exists among siblings, so the guidance is adequate.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the origin re-call workflow, the fields returned (object, file, start/end range, text, truncation status), and structured errors on missing paths. It exceeds the annotation bar without contradicting anything.

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

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

Front-loaded with the core purpose before the alternatives and the origin workflow. It is dense but every sentence (examples, alternative, workflow, return/error behavior) earns its place; the parenthetical examples are the only mild padding.

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

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

With no output schema, the description carries the return-value burden and does so: it names the returned fields, truncation status, and structured error behavior for missing paths. Combined with full schema coverage and annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline would be 3. The description still adds meaning by framing origin as a two-step workflow (list origins, then re-call with origin=N) and by contrasting it with reading a declaration, which is more than the schema's field-level text conveys.

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

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

States a specific verb and resource (read the bounded source excerpt that produced an object) and grounds it with concrete examples mapping an SV FF instance to its always_ff block. It explicitly distinguishes itself from the sibling get_intent by scope, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use ('when exact source text is needed'), names the alternative and its domain ('use get_intent for typedef/enum/parameter semantics'), and describes the follow-up workflow (call again with origin=N when the response lists origins). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds a real precondition (a loaded design is required) and describes the return shape (root_model, totals, paginated models list, pagination fields), which is genuinely useful since no output schema exists. It stops short of describing pagination limits behavior in prose, but the schema covers limit/cursor.

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

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

Three sentences, front-loaded with purpose, then routing, then precondition and return shape. The return-field list is dense but earns its place because there is no output schema. Slightly run-on but no waste.

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

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

For a read-only stats query with full schema coverage and no output schema, the description covers purpose, alternatives, precondition, and return fields. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents path, limit, and cursor fully (including the 200 cap). The description reinforces path semantics ('below `path` or the top design') but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (summarize) and resource (instance population by model) with explicit scope ('below `path` or the top design'). It even names the two sibling tools it is not (get_hierarchy, get_module_card), so an agent can distinguish it 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?

Gives explicit routing: 'Use this for aggregate leaf/sequential/model counts; use get_hierarchy for actual child instances or get_module_card for one model's ports.' It also states the precondition ('requires a loaded design'), leaving nothing to inference.

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

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

Annotations declare destructiveHint=true, and the description goes further by naming what is destroyed: 'it replaces the active universe by re-elaborating from explicit or captured flist/files.' It also discloses the idempotency-like no-op path when the link is already live, the return value (intent_loaded), and the error behavior for missing inputs.

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

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

Front-loads the purpose, then the precondition, exclusions, alternative, and side effects in five tight sentences with no filler. Every clause carries actionable 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 3-parameter mutation tool with no output schema, the description covers preconditions, exclusions, the destructive replace-the-universe side effect, the reuse behavior of omitted params, and the return/error signals. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so top/files/flist are already documented with their reuse semantics. The description only echoes the 'explicit or captured flist/files' concept without adding format or precedence detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb+resource: makes the warm source-intent layer available for get_intent. It explicitly names the sibling alternative (load_systemverilog(intent=True)) and the case it serves, so an agent can distinguish it from the load_* family without opening schemas.

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

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

Gives explicit when (after a SystemVerilog load that did not retain intent), when-not (VHDL or gate-level Verilog), and the preferred alternative on initial load (load_systemverilog(intent=True)). All routing conditions are stated rather than implied.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false), so the bar is lower, but the description adds real value by stating it 'changes session state' and returning `{"ok": true}` — a return shape that matters because there is no output schema. It stops short of noting failure modes (bad paths, duplicate loads) or that repeated invocation is not 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?

Three tight sentences, front-loaded with the action, then the ordering prerequisite, then the alternative and the state/return note. No filler and nothing buried.

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 loader with no output schema, the description covers purpose, sequencing relative to load_verilog, the sibling alternative, and the return value. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single `files` parameter is already documented as 'One or more local Liberty .lib file paths.' The description's mention of local `.lib` files merely restates the schema, adding no syntax, globbing, or multi-file resolution detail. Baseline 3 for a fully covered 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: 'Register standard-cell models from local Liberty `.lib` files in the active session.' It is immediately distinguishable from load_primitives (built-in model sets) and load_verilog/load_vhdl 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?

Explicitly gives the ordering condition ('use this before load_verilog when a gate netlist instantiates those cells') and names the alternative with its selecting condition ('use load_primitives instead for the built-in Xilinx or Yosys model sets'). This is a full when/when-not/alternative routing statement.

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

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

Annotations declare a destructive, non-idempotent, open-world write, and the description adds genuinely non-redundant context: custom files execute unsandboxed Python in the server process and must be trusted. It also discloses precedence behavior and the return value `{"ok": true}`.

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

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

Three tight sentences that lead with the action and source choice, then the precedence rule, then the risk note and alternative. Slightly dense with clauses, but essentially 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 two-optional-param tool with no output schema, the description covers source selection, precedence, the execution-security caveat, the alternative sibling for a related file format, and the return shape. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100% and both parameters are already documented with the same precedence semantics ('used only when name is omitted', 'when set, file is ignored'). The description largely restates that, so the baseline 3 applies; it adds the trusted-code constraint but no additional parameter syntax.

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 ('Register primitive models in the active session') and enumerates the two mutually exclusive sources (built-in `name` or local Python `file`). It also names the sibling it is not (load_liberty), so an agent can route correctly without opening a schema.

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

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

Gives an explicit either/or rule ('Provide one source; `name` takes precedence when both are set') and an explicit alternative for a plausible adjacent task ('Use load_liberty instead for standard-cell `.lib` files'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations mark this as non-read-only and non-idempotent, and the description adds real context beyond that: the version-compatibility requirement, the performance profile ('in seconds instead of re-elaborating'), and the side effect of intent=True rebuilding the warm intent layer. It does not state what happens on a version mismatch or exactly which session state is overwritten, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the benefit and immediately followed by the fallback rule and precondition. No filler, though the closing intent clause is slightly dense relative to its value.

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

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

For a two-parameter, no-output-schema tool with annotations present, the description covers purpose, precondition, alternative tools, and the optional parameter's effect, which is enough to invoke it correctly. Return behavior is not described, but no output schema exists to carry that burden.

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 goes further by explaining that intent=True re-elaborates the warm intent layer 'for get_intent', giving the parameter purpose in the workflow rather than just restating the schema text. The directory parameter's snapshot origin is already covered by 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 (load a save_snapshot directory into the active session) plus the exact outcome (fast restore instead of re-elaboration). It is clearly separable from save_snapshot and from the load_systemverilog/load_verilog/load_vhdl siblings, which it names.

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 decision rule: use load_systemverilog/load_verilog/load_vhdl when no compatible snapshot exists, and adds the hard precondition that the directory must match the najaeda version. Alternatives and the condition selecting them are named outright.

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

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

Annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) establish the mutation profile; the description adds real context on top: it changes the in-memory design session, blackboxes undefined modules, retains the SNL↔slang link for get_intent, and notes anonymous objects are addressable by #<id>. It stops short of describing return shape or failure semantics, so 4 rather than 5.

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

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

Front-loaded: purpose, then sibling routing, then the precondition, then per-flag detail. Every sentence carries weight, though the defines syntax and intent wording partially restate text already in the schema descriptions, adding mild redundancy.

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

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

For an 8-parameter mutation tool with no output schema, the description covers purpose, alternatives, prerequisites, and the non-obvious flag semantics well. It omits what happens on repeated loads (idempotency behavior) and error/result reporting, which an agent would benefit from knowing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds value beyond the schema: the `files`-or-`flist` requirement is not expressible in the schema (neither is required), and it explains the practical effect of allow_unknown_designs (undelivered hard macros in partly-open-source designs) and blackbox_multi_writer_memories (multi-writer memories naja cannot infer).

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 ("Elaborate") + resource ("local SystemVerilog sources") + destination ("active design session"). It explicitly names how it differs from siblings load_vhdl, load_verilog, load_liberty and load_primitives, so an agent can disambiguate 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?

States exactly when to pick this tool (SystemVerilog RTL) and routes to named alternatives for VHDL and structural gate netlists. It also gives a hard prerequisite ("Requires at least `files` or `flist`"), which is critical since the schema declares zero required parameters.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotent=false, openWorld=false, destructive=false). The description adds substantive behavior beyond them: unresolved modules fail unless allow_unknown_designs is true, and yosys_source_attributes records RTL origins consumable via get_source. It also flags a downstream limitation (get_intent cannot answer for netlists), which is genuinely non-obvious.

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

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

Purpose is front-loaded and each sentence is dense and useful, but the trailing sentences about get_source and get_intent drift into describing sibling tools' behavior, which is slightly more than this tool's own contract requires. Still lean 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 load tool with no output schema and high-complexity session side effects, the description covers prerequisites, alternatives, failure semantics, and downstream tool interactions. Nothing an agent needs to call 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. The description restates the effect of allow_unknown_designs and yosys_source_attributes that the schema already documents, adding only the get_source origin=N usage detail, which is marginal incremental value over the structured fields.

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

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

States a specific verb (Load), resource (gate-level/structural Verilog), and target (active session), and explicitly distinguishes itself from load_systemverilog ('for RTL elaboration'), load_liberty, and load_primitives. An agent can route correctly 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?

Gives explicit ordering prerequisites ('First call load_liberty... or load_primitives') and names the alternative for the RTL case ('use load_systemverilog instead'). When-to-use and when-not-to-use are both covered with named siblings.

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

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

Annotations declare it non-read-only and non-idempotent; the description goes well past that by disclosing beta limitations (restricted subset, possible failures on unsupported constructs), the possibility of top=null for package-only or generic-awaiting entities, and unavailable SV intent recovery with unguaranteed source ranges. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loads the core action and then layers caveats efficiently; every sentence (batch preference, package-first ordering, beta limitations, return summary) carries information. It is dense but not padded, though the caveat block is slightly long.

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

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

With no output schema, the description correctly fills that gap by stating it returns the top summary plus language and beta status, and it warns about top=null before the agent misreads a result. For a stateful loader in beta, this is complete enough to call 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 100%, so baseline is 3, but the description adds real meaning: files may be passed in any order because units resolve across files, and top may remain null for specific design shapes. It explains the batch-vs-single semantics rather than restating 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 ("Load VHDL into the active session") and scopes it to a beta two-state RTL subset, which cleanly distinguishes it from load_systemverilog and load_verilog among its siblings. An agent can select it purely on language identity.

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 concrete how-to-use guidance: prefer one batch list in any order, and if going single-file, load packages before the top. It also names downstream queries (hierarchy, cards, connectivity) as the intended follow-on. It stops short of explicitly contrasting when to pick this loader over its sibling loaders.

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

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

Annotations cover the safety profile (destructiveHint=false, openWorldHint=false), but the description adds genuinely useful context beyond them: it returns a local URL, that URL lives on the MCP server's machine (a real gotcha for a remote caller), and it requires the schematic extra. It never explains why readOnlyHint is false even though the operation looks like a pure view, leaving a small 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?

Three tight sentences with the core action front-loaded and no filler. Minor structural looseness in the trailing sentence, which packs two unrelated details ('loaded design' and '#id instances') together, keeps it from a 5.

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 its job by stating what is returned (a local URL) and the requirement to have the schematic extra and a loaded design. The agent has enough to call it correctly; the only missing piece is guidance on how the returned URL should be consumed or when this tool is the right choice.

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 path parameter's meaning ('Instance path to focus; omit for the top') is already fully documented. The description's phrase 'supports anonymous #id instances' adds a hint about accepted id forms but does not define syntax or format, so the schema carries the load and the baseline 3 applies.

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

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

The description gives a specific verb and resource: 'Serve an interactive browser schematic of the current design.' That is far more informative than a restated name and the nature of the tool is unmistakable. It does not, however, explicitly differentiate itself from schematic-adjacent siblings such as annotate_schematic or get_schematic_selection, so it falls short of a 5.

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

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

Usage is only implied: 'requires the schematic extra' and 'Uses the loaded design' hint at prerequisites, and the mention of the current design implies a design must already be loaded. There is no explicit when-to-use, when-not-to-use, or routing to an alternative tool, which is the core of this dimension.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the crucial blast radius: it destroys session state yet does NOT delete source or snapshots, and it is safely repeatable. This is exactly the contextual disclosure annotations cannot convey, and it is consistent with them.

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

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

Four tight sentences, each earning its place: purpose first, then usage boundary, then destructive scope, then idempotency and return value. Front-loaded and entirely free of filler.

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

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

For a zero-parameter, no-output-schema tool, the description covers everything: what it clears, when to invoke it, what it does not affect, and its return value. Nothing an agent needs to call it safely is absent.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; the schema has no fields to document. Baseline of 4 applies since nothing is missing on the input side.

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 and resource — 'Discard the active design and all in-memory session state' — with a clear scope. It implicitly separates itself from read-only siblings by warning 'do not use merely to inspect status', so an agent can distinguish it from status 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?

Gives genuine when-to-use ('before starting an unrelated design') and when-not-to-use ('do not use merely to inspect status') guidance. It stops short of naming the concrete alternative tool (the `status` sibling) that should be used for inspection, so the routing is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description still adds real behavior, namely that it requires a loaded design and returns did-you-mean suggestions on failure. It stops short of describing match ordering or how source references are formatted, so it is strong but not exhaustive.

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

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

Three tight sentences: purpose first, then syntax affordance, then alternative routing and prerequisites. Every clause carries information; no filler.

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

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

For a read-only resolve query with full schema coverage, no output schema, and a small sibling set, the description covers purpose, path syntax, alternatives, prerequisite state, and failure behavior. Nothing an agent needs to call 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 baseline is 3, but the description goes beyond the schema by giving a concrete glob/bit-select example (`top.u_uart.tx_o[0]`), which clarifies the path syntax in a way the property text does not. It adds no further meaning for kind or limit.

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 (resolve) and resource (hierarchical object path) and states the output artifacts (instance/term/net descriptors with source references). It explicitly distinguishes itself from find and get_hierarchy, so an agent can tell what this does without opening a schema.

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

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

Gives explicit routing: 'Use find when the path is unknown; use get_hierarchy to browse children', plus the prerequisite that a design must be loaded. Both the alternative tools and the condition selecting them are stated, leaving nothing to inference.

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

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

Annotations already declare destructive=true and idempotent=true, so the write profile is partly covered; the description adds real value beyond that with 'Existing snapshot files in the directory may be overwritten' and the version-coupling caveat. It also discloses that the return includes the saved path, which matters since no output schema exists. Minor gap: it doesn't state auth/permission requirements.

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

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

Three short sentences, front-loaded with the verb+resource, then the trigger, then the caveats. Every sentence carries distinct information (purpose, when, side effects/compat) 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?

For a one-parameter write tool with annotations covering the safety profile, the description covers trigger, overwrite risk, version compatibility, and the return path even though no output schema exists. Only permission/error behavior is left unstated.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents 'directory' as the local destination for naja-if and metadata files. The description's 'local directory' wording only marginally reinforces this, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Write the active design and source metadata to a local directory') with the purpose ('for fast reload'). It explicitly names its counterpart 'load_snapshot reads the result', so an agent can distinguish it from the load_* siblings without opening a schema.

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

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

Gives a clear trigger ('Use after loading a design') and names the complementary tool that consumes the output. It stops short of stating when not to use it (e.g., prior to loading) or whether it can be re-run mid-edit, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: it enumerates the returned fields (`loaded`, top summary, loaded source files) and explains the `intent_loaded`/`intent_loadable` state semantics.

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

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

Front-loads purpose, then usage, then return shape in a tight block with no filler. The phrase 'without changing it' slightly duplicates the readOnlyHint annotation, but otherwise every sentence earns its place.

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

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

With no output schema, the description carries the return-value burden and does so ('Returns `loaded` and, when available, the top summary and loaded source files'). For a zero-parameter read tool this is essentially 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 takes zero parameters, so the baseline is 4; there is no parameter syntax an agent needs the description to supply.

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 ('Inspect the current in-memory session') and scopes it with 'without changing it', which an agent can distinguish from the load_* siblings. It does not explicitly name a sibling to contrast against, keeping it just below 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?

Gives clear context ('Use this before design queries'), states the conditions it confirms (a design being loaded, whether get_intent is live or reloadable), and references get_intent as the related tool. No explicit when-not or exclusions, so not a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real traversal semantics: the cone crosses hierarchy and combinatorial arcs and always terminates at flops, top ports, and opaque black-box cells. This is behavior beyond the annotations, though much of the rest of the text shifts toward return format.

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

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

Purpose and the sibling distinction are front-loaded, and most sentences carry useful information. It runs slightly long, with return-shape detail that could be tightened, but nothing is gratuitous.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly (node_count, counts_by_kind/model, frontier shape, truncation marker, cross_hierarchy/outside_root_subtree semantics). Combined with full param coverage and rich annotations, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both direction and max_frontier are already documented (including the 1..200 clamp and default 50). The description restates direction and the <=200 cap but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Trace) and resource (combinational fanin/fanout cone of a term/net) with clear scope, and names get_drivers/get_loads as the immediate-endpoint alternatives, so an agent can distinguish it from siblings 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?

Explicitly says when to use it (transitive logic reachability) versus the alternatives (get_drivers/get_loads for immediate endpoints only), which is exactly the selection guidance an agent needs.

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