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

No annotations are present, so the description carries full disclosure burden, but it only enumerates assertion kinds. It does not state how multiple assertions are evaluated, what pass/fail or return semantics are, or side effects such as the knowledge-vault write-back described 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?

Two short, front-loaded sentences: the first states the operation and target, the second lists supported assertion forms. No filler or tautology.

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 rich schema covers parameter semantics and the knowledge side effect, so the description is adequate for initial selection and invocation. However, with no annotations and no output schema, the missing evaluation/return and usage-boundary information leaves material gaps for autonomous use.

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; the description adds value through '和/或' clarifying that log and vcdPath can be combined, and by paraphrasing enum meanings ('终值/指定时刻/永不等于').

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 operation ('做声明式断言判定') on a specific resource ('fpga_sim 日志和/或 VCD') and lists concrete assertion modes. This makes it clearly distinct from sibling tools like fpga_sim, fpga_log_extract, and fpga_wave.

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 'fpga_sim 日志和/或 VCD' phrasing gives clear context that the tool validates simulation artifacts, and the supported assertion types signal when it applies. It does not explicitly name alternatives or when-not conditions, so it does not merit a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so well by revealing that the tool returns cost/safety notes and that serverVersion acts as a runtime code fingerprint whose mismatch with the working tree HEAD indicates stale service requiring restart. It does not explicitly state 'read-only', but the return-oriented phrasing and the absence of mutation language make the safety profile reasonably transparent.

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

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

The description is two dense, front-loaded sentences with no filler. The first sentence states the primary return value and purpose; the second adds a critical ops detail about serverVersion. Every clause contributes useful information for invocation.

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

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

Despite having no output schema and no annotations, the description explains the main return kinds (catalog, long-tail routing, cost/safety notes, serverVersion) and even interprets the serverVersion semantics. For a parameterless discovery tool, this is sufficient for an agent to understand what it will receive and why it matters.

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 and the schema description coverage is 100%, so there is nothing meaningful for the description to add about parameters. According to the zero-parameter baseline, a score of 4 is appropriate because the description correctly focuses on return content rather than inventing parameter details.

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-resource pair: it returns a layered tool catalog (tier0 hot/tier1 common/tier2 expert) plus a server version fingerprint. It clearly differentiates itself from sibling tools by positioning itself as the discovery entry point to the complete PDS control plane, rather than a tool that performs an FPGA operation.

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

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

The description explicitly says it is '用于发现完整 PDS 控制面' (used to discover the complete control plane) and notes that long-tail capabilities are reached via fpga_cdt/fpga_exe, which gives the agent routing guidance. It does not explicitly state when not to use it, but the discovery-oriented framing is clear enough.

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

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

With no annotations, the description carries the safety burden and discloses critical behavior: destructive write-device operations are gated by confirm and expectIdcode plus a scan check, and connect:true silently wraps commands in connect/scan_chain/disconnect while raw tcl uses {{PORT}}. It does not spell out exact failure modes or return format, but the guardrail and connection behavior are well covered.

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 dense but optimally sized, front-loading purpose and then adding guardrail and connection rules. The compressed notation (cfg_jtag_flash_erase|program, confirm:true) is efficient, though slightly less readable, so a 4 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?

For a 12-parameter, no-annotation, no-output-schema tool, the description covers guardrails, invocation modes, and coverage, but it omits what the tool returns (raw Tcl output? summary/full structure?) and does not position the tool against the many fpga_* siblings. This leaves an agent with meaningful gaps for a high-complexity 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 baseline is 3, and the description adds real interaction semantics: connect:true pairs with commands, raw tcl requires {{PORT}}, and confirm/expectIdcode are tied to write-device commands. This tells an agent how the parameters relate, which the bare schema does not.

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

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

The description clearly states the tool runs arbitrary cfg_* (cdt_cfg) or dbg_* (cdt_dbg) Tcl against cdt_js and enumerates the covered operations (scan, read, config, SPI flash, ILA, virtual-IO). It does not name explicit sibling tools for differentiation, so it earns 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?

It gives clear operational conditions: read-class commands are unrestricted; write-device commands require confirm:true and expectIdcode with prior scan validation; connect/scan/disconnect auto-wrapping depends on commands vs raw tcl. However, it never says when to choose this generic pass-through over the many specialized siblings (fpga_jtag_scan, fpga_flash_*, fpga_ila_*), so usage vs alternatives is only implied.

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

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

With no annotations, the description carries the full disclosure burden and delivers: it states chunks are '直接可用' (directly usable), PDF paths are returned for the host agent to Read, and the no-query fallback returns a manual list. It also reveals the cost profile ('无 embedding、零额外成本'), a useful behavioral trait absent from schema/annotations. It stops short of describing zero-result behavior or result ordering.

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

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

Four dense sentences with zero filler: the action is front-loaded, the two-tier return contract follows immediately, parameter behavior is packed into the middle, and the cost note closes it. Every sentence earns its place relative to a 4-parameter 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 moderate-complexity search tool with no output schema, the description competently sketches the return contract (chunk text vs PDF path) and default behaviors. The remaining gaps are minor: no explicit return structure/ranking details and no pointer to the sibling msim_doc_search for non-PDS documentation.

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 baseline is 3, but the description adds genuine meaning beyond the schema: it enumerates what chunks contain (Tcl/编译流程/扫链烧录/ILA 调试), gives the exact registry size (21+62), and clarifies that 'semantic' mode does not rely on embeddings. This meaningfully supplements the bare parameter 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?

The description opens with a specific verb+resource ('检索 PDS 文档层') and explains the two-tier result structure: distilled text chunks that are directly usable versus PDF paths the host agent can Read for 21 PDS manuals + 62 IP datasheets. This scoping clearly differentiates it from sibling fpga_msim_doc_search (MSIM docs) and fpga_ip_lookup without ambiguity.

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 clear usage context: query drives keyword recall, kind restricts scope to all/chunk/manual/datasheet, and omitting query returns the manual list. However, it never names alternatives or exclusions — notably the near-twin sibling fpga_msim_doc_search — so an agent gets context but no explicit when-not-to 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 provided, the description carries the behavioral disclosure burden. It discloses the probing scope, the local vs remote SSH behavior, and the kinds of information reported. It does not explicitly state 'read-only' or describe failure/error behavior, but '报告' and '探测' strongly imply a non-mutating reconnaissance 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?

The description is two sentences, front-loads the tool's purpose, and packs the essential behavioral distinctions (local vs remote, same probing logic) without redundancy. Every clause adds 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 an environment probe with one optional parameter and no output schema, the description covers the input semantics, execution mode, and the full set of reported items. It is complete enough for an agent to select and invoke the tool, though it could optionally mention SSH prerequisites or the absence of side effects.

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

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

The schema already documents host as a remote device id from pango-mcp.config.json, and description coverage is 100%. The description adds meaningful semantics by explaining that omitting host means local, while providing host triggers SSH-based probing of the remote execution-device layer with identical logic.

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

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

The description uses a specific verb ('报告'/report) and a concrete resource (FPGA workflow environment), enumerating exactly what is probed: iverilog/vvp, verilator, gcc, node/pnpm, PDS/cdt paths, license availability, and MCP server instance ownership. It clearly distinguishes this tool from the flow-oriented siblings by positioning it as an environment discovery/probe 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?

The description gives clear usage context: default is local probing, and passing a host switches to SSH-based probing of a remote execution-device layer with the same logic. It does not explicitly name alternatives or exclusions, but the local/remote usage rule is concrete and actionable.

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. It does add useful behavioral context: only listed tools are in scope, output is extracted and returned, and -help/-version probing is possible. However, it never explains what the claimed 'guardrail' enforces, potential side effects, permissions, or failure behavior, so the disclosure is incomplete.

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

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

Two dense but purposeful sentences cover the action, the allowlist, the exclusion set, and the routing alternatives. No filler or repetition of schema content; the key constraints are front-loaded.

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

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

