Skip to main content
Glama
gchen19

AnkusDrive

by gchen19
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

add_primitive

Create a box, cylinder, or sphere in the active FreeCAD document with optional position and label, returning a handle for later boolean operations.

Instructions

Add a primitive to the active document.

kind: 'box' (uses w, d, h), 'cylinder' (uses r, h), or 'sphere' (uses r). placement: optional [x, y, z] mm translation. name: optional human-facing name. It sets the object's LABEL — what list_objects, bom_extract and the drawing/manifest layers display — and leaves the internal FreeCAD Name alone, since handles and register_handle key off Name and it must stay unique and stable. Omit it and the label stays the type default ('Box' / 'Cylinder' / 'Sphere'), which BOM and designation checks read as an unnamed generic solid. Returns {handle, name, label, volume}: name is FreeCAD's internal id and label is the display name (equal to name when you passed none). The handle (e.g. 'box_1') is how you reference this object in subsequent boolean_op calls.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dNo
hNo
rNo
wNo
kindYes
nameNo
placementNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does substantial work: it discloses that name sets the LABEL while leaving FreeCAD's internal Name alone, that Name must stay unique and stable for handles/register_handle, that omitting name yields a type default read by BOM and designation checks, and it documents the return tuple {handle, name, label, volume}. Missing a note on failure modes (e.g. no active document) or coordinate-frame semantics for placement, so not a 5.

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

Conciseness4/5

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

Front-loaded with the core action, then structured per-parameter blocks and a returns line; each sentence carries information. The name paragraph is somewhat dense but every clause is load-bearing (label vs Name, uniqueness, defaults, downstream readers).

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?

For a 7-parameter mutation tool with no annotations and no output schema, the description covers kinds, dimensions, placement, naming semantics, and the return shape, plus the downstream handle contract. It leaves out error conditions and whether an active/selected document prerequisite can fail, keeping it just short of complete.

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 coverage is 0%, so the description must compensate and does: it maps w/d/h to 'box', r/h to 'cylinder', r to 'sphere', specifies placement as optional [x, y, z] mm, and explains the label-vs-Name distinction for the name parameter. This goes well beyond the bare schema titles.

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?

States a specific verb and resource ('Add a primitive to the active document') and immediately enumerates the supported kinds ('box', 'cylinder', 'sphere'), which differentiates it from specialized siblings like add_gear, add_rack, or hole. An agent can identify the tool's scope without inspecting 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 Guidelines4/5

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

Gives clear operational context: it operates on the active document, the three valid kinds and their dimension sets, optional placement in mm, and the consequences of omitting name. It does not explicitly name alternatives (e.g. 'for a geared part use add_gear instead') or state when not to use a generic primitive, so it stops short of full when/when-not routing.

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