eda_pcb_document_get_primitive_at_point

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

No annotations are present, so the description carries the full burden. It usefully discloses the click-like hit-test behavior and the undefined-return semantics when no primitive exists at the point, which goes beyond the bare name. However, it omits important behavioral context for correct PCB hit-testing: which coordinate system/units the x:y arguments use (data vs canvas origin — relevant given siblings like convert_data_origin_to_canvas_origin exist) and whether the search respects current layer or filter visibility.

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 signature, then the purpose, remarks, and returns. It earns its place, but there is redundancy: the remarks line '获取指定坐标点上的图元' repeats essentially the same content as the primary sentence, adding little new 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 low-complexity single-primitive retrieval tool, the description covers the return value adequately through the signature and the returns note. The main gap is the missing coordinate system/unit specification for x and y, which is material for a PCB document tool given that origin conversion utilities exist among siblings. No output schema exists, so the description stands alone on return-value explanation, which it handles acceptably.

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 args array and windowId are already documented in the schema, which keeps the baseline at 3. The description adds marginal value by spelling out the x: number and y: number signature, but it does not clarify the coordinate units or origin frame, which is precisely the semantic detail an agent would need 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 clear verb and resource: '获取坐标点的图元' (get the primitive at a coordinate point), backed by the method signature pcb_Document.getPrimitiveAtPoint(x, y). The remarks clarify it behaves like a frontend mouse click, reinforcing the single-slot hit-test semantics. It is reasonably distinct from the sibling eda_pcb_document_get_primitives_in_region by the 'at point' phrasing, though it does not explicitly call out that 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 remark '本操作和前端鼠标点击操作类似' gives implied usage context — the agent can infer this is a single-objet hit-test on a coordinate, similar to clicking. However, there is no explicit guidance on when to use this tool versus the region-based sibling get_primitives_in_region or the schematic counterpart eda_sch_document_get_primitive_at_point, and no stated exclusions or prerequisites.

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