nx_linear_pattern

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

With no annotations present, the description carries the full burden and does real work: it clarifies that count is inclusive of the original, that spacing is a per-instance delta in mm, and that the original body is retained while new instances are separate, non-united bodies. Missing is any statement about required part/body state, error conditions, or whether the operation is undoable.

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?

Front-loaded verb-and-resource sentence followed by two tight clarifications, with the most surprising behavior (instances are not united) surfaced rather than buried. The backticked parameter names read slightly documentation-flavored but no sentence is wasted.

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?

An output schema exists, so return values need not be explained, and the core semantic ambiguities around count/spacing/merging are resolved. However, for a five-parameter mutation tool with zero annotation coverage, the absence of any prerequisite or safety context (open part, how to obtain body_id via nx_list_bodies, undo availability) leaves real gaps.

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. It does well for two parameters, disambiguating count (total including original, count=4 → 4 bodies) and spacing (per-instance delta in mm). It says nothing about body_id, direction, or the reverse flag, leaving three of five parameters to bare type/enum hints.

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 (pattern), resource (a body), and the qualifying mode (linearly along X/Y/Z). The word 'linearly' paired with the sibling names nx_circular_pattern and nx_mirror lets an agent place this tool precisely in the feature family without reading the schema.

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?

Gives a clear conditional rule: instances are independent bodies, so use nx_unite if merging is required. That names a real sibling and the condition that selects it. It stops short of an explicit 'when not to use' (e.g. versus nx_circular_pattern or nx_mirror) or prerequisite state such as an open part and a valid body_id.

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