Add Joint

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

The NOTE discloses a non-obvious and consequential side effect — creating the joint MOVES the components into coincidence — which goes well beyond the supplied annotations and is exactly what an agent needs to know before calling a mutating tool. Gaps remain: no statement of what is returned, what happens on failure (e.g. invalid face index), or whether the move can be undone except generically via the undo sibling.

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?

Front-loaded with the core action, then constraints, then the implicit alternative, with the side effect flagged as a NOTE so it is not buried. Dense but every clause carries information; the parenthetical hinge example is the only borderline addition and it earns its place as a disambiguator.

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?

For an 11-parameter, non-idempotent CAD mutation with no output schema, the description covers the make-or-break hazards: mandatory face geometry, the component-move side effect, and the as-built alternative. Remaining shortfall is joint_type, which has no description in the schema and no explanation in the description, leaving the agent to infer the difference between rigid, revolute, and the rest.

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 coverage is 73%, so the baseline is 3, and the description earns the bump by explaining what face_one/face_two actually mean geometrically (a cylindrical face per side, hinge knuckle bore as the canonical case) and by pointing at get_object_info to obtain indices. It does not add anything for joint_type, axis, or body_one/body_two, which are left entirely to the schema.

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?

States a specific verb and resource — 'Add a joint between two components' — and immediately narrows it to face-pair geometry, distinguishing it from create_as_built_joint and from component-origin constructions. An agent can pick this tool without opening the schema.

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?

Explicit preconditions ('face_one/face_two are mandatory', origins don't work and why), guidance on what geometry to choose ('pass a cylindrical face on each side', hinge/knuckle-bore example), a pointer to get_object_info for face indices, and a named alternative plus its selecting condition: 'use create_as_built_joint when the parts are already positioned.'

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