flat_pattern

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

With no annotations, the description carries the full load and does well: it discloses the implicit mutation ('Creates the flat pattern if the part has none'), the exact layer taxonomy of the output file (OUTER/INNER/IV_BEND*), and what is deliberately excluded (tangent lines, sketches). Gaps remain: behavior when the active document is not a sheet metal part, and whether an existing DXF at `path` is overwritten.

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 with the purpose and scope, then the args block; no filler sentences. It is somewhat dense and parenthetical, but every clause (layer legend, exclusion list, empty-path behavior) conveys operational information rather than restating the name.

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 description covers the mutation side effect, output file layout, and option semantics. It falls short only on failure modes (non-sheet-metal active document, file overwrite, format/path mismatch), which matter for a tool that writes a file to disk.

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 only 25%, so the description must compensate and largely does: it explains `path` semantics including the empty-string sentinel, restricts `format` to DXF or DWG, and defines `bend_lines` as emitting bend lines on their own layers. Only `instance` is left undocumented in the description, and the schema covers that one, so nothing is fully dark.

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 — generating/reporting the flat pattern of the active sheet metal part — and enumerates what it yields (flat size, thickness, bend count, DXF/DWG export). An agent can distinguish it from modeling siblings like sheet_metal_face or flange, though it never names a specific sibling to contrast with.

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 'Empty: just report the flat size' clause effectively gives the two operating modes (report-only vs. export), which is genuine when-to-use guidance. It also notes the tool will create the flat pattern if none exists, so the agent knows it need not run a separate step. No explicit when-not or prerequisite conditions (e.g. active document must be sheet metal) are stated.

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