eda_pcb_primitive_region_create

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 only mentions the return type 'Promise<IPCB_PrimitiveRegion | undefined>' and 'returns: 区域图元对象', without stating side effects (e.g., document mutation), failure conditions, prerequisites like an active PCB document, or behavior on invalid input. For a creation/write tool, this is a significant gap.

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

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

The description is compact and front-loaded with the technical signature, followed by a short Chinese description and return note. It contains no fluff and is efficient, though a natural-language explanation could improve readability.

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 six parameters and no output schema, the description is incomplete. It omits critical context such as how to construct a complexPolygon (likely via sibling math tools), whether a PCB document must be active, and what causes undefined to be returned. An agent would need to inspect related tools or documentation to use this 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 only describes 'args' as an ordered JSON array, while the description expands this by listing concrete parameters (layer, complexPolygon, ruleType?, regionName?, lineWidth?, primitiveLock?) with types and optionality. This adds meaning beyond the schema, though it does not explain the semantics of each parameter (e.g., what values layer accepts).

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 PCB region, both via the English signature 'pcb_PrimitiveRegion.create' and the Chinese '创建区域' (create region). It distinguishes from sibling tools by specifying the primitive type 'region' and aligns with the tool name 'eda_pcb_primitive_region_create'.

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?

No guidance is provided on when to use this tool versus alternatives such as region_modify, region_delete, or other primitive creation tools. The description only gives the function signature and a brief return note, without any context, prerequisites, or exclusions.

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