For a generic executable passthrough with 7 parameters, no annotations, and no output schema, the description gives enough selection guidance but not enough execution detail. It omits the return format, error handling, guardrail specifics, and any prerequisites, leaving an agent to discover these at runtime.

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 tool description's tool list is already reflected in the exe parameter description. The only extra parameter-relevant guidance is the -help/-version probing tip, which is operational rather than semantic.

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 operation—executing build/analysis PDS bin tools (with an explicit allowlist) and returning extracted output—and explicitly excludes device/JTAG and GUI tools. This makes it easy to tell apart from fpga_cdt and fpga_pds_run without inspecting 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?

It states when to use the tool (build/analysis bin tools), when not to (device/JTAG and GUI tools), and names the correct alternatives (fpga_cdt, fpga_pds_run). It also gives the actionable hint to probe any bin exe with -help/-version.

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

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

With no annotations provided, the description carries the full burden, and it delivers meaningful safety-relevant behavior: the operation is persistent and destructive, it is gated by confirm=true, and it internally scans and verifies expectIdcode before writing. This goes well beyond the schema for a dangerous flash-write tool. It does not cover failure behavior (e.g., what happens on IDCODE mismatch) or overwrite/erase specifics, but the critical safety profile 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?

A single compact sentence front-loads the mechanism and persistence trait, then immediately delivers the danger warning and the two safety requirements. Every word earns its place; no filler, no repetition of schema content.

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

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

For a 10-param destructive tool with no annotations and no output schema, the description covers the most critical contextual elements: mechanism, persistence, danger, the confirmation gate, and internal IDCODE verification. Minor gaps remain (no return/result info, no failure-mode behavior, no prerequisites like JTAG connection state), but the schema documents all parameters at 100% and the safety-critical workflow is described.

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 behavioral meaning to two key parameters beyond the schema: confirm must literally be true (enforcement gate) and expectIdcode is checked internally via a scan step. This is useful nuance that reinforces how those parameters behave at runtime, not just what they 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?

The description states a specific verb (持久烧录/persistently burn) plus the resource (板载 SPI Flash) and the mechanism (FPGA JTAG->SPI bridge). The word 持久 (persistent) distinguishes it from volatile alternatives like fpga_flash_sram, and the mechanism distinguishes it from fpga_jtag_flash. Purpose is unambiguous and differentiates well from 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?

Usage is implied through 持久烧录 (persistent flashing, implying it is for final/production writes rather than volatile) and 危险动作 (dangerous, implying caution is required). However, it never explicitly names alternatives or states when not to use it — e.g., it doesn't say 'for volatile/debug use fpga_flash_sram' or contrast with fpga_jtag_flash. No exclusions 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 of behavioral disclosure. It explicitly discloses that this is a dangerous action, that confirm=true is mandatory, and that the tool internally scans and verifies expectIdcode before burning. This is meaningful safety-relevant context, though it does not describe what happens on IDCODE mismatch or after successful programming.

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 short sentences with no filler. The action is front-loaded, and the critical safety constraint follows immediately. Every word contributes necessary information.

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

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

For a dangerous mutation tool with no annotations and no output schema, the description is incomplete. It omits when to prefer this over fpga_flash_spi, what happens if the expectIdcode check fails, power-cycle volatility implications, and what a successful result looks like. The rich parameter schema does not compensate for missing operational and failure context.

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 a baseline of 3 applies. The description adds behavioral meaning to parameters beyond schema text: confirm is framed as a required safety gate, and expectIdcode is tied to the internal scan-and-verify behavior. This goes beyond the schema's basic field descriptions.

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

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

The description states a specific action ('烧 .sbit') and a specific resource ('FPGA SRAM'), immediately distinguishing it from siblings like fpga_flash_spi, which targets SPI flash. The verb and resource are concrete enough for an agent to understand the core operation without opening the 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?

The description gives no explicit when-to-use or when-not-to-use guidance, and does not mention alternatives such as fpga_flash_spi for persistent storage. It warns that the action is dangerous and requires confirm=true, but this is a safety requirement, not a selection rule between tools.

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

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

No annotations are present, so the description carries the full transparency burden. It discloses three important behavioral traits: offline operation, no hardware connection, and optional bin genertion with byte/bit reversal that are fully parameterized. It does not mention output-file overwrite behavior or timeouts, but for a file-genertion tool this is reasonably sufficient and non-misleading.

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

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

One compact sentence is front-loaded with the core operation and immediately adds the critical offline/no-device distinction. Each phrase earns its place, with no redundancy or filler.

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

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

For a relatively simple file-genertion tool, the description combined with a fully documented schema covers the essential context: purpose, offline behavior, no hardware, and optional bin/reversal modes. It does not explicitly state that files are written to disk, but this is heavily implied by '生成文件' and the outfile parameter, and no output schema is expected for 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% and every parameter (infile, outfile, pdsVersion, timeoutSec, createBinFile, reverseBitInAByte, reverseByteInAWord) already has a description. The tool description only re-stares the existence of bin and reversal options without adding new parameter meaning, 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?

Description uses specific verb '合成' (combine) with concrete resources (.sbit files) and output (SPI chain file). The explicit '不连器件' (does not connect to device) distinguishes it from hardware-flashing siblings like fpga_flash_spi and fpga_jtag_gen_svf. The main purpose is immediately clear and 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?

Description provides clear context: use this when you need to generate an SPI chain file offline from two or more .sbit files without a connected device. This gives an agent a solid selection rule. It does not explicitly name alternatives or say when not to use it, so it falls just shy 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 present, so the description carries the full behavioral burden. It discloses that the tool does not connect to the device, performs an offline merge, and does not hard-code offsets, which are meaningful behavioral traits. It does not discuss error handling or file overwrites, but the critical no-device behavior is explicit.

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 dense sentence with no filler. Every clause contributes signal: offline operation, multi-image merging, type selection, and caller responsibility. The core action is front-loaded before constraints.

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 full schema coverage and no output schema, the description provides the essential operational context: offline, no device, caller-controlled inputs, and type selection. It does not describe return values or exact output artifacts, but the schema's outfile, goldenOutFile, and appliedOutFile fields fill most of that gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces that infile and sbitStartAddress are caller-provided and that type selects the stream type, but this mostly overlaps with existing schema descriptions. It adds only the '偏移不写死' nuance 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: offline synthesis of two or more .sbit files into a multi-boot/upgrade data stream. It distinguishes itself from hardware-connected sibling tools by explicitly saying '不连器件' and clarifies the multi-boot/upgrade 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?

The description clearly indicates this tool is for offline generation without a connected device, and that the caller must supply infile and sbitStartAddress while type selects the stream kind. It provides clear context for when to use it, though it does not explicitly name sibling alternatives such as fpga_gen_chain_file.

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

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

With no annotations, the description carries the burden and does well: it discloses the offline/no-hardware nature, the lack of built-in board defaults, and the parameterized flash model/read opcode/start address. It does not mention overwrite behavior or return details, but those are minor for a file-generation tool.

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

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

The description is two sentences, front-loades the core transformation, and each sentence adds distinct value: offline/no-hardware context and multi-boot routing. There is no tautology or redundant 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?

Combined with a fully documented schema, the description supplies the key operational context an agent needs: it is an offline generation step, not a hardware-bound operation, and multi-boot is handled elsewhere. It could add a note about prerequisites such as PDS environment, but the schema's optional pdsVersion and the sibling tool set already hint at that.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a useful umbrella statement that flash model, read opcode, and start address are fully parameterized, but it does not replace the schema-level 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?

The description states a specific operation: offline conversion of .sbit to .sfc via cfg_gen_sfc, which clearly identifies the tool's purpose. It also differentiates it from siblings by noting multi-boot should use fpga_gen_multi_file.

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

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

It explicitly sets the usage context: offline, no device, no cable, no confirm. It also provides a concrete alternative for multi-boot, so an agent can route correctly without guessing.

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 meaningful operational context: execution goes through the GUI Tcl Console via a session-1 UIAutomation driver, and the cable is opened by the GUI. However, it does not disclose whether the operation is read-only, what error conditions look like, or what happens when the GUI/cable is not ready.

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 with no redundancy. The core function and command example are front-loaded in the first sentence, and the second sentence adds the underlying mechanism and the GUI dependency. 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 tool with one required parameter and full schema coverage, the description covers what it does, the underlying mechanism, and the GUI cable dependency. But with no output schema, the return is only vaguely signaled ('回读并解析数值'), and prerequisites and failure behavior are left implicit, leaving a real but small gap.

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

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

