execute_freecad_python

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

No annotations are present, so the description must disclose behavior on its own. It only mentions the environment-variable gate and says nothing about arbitrary code execution mutating documents, side effects, failure modes, or timeout behavior. This is insufficient for a code-execution tool.

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 one short sentence with no wasted words, but the main clause merely restates the tool name and the only added content is the allow-flag condition. It is under-specified rather than genuinely well-structured.

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?

Arbitrary Python execution is high-risk and high-complexity, yet the description offers only a single gating condition. A complete definition would explain that code runs in FreeCAD's Python environment, may modify the current document, and what timeout_ms does. The output schema may cover returns, but not usage context.

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%, and the description does not mention code or timeout_ms at all. An agent receives no explanation of what code should contain, how timeout_ms works, or how the parameters relate to execution.

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 says 'Execute FreeCAD Python', which essentially restates the tool name and gives little detail about what counts as 'FreeCAD Python' or what execution entails. It is vaguely distinguishable from siblings because no other execute tool exists, but an agent still has to infer that this runs arbitrary Python code in FreeCAD.

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 explicit clause 'only when FREECAD_ALLOW_EXECUTE_PYTHON=true' provides a clear precondition for invoking the tool. It implies the exclusion case (do not call when the flag is not true), though it does not discuss alternatives or when to prefer specific sibling tools.

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