constrain_faces

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

With no annotations the description carries the burden, and it does disclose a real surprise: the call reports which OTHER components moved, since a constraint can drag unintended parts. It also discloses target-document behavior (constraint goes into the active top assembly, sub-assembly refs legal) and the offset-sign retry heuristic. It stops short of saying whether over-constrained or failed solves raise errors, which matters for a mutation tool.

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 operation and scope, then a side-effect note, then a tidy Args block — nothing is buried. The sentence fragment 'Says which OTHER components the constraint moved' is slightly clipped and the sign caveat is repeated in both the offset arg and a_at, costing a little tightness.

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 a 7-parameter mutation tool with no annotations, the description covers the parts that matter: what is being constrained, reference syntax, mode semantics, offset/angle units, sign-failure recovery, output side effects, and which document is modified. An output schema exists, so not spelling out the return payload is not a gap, and the only omission is the optional 'instance' selection parameter.

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 only 14%, so the description must compensate and largely does: it defines a vs b roles, enumerates kind's three values with meaning for each, and scopes offset to mm for mate/flush and angle to degrees for kind='angle'. It leaves the 'instance' parameter undiscussed and does not constrain the keys allowed inside a_at beyond the single 'Z' example.

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 ('constrain two components by faces'), names where the refs come from (assembly_faces), and gives literal ref formats so it is unmistakably distinct from generic constrain and constrain_insert. It also pins the scope: the constraint lands in the active top assembly.

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?

Gives concrete invocation conditions: which ref forms are accepted, that a is the one meant to move, when to supply a_at ('its sign is easy to get wrong — give a_at too'), and that a_at mismatch triggers a sign retry. It never explicitly says when to prefer constrain_insert or plain constrain over this tool, so it falls short of full alternative-routing guidance.

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