Schema description coverage is 100%: host, user, address, and timeoutSec all have individual descriptions including format examples and defaults. The description only adds marginal value by showing how address maps into the underlying command; it contributes no meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb-object pair: read and parse on-chip ADC registers (e.g., die temperature), and names the exact underlying Tcl command it wraps (`dbg_adc_read_reg -address <addr>`). It also positions itself as a convenience wrapper over fpga_ila_console, which helps distinguish it from the raw console and capture tools in the sibling list.

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 ('便捷封装' convenience wrapper for reading ADC registers), and the relationship to fpga_ila_console is stated at the implementation level. However, there is no explicit statement of when to choose this tool over alternatives, no exclusions, and no conditions such as 'the GUI must already have the cable open before calling this.'

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does so well. It reveals fail-fast behavior for ambiguous, unverified, or optimized signals, states that validation happens before modifying the project, and exposes side effects by saying the sbit is handed to fpga_jtag_flash and the fic to fpga_jtag_capture by default. This goes beyond the schema and gives the agent a realistic model of what the tool will do.

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 dense but efficient: every sentence adds substantive information about pipeline, validation behavior, outputs, or fallback. The core pipeline is front-loaded in the first sentence. A small amount of structure, such as bullet points or clearer separation between pipeline, error behavior, and defaults, would improve readability, but there is no fluff.

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

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

For a complex tool with 9 parameters, no annotations, and no output schema, the description covers the essential behavioral contract: pipeline steps, outputs, side effects, default downstream actions, and error-handling posture. The input schema fully covers parameter details. The main gap is that the exact structure of the returned report and sbit/fic result is not described, and explicit differentiation from fpga_ila_flow is only implicit.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter-related context beyond the schema, especially for the signals parameter: multi-instance same-name ambiguity returns 'ambiguous', and unverified/optimized signals cause fail-fast before the project is modified. This helps the agent construct valid inputs, though not every parameter receives additional explanation.

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

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

The description clearly states the core function: combining ILA instrumented build into one self-correcting call, with a concrete pipeline (bypass synthesis → ins_list_nets parsing → FIC validation → generate/register .fic → gen_bit_stream). It also names concrete outputs (sbit+fic+报告), making the tool's purpose distinct from the individual-step sibling tools like fpga_ila_generate_fic and fpga_ila_list_nets.

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 clear context for when to use this tool: it is the consolidated local build path, and GUI flow is explicitly positioned as only a remote/special fallback. It also mentions default chaining to fpga_jtag_flash and fpga_jtag_capture, which helps the agent understand the tool's role in the broader flow. However, it does not explicitly name sibling alternatives such as fpga_ila_flow as the thing to use instead in other scenarios.

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 it delivers useful context: this is a non-default fallback, it depends on a completed fpga_ila_open, and it performs a concrete multi-step workflow. It does not detail potential side effects, permissions, or completion/return behavior, so I do not score it 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 dense sentences front-load the critical classification as a GUI fallback, state the preferred alternative, give the exact usage condition, and describe the workflow. No sentence 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?

For a complex tool with 10 optional parameters, nested trigger semantics, no output schema, and no annotations, the description plus rich schema is mostly sufficient: an agent knows when to use it, what it does, and what it produces. It could be stronger on success/return semantics and explicit side effects, but it is not under-specified.

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 input schema already documents all 10 parameters and the trigger object with an example. The description does not add parameter-level meaning 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?

The description states a specific purpose: it is the GUI fallback capture path that runs the dbg_fla_* sequence, exports VCD, parses groups, and generates an interactive waveform viewer. It explicitly distinguishes itself from the local default fpga_jtag_capture, so an agent can tell them apart 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?

It gives explicit when-to-use conditions: only in remote GUI scenarios or when bare-metal capture does not support the needed function. It also names the preferred alternative for ordinary local FLA, fpga_jtag_capture, and states the prerequisite that fpga_ila_open must already have completed.

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

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

With no annotations provided, the description carries the full disclosure burden and meets it thoroughly. It reveals the GUI-automation mechanism (UIAutomation on interactive session 1, zero human clicks, auto-catch so errors return to the transcript), the performance profile (1-2 minutes per simple command due to tab switching and segmented transcript reads), the local/remote execution paths, and the safety behavior for write-device commands (confirm=true plus a pre-execution read-only IDCODE match via expectIdcode). No annotation contradiction exists.

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

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

The description is a long single paragraph, but it is dense and every sentence earns its place: motivation, mechanism, local/remote variants, command scope, prerequisites, write-command safety gating, and performance warning follow in a logical order. It is front-loaded with the most decision-relevant facts (what it is, why GUI is required, safety gating) and contains no redundant filler, though light segmentation would improve scannability for an AI agent.

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

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

For a complex 6-parameter tool with no annotations and no output schema, the description covers preconditions, mechanism, scope, safety gating, error behavior (catch), and performance expectations comprehensively. The main gaps are that the return value is only implied (reads back transcript increments) rather than stated as a concrete output an agent can rely on, and failure behavior when the GUI is absent is not described. These are minor relative to the overall coverage.

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

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

Schema description coverage is 100%, so the baseline is 3; the per-parameter schema already documents tcl catch-wrapping, host/user routing for local vs. remote, confirm gating, timeoutSec defaults, and the expectIdcode read-only matching step. The description adds some meaningful context beyond the schema, mainly the concrete 1-2 minute latency estimate that explains the timeoutSec rationale, but it largely restates the schema's safety rules rather than adding new parameter-level semantics, so it does not exceed the baseline.

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

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

The description states a precise verb-resource-mechanism: it type Tcl commands into the GUI Fabric Debugger's Tcl Console via UIAutomation, running arbitrary dbg_* commands (IDCODE/ADC, dbg_fla_* capture, import fic, program). It also distinguishes itself by explaining why the headless cdt_dbg path deadlocks (open_cable) and by routing long captures to fpga_ila_capture. An agent can identify exactly what this tool does and how it differs from the ILA sibling cluster 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?

Provides explicit when-to-use context: the Fabric Debugger GUI must already be open and connected to the project on the target desktop, since the cable is held by the GUI. It gives a concrete when-not-to-use rule (long captures / slow JTAG → use fpga_ila_capture or the low-level driver), explains why the headless alternative is not viable, and documents local vs. remote host determination. This is complete routing guidance, not a vague hint.

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

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

With no annotations provided, the description carries the full disclosure burden and does substantial work: it flags the flow as dangerous ("危险动作"), mandates confirm:true before cable access/flash/capture, names the destructive stages (释放 cable, 烧录), and promises stage-by-stage reporting. It stops short of describing side effects (e.g., what cable release does to other JTAG users) and failure/rollback behavior, so not 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?

The description packs classification, usage condition, safety gate, the full stage pipeline, reporting behavior, and an exclusion into a few dense clauses, with the most decision-relevant facts (fallback status, alternatives) front-loaded. It is slightly run-on rather than enumerated, but no sentence 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?

