The operation envelope

Eighteen of the nineteen tools take exactly one argument, named operation, with a uniform three-field shape (list_supported_formats takes nothing). This is the CADOperation Pydantic model:

{
  "file_path": "/data/site-plan.dxf",
  "operation": "extract",
  "parameters": {
    "layer_pattern": "C-PROP*"
  }
}

Field	Type	Description
file_path	string, optional	Path to the CAD file, for tools that read one. Tools that only create (create_2d_geometry, create_assembly, …) leave it unset.
operation	string, required	A short label for the operation. Required by the schema on every call; most tools dispatch on the tool name and ignore it, but modify_geometry and perform_boolean_operations read parameters.operation for their sub-operation. Any descriptive string satisfies the field.
parameters	object, default {}	Tool-specific parameters — every tool’s reference page documents its keys.

How calls nest

Because each tool takes a single model-typed parameter, an MCP call_tool nests one level:

result = await client.call_tool(
    "extract_parcels",
    {
        "operation": {
            "file_path": "/data/site-plan.dxf",
            "operation": "extract",
            "parameters": {"layer_pattern": "C-PROP*"},
        }
    },
)

The outer key is the tool’s parameter name (operation); the inner object is the CADOperation. Forgetting the outer wrapper is the most common first-call mistake.

Result conventions

Every tool returns a plain JSON object, one of two shapes:

Success — always includes "success": true plus tool-specific fields:

{ "success": true, "parcels_found": 38, "parcels": [...], "diagnostics": {...} }

Failure — a single "error" key with a human-readable message:

{ "error": "File not found: /data/missing.dxf" }

Tool-level failures are returned as data, not raised as protocol errors, so an agent can read the message and adjust (a wrong layer pattern comes back with suggestions, for instance). Genuinely malformed calls — schema violations, unknown tools — surface as MCP protocol errors from FastMCP itself.

Shared validation

All file-reading tools apply the same checks, in order, before touching the file:

1. Path safety — null bytes and parent-directory traversal (.., both slash styles) are rejected: "Invalid file path (parent directory traversal not allowed): ...".
2. Existence — "File not found: <path>".
3. Size limit — "File too large. Maximum size: 100MB" (configurable via MAX_FILE_SIZE_MB).

Tools that write files validate output_name the same way — no separators, no traversal — and always write under the configured output directory.

Validation runs before the FreeCAD availability gate, so a bad path reports “File not found” even on a host without FreeCAD, rather than a misleading “FreeCAD not available”.