to_freecad

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

With no annotations, the description carries the full burden and does well: it discloses the optional freecadcmd verification step, that verified is false when freecadcmd is absent, that a measured deviation is returned, and that an 'error' key appears for out-of-vocabulary parts. It omits behavioral details such as whether output_path is overwritten and what happens on invalid input_path.

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 core action, then scoped vocabulary, then return behavior — a sensible order. The long enumeration of supported features is dense but earns its place because the description later says out-of-vocabulary parts return an error, so the list defines the tool's limits.

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?

The output shape is described well, which matters since there is no output schema, and error behavior is covered. However, for a tool whose only required argument is a path, leaving input_path, output_path, and tol entirely unexplained (with the 'parameters' wording ambiguous) leaves a real gap.

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% for all three parameters, and the description never mentions input_path, output_path, or tol. Worse, its use of the word 'parameters' refers to the generated macro's variables (hole_1_d, boss_1_h, fillet_r), not the tool's arguments, which could mislead an agent looking for input semantics.

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 opening sentence gives a specific verb, artifact, and format ('Write an editable parametric FreeCAD macro (.FCMacro) for a simple part'). It also anchors itself against the sibling to_cadquery by stating the part vocabulary and macro parameter names are the same, so an agent can tell which of the two converters produces which artifact.

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?

Usage context is implied rather than stated: 'Edit one and run the macro in FreeCAD, or with freecadcmd' describes what to do with the output, not when to pick this tool over to_cadquery or to_openscad. The 'Same parts as to_cadquery' framing hints at equivalence of scope, but no explicit when-to-use or when-not-to-use rule is given.

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