sew

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

No annotations are provided, so the description carries the full disclosure burden. It reveals a key behavioral trait — irreversibility: 'there is no API to remove a seam, so save a checkpoint first' — and tells the agent how to verify effects using simulate and snapshot. This goes well beyond a bare mutation statement, though it does not cover failure behavior for invalid pattern references or the return format.

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?

The description is three purposeful sentences ordered by importance: the operation itself, the tricky direction rule with example, then the irreversibility warning and checkpoint workflow. There is no filler, no repetition of the schema, and each sentence earns its place in helping the agent call the tool correctly.

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 six-parameter mutation tool with no output schema and no annotations, the description covers the critical context: direction orientation, verification via simulate plus snapshot, and the checkpoint-first recommendation. Smaller gaps remain (no stated return shape or failure semantics for missing resources), but the core call contract is sufficiently complete for an agent to invoke it safely.

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 description coverage is 0%, so the description must compensate, and it does for the hardest parameters. It narratively maps pattern_a/line_a and pattern_b/line_b, and explains dir_b with a concrete example ('front right side <-> back left side') and an explicit condition (opposite directions). dir_a is left somewhat implicit, but its behavior follows from the stated 'each line's point order' rule.

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 description opens with a specific verb and resources: 'Sew line_a of pattern_a to line_b of pattern_b.' The parenthetical 'segment sewing' scopes the operation as a line-to-line join rather than a whole-pattern operation. Among sibling tools there is only seams_list (a read-only inspection tool), so the purpose is unambiguous and well-differentiated.

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?

The description gives actionable when-to-set guidance for direction parameters: 'Directions follow each line's point order; when the two lines run in opposite physical directions set dir_b=False.' It also prescribes a follow-up workflow (check with simulate and snapshot) and a saving checkpoint precondition. It does not state explicit exclusions or name-alternative calls, but since no other tool performs sewing, the guidance is still clear context for correct invocation.

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