For a high-complexity composite tool (20 params, nested objects, destructive multi-stage flow, no annotations and no output schema), the description covers the orchestration stages, the confirm gate, and periodic reporting. Remaining gaps are failure/rollback semantics and an explicit statement of final outputs (only implied via outDir's viewer/json/vcd), but the schema carries the parameter load effectively.

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 entries are already rich (capture explains n/w window modes, confirm documents the cable/flash/capture gating, expectIdcode states verification-before-flash). The description adds only marginal reinforcement of the confirm requirement and the remote-desktop host condition, so the baseline 3 applies.

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

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

The description identifies the tool as a GUI-fallback flow for ILA capture and enumerates its pipeline (push→release cable→scan+IDCODE→flash→fpga_ila_open→fpga_ila_capture→teardown), so the resource and flow are specific. It separates itself from the bare-metal fpga_jtag_flash→fpga_jtag_capture path by naming that sibling, but the purpose is defined largely by exclusion ("仅当...不支持...或必须...时采用") rather than by a crisp primary action statement, so it falls just short of 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 explicit adoption conditions (bare-metal fpga_jtag_flash→fpga_jtag_capture lacking target support, or remote interactive desktop required), names the alternative tools verbatim, and adds a clear exclusion ("普通本地 FLA 抓波不要优先走本流程"). This is textbook when-to-use/when-not-to-use guidance with named 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this well by warning about flatten renaming, requiring post-synthesis net names, and framing the tool as pure local code generation. It does not mention edge behaviors like file overwrite or validation failure, but the critical behavioral constraints are clearly 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?

The description is dense but well structured: core action, then critical caveat, then alternatives, then downstream workflow. Every sentence contributes actionable information, and there is no filler or repetition of schema content.

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

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

For a 7-parameter tool with nested objects and no output schema, the description covers the essential usage context: what input is required, why the input must be real net names, how to obtain those names, which alternative tool to prefer, and what to do after generation. Combined with the fully-described schema, an agent has enough to invoke the tool 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 is 3. The description adds meaningful semantics beyond the schema by explaining that signals and clockNet must be post-synthesis real net names, giving concrete rename examples, and directing the agent to fpga_ila_list_nets for resolution. It does not discuss busGroups or dataDepth in prose, but those are already well covered by schema descriptions.

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

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

The description names a specific action — writing device, clock net, and signal net names into a Pango .fic text file — and identifies itself as a low-level primitive. It clearly distinguishes itself from fpga_ila_build and fpga_ila_list_nets, so an agent can tell this tool apart without inspecting schemas.

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

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

The description explicitly states when to use this tool: when you already have post-synthesis real net names. It also gives clear alternatives: use fpga_ila_list_nets if names unknown, or use fpga_ila_build for automatic name resolution. It even names the downstream sequence (fpga_pds_register_fic → fpga_pds_run gen_bit_stream), which fully orients the agent.

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

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

With no annotations provided, the description carries the full burden and delivers: it discloses that the tool runs compile→run_ads inside an isolated bypass copy (side-effect containment), triggers a full synthesis (justifying timeoutSec), obtains names via ins_list_nets from the .fic, and states a key limitation — it does not guess paths from module definitions. It also reveals the output status taxonomy (exact/renamed/hierarchical/ambiguous/unverified/pruned) and the ambiguous+candidates behavior for multi-instance nets.

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

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

Three dense sentences with the core purpose front-loaded ('solves the fundamental ILA probing problem'), followed by mechanism, optional behavior, and workflow relationship. Every clause carries distinct information — problem, mechanism, limitation, statuses, and fpga_ila_build dependency — with no filler or repetition.

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

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

For a tool with no annotations and no output schema, the description is remarkably complete: it covers purpose, mechanism, side effects (isolated copy, full synthesis run), parameter nuances, return status categories, and its place in the ILA flow. An agent has enough to decide when to call it, what to pass, and what shape of result to expect.

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%, establishing a baseline of 3. The description adds meaning beyond the schema for the signals parameter by listing the full resolution status taxonomy not present in the schema, and it gives context to pdsPath/timeoutSec by explaining the isolated compile→run_ads flow. It does not add novel format details for pdsVersion or timeoutSec beyond what the schema already 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 precise verb and resource: it discovers the real, probe-able full-hierarchy scalar net names that the Fabric Inserter can consume from the .fic, explicitly distinguishing them from RTL names. It differentiates itself from siblings by declaring it does not guess paths from module definitions and by positioning fpga_ila_build as the consumer of the same authoritative list.

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 clear situational context — use it when post-synthesis flattened net names diverge from RTL names and you need the exact names the Inserter will consume — and establishes the workflow position (fpga_ila_build uses the same list for FIC fail-fast). It also gives conditional guidance for signals (unique buses auto-expand; multi-instance same-name nets require full hierarchy), but it never explicitly names an alternative tool or states when not to use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the operational workflow, the session-1 startup, popup handling, and prerequisites. It does not discuss timeouts, process leftovers, or success/failure semantics, but the GUI-launch behavior is well characterized.

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

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

Four dense sentences, each earning its place: fallback status, alternatives/conditions, workflow steps, and prerequisite. No filler, and critical context is front-loaded.

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

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

The description covers the when, what, workflow, and prerequisites for a medium-complexity GUI tool. There is no output schema, and it does not describe return values or failure indications, but the title and workflow imply success is 'DebugCore detected/ready', which is enough for an agent to proceed.

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 prerequisite emphasis on projectDir being a built FLA-containing directory, but the schema already states this and also documents host/user/pdsVersion meaning, so the description provides little extra parametric value beyond what structured fields already offer.

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 — launching and readying the Fabric Debugger via a concrete sequence (cdt_dbg → Search JTAG Chain → handle Open Cable popup → scan UIA tree for DebugCore) — and clearly labels itself as the GUI fallback, distinguishing it from the local default path. This makes the tool's function unmistakable even before reading the 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 the preferred alternatives (fpga_jtag_flash → fpga_jtag_capture) and gives exact conditions for choosing this tool instead: when bare-metal capture lacks target support or remote interactive desktop is needed. This is textbook when-to-use guidance with no ambiguity.

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

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

With no annotations provided, the description carries full behavioral burden. It discloses what each call mode returns, that category uses substring matching, that all-args-omitted produces a summary, and that every core includes a datasheet PDF path. It omits error/edge-case behavior, but for a read-only lookup this is acceptable.

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 dense sentence with semicolon-separated modes, front-loaded with scope ('~65 核') and a representative list of categories. Every clause conveys either a mode, its behavior, or its output; there is 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?

It covers slug, query, category, and the empty-args case, and describes output contents adequately. However, the schema exposes a 'mode' parameter with auto/keyword/semantic options, and the description does not explain when to choose semantic over keyword, nor what 'auto' resolves to. Without an output schema, those ambiguities remain, so completecess is slightly short.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: e.g., slug returns the core's header/params/PDF, category is a substring match, and passing no filter returns a summary list. This extra behavioral nuance is valuable and justifies the score.

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

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

The description states a specific action ('查') and a concrete resource ('PDS IP 目录'), and further distinguishes itself by enumerating output contents (header, supported devices, parameters with enum options, datasheet PDF path, summary list). This clearly separates it from sibling lookup tools like fpga_primitive_lookup or fpga_doc_search.

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 explicit usage conditions for each mode: slug for exact matching, query for keyword recall, category for substring filtering, and no-args for a summary list. This is strong operational guidance. However, it does not explicitly compare this tool to sibling tools or state when not to use it, so the cross-tool selection logic is left to inference.

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

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

With no annotations, the description carries the burden. It discloses core behaviors: physical stride probing by vendor standard, expanded reads with protocol-padding sparsity inference, ambiguity fail-closed, trigger alignment, and automatic recursive creation of export parent directories. It does not mention side effects on the FT2232 or FLA state, but gives substantial behavioral context beyond a generic 'captures' verb.

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 content is dense and front-loaded with the key default-path statement, but it is a long paragraph with many semi-colon-separated clauses. Every clause adds information, but an agent would benefit from bullet structure or shorter sentences. It is not concise, though it is information-dense.

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 15 params, no output schema, and no annotations, the description covers the workflow prerequisites, capture process, export formats, trigger alignment, and ambiguity handling. It does not specify all return fields of capture.framing (but names several), nor does it detail the exact condition/cond parameter semantics beyond a hint. Still, it is unusually complete for a complex 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 baseline is 3. The description adds meaningful semantics beyond the schema: it explains how paddingBits interacts with the automatic probing/inference and fail-closed behavior, how trig relates to ila.mjs Match-Unit prerequisites and per-channel trigger patterns, and how signals relate to .fic overrides. It ties parameters into the overall workflow.

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 ('capture'), resource ('FLA via FT2232'), and workflow position ('default local ILA capture path'), and distinguishes itself from cdt_js/GUI and sibling fpga_ila_capture. It clearly tells an agent what the tool does and how it relates to the local JTAG flow.

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 ('默认抓波路径...不走 cdt_js/GUI'), prerequisites ('通常先 fpga_jtag_flash，再调用本工具'), and configuration source ('width/depth/信号名来自设计 .fic 或显式给定'). It also gives fail-closed behavior and explicit override (paddingBits) for ambiguous cases.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the operation is volatile/reversible, takes about 15s at 6MHz, verifies done bit, performs two IDCODE checks, auto-generates/caches SVF for --sbit, and requires confirm=true as a safety gate.

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

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

The description is compact and front-loaded: the core operation and verification appear first, followed by safety preconditions, the sbit generation path, and one explicit exclusion. Every sentence carries distinct information 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 complex, dangerous tool with no annotations and no output schema, this description covers most invocation-critical context: operation, safety, preconditions, both input paths, and tool boundaries. However, it leaves the success/failure return behavior implicit, so it is not fully complete for an agent that needs to interpret results.

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 extra semantics: it clarifies the svf/sbit mutual exclusion and caching behavior, notes that tckHz up to 10e6 is safe in practice, and explains that expectIdcode comparison ignores the high 4 bits. This exceeds the schema's own descriptions, though not every parameter is discussed.

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: replay a CRAM SVF via FT2232 to configure FPGA SRAM, then verify the done bit. It differentiates from siblings by emphasizing volatile/reversible SRAM and explicitly excluding the cdt_js/GUI workflow.

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?

Clear context and preconditions are given: this is a dangerous action, confirm must be true, and a bare-metal scan should first verify expectIdcode. It also says 'not via cdt_js/GUI,' but it does not name sibling alternatives or explicitly state when to prefer this over tools like fpga_flash_sram or fpga_jtag_gen_svf, so it falls short of full 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 burden. It discloses key behavioral traits: offline operation, no cable connection, PDS bin/license auto-discovery, and the default CRAM property value (0x40C4E). However, it doesn't disclose what happens on failure, whether the SVF is overwritten, or the detailed behavior of timeoutSec. The core offline-vs-online behavior is clear, which is the most important trait here.

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

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

The description is a compact paragraph that front-loads the core transformation (offline .sbit→CRAM SVF) and then adds the key qualifier (offline, no cable) and the reuse note. The auto-discovery sentence is useful but slightly dense; still, 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 conversion tool with no output schema, the description explains the input (.sbit), output (SVF path default), toolchain (cdt_cfg), offline nature, and environment discovery. It lacks details about return values or error semantics, but the parameter schema covers paths and defaults well. Given the absence of annotations and output schema, this is reasonably complete but could add a note about typical failure modes or output artifacts.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds value by explaining that pdsBin and license are auto-discovered from pango-mcp config/environment, and by revealing the default SVF naming convention (<sbit>_cram.svf). It also explains the purpose of the property default (CRAM+check-done+1MHz), which goes beyond the schema's terse '-svf_property'.

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 (转换/将...转成), a precise resource (.sbit → CRAM SVF), and the underlying mechanism (cdt_cfg cfg_one_step_create_svf). It explicitly distinguishes itself as offline (离线、不连 cable) and notes its reuse by fpga_jtag_flash, making it clear how it differs from sibling JTAG 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 explicitly says this tool is offline and does not connect a cable, and that it is intended for reuse by fpga_jtag_flash. This gives clear context for when to use it, though it doesn't explicitly name alternatives or state when not to use other JTAG tools beyond the offline/online distinction.

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 important behavior: direct hardware read, read-only and device-safe, no license needed, and cable mutual exclusion. It could add what happens on conflict or what output is returned, but the stated traits cover the main safety and operational concerns.

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 clauses with no filler: mechanism, licensing/read-only status, and the one critical caveat. High-value information is front-loaded and 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 read-only probe with three optional and fully documented parameters, the description covers selection, safety, and the key operational constraint. It falls slightly short only by not specifying the exact output/return format, since no output schema exists.

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

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

Schema coverage is 100%, and each parameter already has a meaningful description including defaults and channel probing behavior. The tool description adds no parameter-level information, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: reads IDCODE directly via FT2232, explicitly distinguishing itself from fpga_pds_scan and the cdt_js/PDS path. The scope is clear enough that an agent can separate it from sibling JTAG tools without opening schemas.

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

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

It gives concrete selection criteria: no license required, no dependency on cdt_js/PDS, read-only, and mutually exclusive with fpga_pds_scan on the cable. It also instructs the agent to stop cdt_js first, which is actionable guidance beyond 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 provided, the description carries the behavioral burden. It discloses the operation is a cheap, token-saving extraction, and details the information categories produced for each profile. It does not describe the output format or error behavior, but for a read-only extraction tool the description covers the main behavioral expectations.

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 action and object come first, followed by the profile details and a purpose note. Every clause contributes to understanding what the tool does and why to use it.

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

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

The tool is simple (3 optional params, no nested objects) and the schema already documents all parameters, so the description does not need to repeat schema details. The only notable omission is the output representation, but the per-profile content list gives the agent enough expectation for this utility.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by mapping each profile enum value to concrete extracted fields (pds: error codes/stages/timing/resources/known issues; cdt: IDCODE/done bit/verify; sim: failure markers), and it hints at the log/logPath duality by mentioning both log text and log file.

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

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

The description uses a specific verb ('抽取'/'extract') and resource (日志/log), and enumerates the per-profile extracted content (pds, cdt, sim), making its function clear. It does not explicitly name sibling tools or contrast against them, but its role as a log post-processing utility is distinct enough among the FPGA workflow siblings.

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

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

The phrase '用于对落盘日志二次廉价提取' explicitly establishes when to use the tool: for secondary, low-cost extraction from on-disk logs. It does not state when-not-to-use or name alternatives, but the context is clear and no exclusion is needed for this simple utility.

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 and does well: it reveals that success is determined by 'Errors: N' and '** Error' rather than the exit code, that encrypted IEEE-1735 IP is natively decrypted by vlog, and that caching affects recompilation. This materially helps an agent predict tool behavior beyond what the schema states.

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 four short, dense sentences with the core scope front-loaded, followed by behavioral caveats. There is no filler, and every sentence adds useful operational 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 an 11-parameter tool with no output schema, the description covers the essential operational context: compile-only scope, language-to-tool mapping, success criteria, encrypted IP, cache, and detail modes. It does not describe the exact output structure or explicitly route to simulation alternatives, but those are modest gaps given the rich parameter schema.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail. The description mentions cache, detail:'full', and encrypted sources, but these largely restate schema content rather than adding new parameter-level meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource: '只编译' (compile only), maps Verilog/SV to vlog and VHDL to vcom, and specifies the purpose as syntax/early checks. It also distinguishes itself from a simulation run by explicitly saying '不运行 vsim', which separates it from sibling fpga_msim_sim.

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 clearly frames when to use the tool: compile-only before simulation, for syntax/early checking, with encrypted-IP handling and cache behavior. It does not explicitly name a sibling alternative or state 'use fpga_msim_sim instead', so it stops short of full 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. It clearly discloses forced headless mode, automatic quit -f to prevent hangs, the confirm guard for host-reaching commands, remote staging behavior, and the top-vs-script-driven vsim modes. This is strong transparency for an arbitrary-script execution tool.

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

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

The description is dense but purposeful, front-loading the purpose and then grouping execution safety and invocation modes. Parentheticals make it a bit packed, but every clause contributes.

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 10 parameters, no output schema, and many siblings, the description covers core invocation modes, safety, and remote behavior well. It could go further on return granularity and failure behavior, but it is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds operational meaning for confirm, the top/lib relationship, remote host staging, and vsimArgs examples. It does not define summary vs full, but that is minor given the rich 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 action: run arbitrary do/Tcl scripts through vsim -c, with concrete examples of covered use cases. The '通用/长尾' framing distinguishes it from more specialized sibling 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?

Gives clear context for when to use the tool: long-tail do/Tcl workflows covering coverage, UVM, WLF, force/examine, and custom run control. It also specifies when confirm:true is required. It does not explicitly name sibling alternatives like fpga_msim_sim or fpga_msim_compile, but the niche is clear.

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 substantial work: it states 'pure keyword, zero extra cost' (no side effects/cheap), explains that PDFs return paths for the host to Read directly, and defines the distinct output shapes for command, query, and no-query calls. It does not discuss failure/empty-result behavior, but for a read-only search tool the disclosed traits are strong.

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

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

Two dense sentences with zero filler. The core function is front-loaded, parameter behaviors are compressed into one sentence, and the final clause about full syntax via fpga_msim_exe is a self-contained routing note. Every phrase 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 4-parameter search tool with no output schema and no annotations, the description covers purpose, data sources, per-mode outputs, cost, and the sibling tool for full syntax. Minor gaps remain around the exact JSON shape of result lists and error cases, but nothing an agent needs to choose and invoke the 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, but the description adds interaction semantics the schema lacks: command returns description+arguments, query triggers keyword recall, kind scopes the search, limit applies to query results, and omitting query returns a summary. This is meaningfully beyond the parameter names and examples in 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 opens with a specific verb and resource: it searches the ModelSim command reference (structured corpus from docs/cmd_help/*.txt) plus the manual PDF registry (docs/pdfdocs/*.pdf). This clearly distinguishes it from siblings like fpga_msim_exe (execution), fpga_msim_sim (simulation), and fpga_doc_search (general docs).

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 maps each invocation mode to its outcome (command=exact lookup, query=keyword recall, kind=all/command/manual, no-query=summary), and explicitly routes the need for full command syntax to the sibling tool fpga_msim_exe <tool> -help. This is explicit when-to-use and when-to-use-alternative 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 present, so the description carries the behavioral burden. It does disclose that output is extracted and that any bin exe can be probed with -help/-version, and the title hints at guardrails. However, it does not explain side effects (e.g., vlib/vmap may mutate libraries, vcover may write coverage data) or what '受护栏' actually enforces, leaving meaningful behavioral ambiguity for an execution 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 dense, front-loaded sentences with concrete exe examples and an explicit exclusion. Every sentence adds value and there is 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 passthrough execution tool, the description covers scope, exclusions, probing strategy, and output extraction. With no output schema, it could more explicitly describe the returned structure beyond '提取后的输出', but the detail enum (summary/full) partially addresses granularity.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds useful examples and probing guidance but does not need to compensate for parameter gaps; 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: run utility exes (vlib/vmap/vdir/vcover/wlf2vcd/etc.) in the ModelSim bin directory and return extracted output. The description explicitly distinguishes this from compile/sim tools by naming fpga_msim_compile/sim/do as dedicated alternatives, so an agent can tell it apart from siblings.

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

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

Gives explicit when-to-use guidance: library/coverage/waveform/tool exes belong here, while vlog/vcom/vsim do not and have dedicated tools. It also mentions probing any exe with -help/-version, which is actionable context for exploring unknown utilities.

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 it well: it warns that exit codes are unreliable and that parsing transcript ** Error/Fatal and 'Errors: N' is the authoritative pass/fail signal, including the surprising $fatal-exits-0 case. It also discloses headless execution, VCD generation behavior, structured coverage returns, and input-hash caching—valuable non-obvious behavioral context.

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

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

The description is compact and front-loaded with the core compile-and-run action, then adds the most decision-relevant quirks (unreliable exit codes, VCD/coverage, caching, VHDL differentiator). Every sentence contributes non-obvious value and does not waste tokens repeating schema content.

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

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

For a 24-parameter tool with no output schema, the description covers the critical execution model, pass/fail determination, cache, VCD/coverage capabilities, and VHDL positioning. However, it does not describe the default summary output structure or the full set of returned artifacts, leaving some ambiguity about what the agent should expect in the response beyond the schema-covered param details.

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

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

Schema description coverage is 100%, so the schema already documents all 24 parameters in detail; the tool description adds little parameter-level meaning beyond reinforcing cross-cutting behaviors like detail:'full' and input-hash caching. This meets the baseline but does not meaningfully elevate parameter understanding beyond the rich 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 action—headless ModelSim compile (vlog/vcom) and run (vsim -c -do)—with a clear resource (a design including testbench). It also distinguishes the tool from fpga_sim(iverilog) by calling VHDL support the incremental capability, helping an agent tell it apart from a closely related sibling.

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 clear usage context: it names fpga_sim(iverilog) as the alternative and notes that VHDL support is the differentiator, implying this tool is preferred for VHDL or ModelSim-specific flows. It also mentions VCD output as usable by fpga_assert, giving a downstream integration hint. However, it does not explicitly state when not to use this tool versus the other fpga_msim_* 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?

With no annotations provided, the description carries the full burden and delivers: the GUI process runs detached from MCP with immediate return, VCD is auto-converted via vcd2wlf to WLF, omitted signals default to add wave -r /*, omitted groups auto-group by VCD hierarchy scope, and launch:false only converts and returns a command. This is rich behavioral context far beyond what the schema alone provides.

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 dense, not bloated, and front-loaded with the core purpose followed by behavioral specifics. Every sentence earns its place; the sibling-routing and launch:false notes are placed at the end where they serve as clarifications rather than competing with the main 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?

For a 7-parameter tool with no annotations and no output schema, the description covers purpose, inputs, defaults, runtime behavior, local/remote nuance, and sibling routing. Minor gaps remain: the return value in default launch:true mode is not described, and behavior when both vcdPath and wlfPath are supplied (schema says '二选一' but no validation behavior is stated) is 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%, setting a baseline of 3. The description adds value above the schema by explaining the signals default behavior (add wave -r /*), the launch:false semantics (convert-only, no GUI), and the VCD→WLF pipeline that links vcdPath and wlfPath. It doesn't elaborate on radix or timeoutSec, but the schema already documents those fully.

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 (open ModelSim GUI to view waveforms interactively with zoom/measure/hierarchy expansion) and explicitly differentiates from the sibling fpga_wave, which serves static images/browser viewing. An agent can tell exactly what this tool does and what it does not do.

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 explicitly names the alternative (fpga_wave for static images/browser) and the condition that selects it, states the local-path context (VCD already pulled back locally), and clarifies that launch:false is for scripting/testing. No ambiguity about when to invoke this tool remains.

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

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

With no annotations provided, the description carries the behavioral burden and covers important traits: pre-launch safety validation, the 2-way concurrency cap with a memory rationale, and the failure semantics (top-level ok=false while preserving per-variant results). It is transparent, though it does not enumerate all side effects (e.g., backup behavior) that the schema mentions in parameter descriptions.

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

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

The description is compact and front-loaded: action first, then safety gates, concurrency limit, and failure behavior. Every sentence carries distinct high-value information 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 batch tool with rich schema but no output schema and no annotations, the description covers the essential operational context: prerequisites, validation rules, concurrency constraints, and result/failure semantics. That is sufficient for an agent to select and invoke the tool 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 is 3, but the description adds meaning beyond the schema by explaining valid variant structure: pdsPath directories must be unique and non-nested, shared prj_tasks cause rejection, and P&R memory intensity motivates maxParallel=2. These invariants help the agent construct valid inputs.

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: run multiple prepared independent PDS project clones in parallel and summarize timing/errors/artifacts per variant. This clearly distinguishes it from single-run siblings like fpga_pds_run and fpga_pds_compile via the batch/multiple-clone 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?

The description gives clear usage context: use when there are multiple independent, pre-prepared PDS clones, and it specifies preconditions such as unique non-nested pdsPath directories and no shared prj_tasks. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden, and it delivers: it discloses the full-pipeline execution, the .sbit output, compact summary format, detail/cache handling, and the effsoftecrypt self-check. It defers remaining behavior to fpga_pds_run, which is an acceptable pattern only if that sibling is equally well documented; side effects like build-directory handling are left to 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?

Two sentences with the identity statement front-loaded before behavioral details; no filler. The parenthetical enumeration is dense, but each item (compact summary, detail/cache, effsoftecrypt self-check) 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 build wrapper with no output schema and no annotations, the description covers the critical questions: tool identity, preset target, expected artifact, and inherited behaviors. Its main gap is relying on fpga_pds_run's description for the rest — an agent without access to that sibling would miss return-value and artifact-location details.

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 semantic value: it frames runTarget as deliberately locked to a preset rather than merely defaulted, and links that parameter to the .sbit outcome. This tells an agent that overriding runTarget would defeat the tool's purpose — meaning beyond the schema's plain default-value note.

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: it is the bitstream-output preset of fpga_pds_run that runs the full PDS flow and produces a .sbit artifact. It distinguishes itself from its parent sibling immediately by pinning the one differing aspect (default runTarget=gen_bit_stream).

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

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

Names fpga_pds_run as the parent and frames this tool as the preset that fixes runTarget=gen_bit_stream, so an agent can infer when to pick it over fpga_pds_run (want the default bitstream flow) and when not to (need a different run target). The guidance is clear but implicit; it never spells out an explicit when-not-to-use condition.

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

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

With no annotations provided, the description carries the full disclosure burden. It usefully discloses the side-effect scope (generates RTL/FDC/.pds) and, importantly, that the tool refuses to guess device parameters ('工具不内置默认', '工具不替你猜'). However, it does not disclose overwrite behavior for an existing project directory (only hinted at by the force parameter) or whether the tool invokes PDS tooling beyond file generation.

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

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

Two dense sentences with zero filler: the first front-loads the action and deliverables, the second delivers the critical invocation constraint. Every clause earns its place, and the most decision-relevant fact (no built-in device defaults) is placed prominently.

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

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

The schema's deep 100% parameter coverage (directory creation, force deletion, timing implications) compensates for most parametric gaps, and the description covers purpose plus the key no-defaults constraint. But with no output schema and no annotations, the agent is left uncertain about the success return value, whether the PDS flow is actually executed, and error behavior when required device info is absent — notable gaps for a 14-parameter mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters with rich detail (e.g., clkFreqMhz's effect on create_clock and timing.met, projectDir's auto-create behavior, package mismatch leading to build failure). The description adds only the meta-rule that the four device parameters must be supplied as a complete set from user/Target Profile, which marginally reinforces but does not go 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?

The description states a specific verb and resource: '创建面向真实板卡的 LED blink PDS 工程' and enumerates the concrete deliverables (RTL、FDC 和 .pds). The '真实板卡' (real board) qualifier plus the LED-blink scope clearly differentiate it from the generic sibling fpga_pds_create_project, while the device-agnostic note ('工具不内置默认') sets it apart from flows that assume device defaults.

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

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

The description implies the usage context — it is for real-board LED blink project creation and explicitly preconditions that complete family/device/speedgrade/package must come from the user or Target Profile. However, it never names alternatives or states when-not-to-use; with ~45 siblings including fpga_pds_create_project, the agent must infer the boundary between generic project creation and blink-specific creation rather than being told.

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. It discloses that the tool does not guess device/family/package/speedgrade, that board provides pins and generates FDC, and that force deletes/recreates directories. It doesn't explicitly mention side effects beyond force, but the key behavioral traits (no guessing, error behavior, FDC generation) are transparent.

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

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

The description is compact and information-dense, with the core purpose front-loaded. The parenthetical about board recommendation is slightly dense but earns its place by conveying the key usage decision. No wasted words, but the structure could be slightly cleaner with explicit separation of the two invocation modes.

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 tool with no output schema, the description covers the essential decision logic (board vs explicit fields), the error behavior, and the force semantics. It doesn't describe the generated project structure or what the return value looks like, but given the complexity and the rich schema, this is adequately complete for an agent to invoke 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 schema already documents all parameters. The description adds meaningful semantics: it explains the relationship between board and the four device fields, clarifies that pinNames is a subset of the design's actual top ports, and specifies that physical loc/freq/iostd all come from the profile. This is value beyond the schema.

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

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

The description clearly states the tool creates a minimal .pds project for pds_shell compilation, names the specific resources (RTL/constraints/.pds), and explicitly contrasts it with board-physical information. It distinguishes itself from siblings like fpga_pds_create_blink_project by emphasizing 'minimal' project creation and the board/profile mechanism.

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 explicitly recommends passing board:<name> and explains the alternative of providing all four fields, including what happens if fields are missing ('缺则报错点名所缺'). It also references fpga_env for listing configured boards, giving clear when-to-use vs alternative 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?

There are no annotations, so the description carries the full behavioral burden. It discloses that the tool mutates the .pds file, automatically backs up the original with `.bak_<ts>`, and supports both PDS 2025.2 XML and older sexpr forms. This is substantial useful behavior beyond a bare 'register fic' statement.

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

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

The entire description is one dense, front-loaded sentence: it states the action, the effect on the next run, the backup behavior, and format compatibility. No filler or redundant wording appears.

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 tool with no annotations and no output schema, this description is complete: it explains the input relationship, the target widget, the downstream consequence, the safety backup, and supported file formats. An agent has enough 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?

The schema already covers both parameters fully with descriptions of absolute paths and the automatic relative-path conversion for ficPath. The description reinforces the .fic/.pds relationship but adds little parameter-level detail beyond what the schema provides, 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?

The description states a specific action: writing an already-generated .fic file into the .pds project's Fabric-Inserter widget, and even names the exact widget markers (`<action name='fic'>`/`wgt_my_fic_src`). It clearly differs from sibling tools like fpga_ila_generate_fic by emphasizing that the .fic is already generated.

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 clear workflow context: use it after generating a .fic and before running `fpga_pds_run gen_bit_stream`, so the inserter path is taken. It does not explicitly say when not to use it or name an alternative tool, but the intended timing is well 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?

No annotations are provided, so the description carries the full burden. It does disclose the important behavior that PDS is not executed, which is valuable for a report-parsing tool. However, it does not mention other behavioral aspects such as whether it only reads files, requires existing build outputs, or has side effects like writing extracted artifacts.

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 one short, front-loaded sentence that conveys scope and the key exclusion. There is no filler or redundancy.

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

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

The description is enough for basic selection and understanding of purpose, especially with the non-execution caveat. However, with no output schema and no annotations, it omits the return format and does not clarify how the five optional parameters should be combined to produce a parse, leaving the agent with some ambiguity about invocation expectations.

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 all five parameters already documented in the input schema. The description does not add parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource set: 解析 (parse) PDS build logs, timing, resource, and bitstream output. It also adds an explicit negative boundary, '不运行 PDS', which clearly distinguishes it from sibling execution tools like fpga_pds_run.

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

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

The description implies the tool should be used to inspect PDS outputs rather than to launch builds, and explicitly warns it does not run PDS. However, it does not name alternatives or state conditions like 'use this when you already have build artifacts and need parsed reports.' The usage context is clear but not fully developed.

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 covers the important behaviors: the exact command shape, the instruction not to trust exit codes, parsing of the E:/bitstream success line plus effsoftecrypt self-check, default compact summary, detail fallback, and input-hash caching. This gives an agent a reliable model of what happens when invoked.

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 dense but every clause contributes: command, target list, naming caveat, success detection, output default, and caching. It is front-loaded with the core invocation and wastes no words.

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

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

There is no output schema and no annotations, but the description explains success detection and the summary/full return granularity, so an agent knows what to expect. It could be more explicit about the shape of the compact summary and side effects like output-dir backup, but the core calling context is 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 100%, so the baseline is 3, but the description adds value by enumerating the valid runTarget values and explicitly correcting the dev_map/pnr naming (not device_map/place_route). It also clarifies the cache and detail behaviors, going beyond the plain schema entries.

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 ('run any flow stage via pds_shell.exe -project ... -run ...') and enumerates the accepted targets, making the resource and scope explicit. The title and target list distinguish it from sibling compile/report/batch tools even without naming 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?

It provides clear context by stating that any -run target can be invoked and specifically notes that early targets such as dev_map can produce resource utilization without running P&R. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly states this is a read-only action, which is important safety information, and it discloses the side-effecting mechanism of starting/reusing cdt_js. It does not describe process cleanup or authentication, but the read-only and operational behavior is clearly conveyed.

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 compact sentences with no filler. The action is front-loaded, the read-only nature is stated early, and the local/remote distinction is summarized efficiently.

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

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

For a read-only tool with 7 optional parameters, the schema fully explains the parameters and the description covers operational context, including default behavior and remote execution. There is no output schema, but the phrase '读取 IDCODE' makes the expected return content clear. Missing details like error/retry behavior are partially covered by parameter descriptions.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds some value by explaining the host parameter's local/remote semantics and the execution-device layer concept, but it does not add significant meaning for the other parameters beyond what the schema 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?

The description names a specific verb and resource: start/reuse cdt_js and use cdt_cfg to scan the JTAG chain and read IDCODEs. It also states the scope (local vs remote via host). It does not explicitly differentiate from the sibling fpga_jtag_scan, so it misses full sibling 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?

The description provides clear usage context: default is local, and passing host executes on a remote device through the execution-device layer. However, it gives no guidance about when to prefer this tool over a sibling like fpga_jtag_scan, and it does not mention exclusions or when not to use 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 transparency burden and meets it by disclosing output content per mode: ports/parameters/instantiation template, category list, keyword recall, and summary. It signals structured output; minor gaps are unspecified precedence if multiple selectors are combined.

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

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

The description is compact, front-loaded with the resource and modes, and uses semicolon separators so the mapping is immediately parseable. No repeated or redundant phrasing appears; even '结构化、省 token' adds useful output-format and efficiency context.

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 5-parameter, no-output-schema, no-annotation lookup, the description covers the main behaviors, all category values, and the no-argument fallback; the schema covers parameter-level details. It is complete enough for correct invocation, though combination precedence such as name+query is not spelled out.

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 description adds real meaning: it specifies what name returns, enumerates the full category list, and defines the no-argument fallback. It does not restate the mode parameter, which is already documented in 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 opens with the specific action '查 Logos2 原语库' and pins the resource to gtp_lib.v and 153 GTP_* primitives. It clearly distinguishes itself from sibling tools like fpga_ip_lookup or fpga_doc_search by scoping to primitive-level port/parameter/template lookup.

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

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

The description gives explicit guidance per invocation style: name for exact lookup, category for class listing, query for keyword recall, and no args for category summary. It does not explicitly contrast with sibling tools, but the narrow resource scope and mode-specific conditions provide clear context.

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

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

With no annotations supplied, the description carries the behavioral burden; it does state the main action (parsing .pds) and an unexpected behavioral detail (bracket balance check). However, it does not disclose whether the operation is strictly read-only, what happens on invalid or missing project files, or how errors surface.

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 one concise sentence that front-loads the action and then lists return payloads in order. No filler or repetition of the tool name.

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

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

For a single-parameter tool with no output schema, the description reasonably enumerates all returned information categories. It could be more explicit about the structure or representation of the bracket-balance result and error behavior, but the essential call 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%, and the only parameter, pdsPath, is already described as the absolute path of the .pds project file. The description reinforces that this is a project file path but adds no new format, encoding, or edge-case 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 names a clear verb ('解析' / parse) and resource ('.pds' project file) and enumerates exact outputs: target device, top-level source, source list, constraints, and bracket balance check. It does not explicitly contrast with siblings like fpga_pds_scan or fpga_pds_reports, so it falls just short of full differentiation.

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 choose this tool versus sibling PDS tools such as fpga_pds_scan, fpga_pds_run, or fpga_pds_compile. An agent must infer from the name and return fields that this is an inspection/parse step, with no stated exclusions or 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?

No annotations exist, so the description carries the full behavioral burden, and it delivers: read-only by default, termination only with confirm:true plus secondary identity verification, anti-race minAgeSec behavior, and a hard guarantee never to kill client-held instances across tasks. This is a model disclosure of a danger profile for a process-killing 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?

Three dense sentences with the audit scope front-loaded, then orphan criteria, then the guarded destructive path and the safety guarantee. Every sentence earns its place; 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 tool with no annotations and no output schema, it thoroughly covers the safety-relevant contract: what is audited, what qualifies as an orphan, when termination happens, and when it never will. Minor gaps: the audit's return format is not described and the 'secondary identity verification' mechanism is left unexplained, but neither blocks safe invocation.

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

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

Schema description coverage is 100% and each of the three params (pids whitelist, confirm gate, minAgeSec race guard) is already well documented in the schema. The description reinforces the confirm default and the orphan criterion that pids depends on, but adds little meaning 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?

The description names a specific verb and resource — auditing local pango-mcp stdio servers (PID, parent process, age, private memory) and conditionally cleaning orphans. The orphan_candidate criterion is precisely defined (parent gone or parent PID reused), and none of the 45 FPGA-focused siblings perform process or orphan management, so the tool 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?

Clearly states when the destructive path applies — only orphan_candidates with confirm:true after secondary identity verification — and when it does not (instances still held by clients are never force-killed). It doesn't name an alternative tool because no sibling performs this function, but it gives strong contextual guidance on the read-only default versus cleanup mode.

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 and parameter schema carry the full burden. They disclose the core workflow (compile + run, return logs, ok verdict), default source selection excluding ._fpga_* files, log truncation behavior via the detail parameter, VCD generation, waveform rendering, and optional browser opening. This is more than a bare description, though it could still mention file side-effects or exact return shape.

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 main description is a single concise sentence that front-loads the toolchain and essential action, with the optional VCD behavior attached without extra fluff. Every word carries meaning; no redundancy beyond an acceptable restatement of the title.

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

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

For a 10-parameter tool with no output schema and no annotations, the definition covers the essential invocation surface: required workdir/top, source selection, VCD options, wave rendering artifacts, timeout, and log granularity. It explains return essentials (logs + ok) and the main artifacts, sufficient for an agent to invoke and interpret results, although a more explicit return structure would push it to 5.

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 main description adds only a general note about optional VCD wrapper injection, which loosely maps to vcd/vcdPath, but it does not meaningfully go beyond the already detailed parameter descriptions for wave, detail, sources, etc.

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: uses iverilog to compile and vvp to run a Verilog/SystemVerilog design with testbench, returning logs and an ok determination. The title's 'iverilog+vvp' and the description's optional VCD injection clearly distinguish it from ModelSim-based siblings like fpga_msim_sim.

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 identifies the toolchain (iverilog/vvp) and the optional VCD injection, giving an agent clear context about what this tool is for. However, it never explicitly states when to prefer this over fpga_msim_sim or other simulation tools; the only alternative mentioned is fpga_wave, and that appears only indirectly in the wave parameter description ('免再调 fpga_wave'), not as main usage 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?

无注解，描述承担了行为披露责任。它明确披露读资产会写 trace、recall 只读且不自动改状态、candidate 的写入来源，这些是关键的副作用与约束；但未展开权限要求、validate 是否会写等细节。

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?

三句话包含了动作、副作用、只读边界和写入来源，信息密度高；但以分号连接成整段，结构略显紧凑，尚未达到 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?

在 10 参数、无输出 schema、无注解的情况下，描述仍覆盖了选择与调用必需的关键差异：get 写 asset_use、recall 只读扫描、candidate 写入约束。返回格式未说明，但有 action 枚举和 schema 补足基本信息。

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

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

输入 schema 对 10 个参数 100% 覆盖，且 action 各枚举的中文语义在 schema 中已给出，描述基本是复述而非新增参数级信息，因此维持 schema 高覆盖时的基线 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?

描述以“检索/读取/校验”三个具体动词指向 knowledge-vault 资源，并明确 get/recall 的行为差异，资源与动作都清晰，足以与 fpga_doc_search 等兄弟工具区分。

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?

说明 get 会记录 asset_use、recall 只读扫描 trace 且不自动改 tier/status，并限定 candidate 仅由 fpga_assert 或 fpga_ila_flow 的客观绿结果写入。使用场景和边界清楚，但没有系统性地说明何时不使用本工具或选择其他兄弟工具。

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 that the tool writes .wave.svg and .wave.html files, returns paths, optionally embeds a full SVG via inlineSvg, and can open a browser with open:true. It also notes truncation behavior for maxSignals. Minor gaps remain, such as overwrite behavior, but the disclosed side effects are substantial.

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

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

Four dense sentences cover purpose, outputs, two boolean behaviors, parameter control, and the sibling alternative, all without redundant filler. The core function is front-loaded, and every clause contributes 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?

Given six parameters and no output schema, the description explains the key return artifacts and option behaviors well. It covers all major invocation decisions and the interactive fallback. It stops short of perfect completeness by not describing failure modes or exact return path structure, but it is strong 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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying defaults and behavioral effects: inlineSvg default true returns an embeddable SVG, open launches the browser, signals selects signals, and maxSignals defaults to 40 with truncation.

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

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

The description clearly states a specific verb and resource: '把 VCD...渲染成数字时序图' and names the concrete output artifacts (.wave.svg + .wave.html). It also distinguishes itself from the interactive sibling fpga_msim_view by framing itself as the static rendering 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?

The description explicitly tells the agent when to use this tool vs. the alternative: '需要交互式深查/缩放用 fpga_msim_view 打开 ModelSim GUI'. It also identifies valid input sources (fpga_sim/iverilog or fpga_msim_sim/ModelSim artifacts.vcd), giving clear context for invocation.

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