import_netlist

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description justifies the write by disclosing that 'the result is stored on the session', which explains the mutation and how to retrieve it. It also notes the optional pin-capability DB enables physical pin resolution, adding context beyond the annotations, though it does not discuss failure behavior or idempotency.

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 tightly packed sentences with zero filler; the core purpose and output shape come first, then input options, then the read-view pointer. Every sentence carries information.

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

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

With no output schema, the description compensates by enumerating the return structure (MCU part/family/line, pin map, power nets) and pointing to describe_board for views, and it covers the session-storage side effect. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value: it frames path/text as mutually exclusive inputs and explains that db_path (or the STM32_GDB_MCP_PIN_DB env var) triggers physical pin resolution with AF corroboration — behavior the schema does not spell out.

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

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

States a specific verb (parse) and resource (schematic netlist, KiCad .net) and precisely characterizes the output (BoardDescription: MCU part/family/line, per-pin map, power/ground nets). It is clearly distinguishable from siblings like describe_board, which it names as the read-side counterpart.

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

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

Explicitly frames the tool as 'the input contract for automated framework design', tells the agent it may pass either 'path' or 'text', and routes it to describe_board for reading results. It lacks explicit when-not conditions or alternatives for other import paths (e.g., import_spec), 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.