Skip to main content
Glama

add_primitive

Creates box, cylinder, sphere, cone, or torus solids in a FreeCAD document from dimensions, position, rotation, material, and color so AI clients can build parts.

Instructions

Add a primitive solid. dimensions keys per shape: box {length(x), width(y), height(z)}; cylinder {radius, height} (axis +Z); sphere {radius}; cone {radius1, radius2, height}; torus {radius1 (ring), radius2 (tube)}. The shape is created with its origin corner/base centre at position [x,y,z] mm (default origin) after rotating rotation_deg about rotation_axis (default Z). Box origin is its min corner; cylinder/cone origin is the centre of the base circle. material: aluminium_6061, steel, stainless_304, pa12, pla, pom. color: [r,g,b] 0..1.

Input Schema

NameRequiredDescriptionDefault
docYes
nameYes
colorNo
shapeYes
materialNo
positionNo
dimensionsYes
rotation_degNo
rotation_axisNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Although no annotations are provided, the description discloses key behavioral conventions: units are millimetres, default position is the origin, rotation defaults to 0 about Z, and each shape's origin is defined (box min corner, cylinder/cone base circle centre). It does not mention document-state requirements or failure behavior, but the geometric creation semantics are unusually well specified.

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 dense but front-loaded, starting with the core action before geometry details. Every sentence conveys necessary parameter semantics or coordinate conventions, with no filler.

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 tool has an output schema, so return-value explanation is unnecessary, and the description is complete enough to call the tool correctly for most parameters. It does not cover sibling selection or document-state expectations, but the critical nested dimensions and coordinate semantics are present.

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 carry parameter meaning, and it does: it maps dimensions keys per shape, defines position anchor semantics and rotation defaults, lists valid material values, and gives the color component range. It provides exactly the semantics the schema does not.

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 opens with a specific verb and resource: "Add a primitive solid," and immediately enumerates the supported primitive shapes. This distinguishes it clearly from siblings like import_step, extrude_polygon, and boolean without requiring the agent to inspect the schema.

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

Usage Guidelines3/5

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

Usage is implied by "Add a primitive solid" and the shape list, but the description does not say when to choose this over import_step, insert_library_part, extrude_polygon, or other modeling siblings. There are no explicit alternatives or exclusions.

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