swdraw_tidy

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

With no annotations, the description carries the full burden, and it does disclose the critical trait that the operation is a DRY RUN unless dry_run is false. It does not disclose where files are moved to, whether the move is reversible, what 'live' means, or any permission requirements for what is effectively a destructive filesystem mutation.

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 purpose, immediately followed by the safety-critical dry-run default, then a compact key list. Three short sentences with essentially no waste, though the key list is terse to the point of under-explaining.

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 return values need not be described. For a mutation tool with no annotations and an opaque nested args object, the description covers the dry-run default and key names but omits the destination of moved files, the definition of 'live', and failure/error behavior.

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 0% and the schema is an opaque free-form 'args' object, so the description's key list (working, keep, superseded, move_folders, dry_run) is the only parameter documentation available. It glosses only 'keep (glob list)' and leaves the meaning and types of superseded, move_folders, and working unexplained, so it partially compensates but falls short of the gap.

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 concrete verb (move) and resource (files that aren't live) scoped to a working folder, which is specific enough to distinguish it from siblings like swdraw_build_drawing or swdraw_validate_spec. It stops short of explicitly contrasting itself with any named sibling.

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 condition for use is implied by 'files that aren't live out of a working folder', and the dry-run default gives a safe entry point. However, there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the sibling tools.

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