ILA: 在 Fabric Debugger 的 Tcl Console 里执行 tcl(AI 调试控制台)

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.