open_document

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

With no annotations, the description carries the full burden and does substantial work: it discloses that the file becomes the current document, that an imported body has no feature history yet still supports holes, bosses and fillets, that an imported assembly's parts arrive as placed components, and what the result reports (body count, mass properties, component count). Missing are failure behavior for unsupported/ corrupt files and whether an existing current document is replaced or a new window is opened.

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 verb and formats are front-loaded in the first clause, and the remaining sentences each add distinct information (part path, imported-body path, assembly path, drawing exception). It is denser than it needs to be and the closing 'Drawings:' fragment is slightly abrupt, but no sentence is 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?

There is no output schema, so the description's account of what comes back (solid body count, mass properties, component count) is genuinely necessary and present. Combined with the part/assembly/drawing branching, an agent has nearly everything it needs; only error handling and current-document replacement semantics are absent.

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 0%, so the description must compensate, and it largely does: 'path' is scoped to the listed file formats, and 'kind' is explained as an optional up-front declaration of 'part' vs 'assembly' rather than leaving the default inference unstated. It never gives path syntax (absolute vs relative, extensions required) or the exact accepted kind values as literals.

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 ('open'/'import') plus the exact resource and accepted formats (.sldprt, .sldasm, STEP/IGES/Parasolid), and the side effect ('becomes the current document'). This clearly separates it from new_document, activate_document, and drawing_file, which is named for the drawing case.

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 routes drawings elsewhere ('drawing_file(action='open')') and explains the kind='part'/'assembly' choice for neutral files. It also names the follow-up tools (list_features, list_dimensions, list_components, add_mate), which orients the agent in a workflow. It does not, however, address open_document vs. activate_document or what happens if a document is already open.

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