replace_trace

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

With no annotations provided, the description carries the full burden. It discloses important behavioral traits: unit handling (millimetres regardless of Units), dry_run safety mechanism, and the need to pass expected_sha256 for actual writes. This goes beyond basic schema info, though it doesn't detail side effects on connectivity or what happens if endpoints cannot be preserved.

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 sentences long and highly efficient. The first sentence states the core function and constraint, the second clarifies units, and the third describes the safe dry-run workflow. Every sentence provides essential information with no redundancy.

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?

Given the tool's complexity (9 parameters, mutation semantics, safety-critical workflow), the description provides a solid foundation. It explains the critical safe usage pattern and units. The presence of an output schema covers return values. Some details about purpose and prerequisites are implied rather than explicit, but the description is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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. It adds meaning to dry_run and expected_sha256, and clarifies units for distance-related parameters. However, it does not explain parameters like path, txid, or clearance, which remain ambiguous despite their schema definitions. The names of trace_id, points, layer, and width are self-explanatory, but the overall compensation is only partial.

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 clearly states the tool's function: 'Replace trace geometry while preserving both connected endpoints.' This identifies a specific verb (replace) and resource (trace geometry), and the endpoint preservation constraint distinguishes it from related tools like add_trace, delete_trace, and set_trace_width.

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 provides explicit usage guidance: use dry_run=true to preview without writing, and only set dry_run=false after inspecting the preview and passing its expected_sha256. It also clarifies that distances are in millimetres regardless of the document's Units attribute. However, it does not explicitly contrast with alternative tools like add_trace or delete_trace, hence not a perfect 5.

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