Skip to main content
Glama
hram

FreeCAD MCP

by hram
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

execute_code

Run Python code in FreeCAD to automate modeling, geometry analysis, imports/exports, and GUI tasks; get printed output and an optional screenshot for verification.

Instructions

Execute arbitrary Python code in FreeCAD.

Args:
    code: The Python code to execute.
    include_screenshot: Whether to return a screenshot of the model (default True).
        Set to False to save tokens when the code does not change the model's
        appearance, e.g. analytical or computational scripts whose result is
        printed output, or intermediate steps in a longer sequence of changes.
    view_name: The view orientation of the returned screenshot (default "Isometric").
        Pick the view that best shows the change being made.
    timeout: Positive finite seconds for each of the queue and GUI execution
        budgets, overriding the 90 s default for this call (capped at 1800).
        Raise it for slow work that must
        run on the GUI thread, such as importing or exporting a large STEP
        assembly. Without it the call reports a timeout while the task keeps
        running, and the result is lost even though the work finishes. Prefer
        execute_code_async for heavy pure-geometry work that touches neither
        the document nor the GUI.

Returns:
    A message indicating the success or failure of the code execution, the output of the code execution, and a screenshot of the object.

Input Schema

NameRequiredDescriptionDefault
codeYes
timeoutNo
view_nameNoIsometric
include_screenshotNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and discloses meaningful behavior: 90-second default budgets, a 1800-second cap, timeout-result loss while the task continues, GUI-thread execution constraints, and the default screenshot behavior. It does not explicitly state that arbitrary code can mutate or destroy document state, which is an important safety caveat for this tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, then structured into Args and Returns. The extra detail on timeout and screenshots is directly actionable, and no sentence is wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all parameters and explains the return value despite there being no output schema, making it largely complete for invocation. However, for a tool that executes arbitrary code, it omits explicit warnings about side effects, permissions, or the distinction from execute_code_headless.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

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, and it documents all four parameters. It explains code, include_screenshot default and token-saving usage, view_name purpose, and timeout semantics including default, cap, budgets, and failure behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: executing arbitrary Python code inside FreeCAD. It also implicitly differentiates the tool from execute_code_async by recommending that sibling for heavy pure-geometry work, giving an agent enough to distinguish core execution behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete usage guidance: set include_screenshot to False for token savings, pick the view that best shows the change, raise timeout for slow GUI-thread work, and prefer execute_code_async for heavy pure-geometry work. It does not explicitly compare against execute_code_headless, which is the main gap.

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

Deploy Server

Other Tools