set_via_style

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

With no annotations, the description carries the full burden. It discloses that dry_run=true does not write, dry_run=false writes, and distances are always in millimetres regardless of document units. It also implies a verification step via expected_sha256. This is meaningful but does not discuss permissions, reversibility, or side effects beyond the preview/write mechanism.

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 concise sentences: the main action, the units caveat, and the critical preview/commit workflow. Every sentence serves a purpose with no redundant or vague phrasing.

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 (6 parameters, nested schema, output schema, no annotations), the description covers the core usage pattern and safety checks. It references the input schema for further details. It does not explain what a ViaStyle is or how selectors are formatted, but these are partly covered by the referenced schema. Overall, it is functionally complete for selecting and invoking the tool correctly.

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 for dry_run and expected_sha256 by explaining their roles in the preview/commit workflow. However, it does not explain selector, via_style, path, or txid, leaving significant gaps. The selector schema reference may help, but the description itself adds limited parameter value.

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 action ('Set an existing verified project ViaStyle') and the target resource ('selected vias'), making the purpose specific. It distinguishes from structural via tools like add_via or delete_via but does not explicitly name sibling alternatives, so it falls short of a 5.

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?

Provides clear operational guidance: use dry_run=true to preview, inspect the preview, then set dry_run=false and pass expected_sha256. This is valuable context for safe usage. However, it does not mention when not to use this tool or compare with similar style-related tools like set_trace_width, so it lacks explicit exclusions or alternatives.

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