frame_members

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

With no annotations at all, the description carries the full burden and does substantial work: it discloses that each member becomes a Content Center custom-length part file (one file per profile/length, reused), where those files land, and that it returns placements plus a saw cut list. It still omits failure behavior (e.g. what happens with no active assembly or missing skeleton) and whether members are adaptively constrained to the skeleton.

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?

It is front-loaded with the one-line purpose before the argument block, and the parentheticals (Frame Generator has no API; roll 90 turns a U sideways) each resolve a real ambiguity rather than padding. Length is proportionate to a six-parameter tool with a nested member list.

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?

An output schema exists, so the brief return summary is sufficient, and the argument documentation is thorough for a complex nested-array call. The remaining gap is environmental: it never states the precondition that an assembly document must be active or what the tool does when the skeleton lines are absent.

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 17%, so the description must compensate, and it does: the members array is shown with a concrete JSON example and every per-member key is defined beyond the schema — roll in degrees with a worked U-section case, anchor 'center' vs 'origin', and extend as [start,end] mm with negatives to stop at a crossing member. The only undocumented parameter, instance, is already described in the schema itself.

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?

The definition opens with a specific verb and resource — building a steel frame of structural profiles along skeleton lines in the active assembly — and anchors it to a known concept (Frame Generator) that has no API. An agent can tell this apart from generic profile tools like extrude or place_component 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?

It establishes the operating context (active assembly, skeleton lines) and ends with an explicit verification step — 'Check with view_image' — which tells the agent what to do after calling. It does not name alternatives or state when not to use it (e.g. when to fall back to place_component plus constrain), so the routing guidance is implicit rather than explicit.

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