proj_get_nets

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

No annotations exist, so the description carries the full burden and does so: it discloses that each call compiles the project (~700 ms), that force_recompile saves dirty docs, invalidates the SmartCompile cache and costs an extra 5-10 s compile, and it explains limit_hit/skipped_nil semantics. These are exactly the cost and side-effect facts an agent needs before choosing a call pattern.

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 critical bulk-query warning is front-loaded in caps before the mechanical Args section, which is the right ordering. There is some redundancy: a Returns block restates what the output schema already carries, though it earns part of its space by explaining limit_hit and skipped_nil. Slightly long, but nothing is purely 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 5-parameter, zero-annotation tool this covers everything needed: cost model, cache/dirty-document behavior, freshness escalation path, parameter defaults, result truncation signals, and a worked usage example. With an output schema present, the description does not need to enumerate return fields exhaustively and does not try to.

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

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

Schema description coverage is 0%, so the description must compensate and it does: all five parameters are documented in an Args block with the meaning of empty string (Empty = all), the default and purpose of limit ('Raise for big boards'), the fallback behavior of project_path (uses active), and a detailed use case for force_recompile. This adds substantial meaning the bare schema titles do not convey.

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

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

States a specific verb and resource: 'Get net-to-pin connectivity from the compiled project netlist', plus a concrete output ('pin-level net assignments'). It implicitly separates itself from PCB-side siblings like pcb_get_nets by scoping to the compiled project netlist, but never names an alternative tool, so the differentiation is inferential rather than explicit.

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

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

Explicitly says when to use it (bulk connectivity for more than one component/net), when not to (do NOT loop this tool per-component), and what to do instead (one unfiltered call with raised limit, then slice locally). It also names the exact companion tool for freshness checking ('Pair with proj_get_compile_freshness') and the trigger condition (after user edited schematics in the UI).

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