add_ipv6_route

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

With no annotations, the description carries the full burden and does so richly: it discloses the MIKROTIK_ALLOW_WRITE=true gate, the confirm preview workflow, that duplicates are never refused (failover shape), the non-null `warning` on default-route override, and a distinct error when the ipv6 package is disabled. This is exactly the behavioral detail an agent needs before a mutating call.

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-loads the purpose and command, then groups parameters, then flags RISK and the write guard in their own blocks. Every sentence adds a constraint or behavior; nothing is padding.

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 guarded write tool with a 6-parameter schema, 0% schema coverage and an output schema, it covers validation rules, risk, gating, error conditions, and even references the preview's `warning` field rather than re-explaining return values. Nothing an agent needs to call it correctly is missing.

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%, so the description must compensate and largely does: it marks dst_address/gateway as required IPv6-validated values, explains distance as failover priority where lower wins, notes comment as optional, and describes confirm's preview-vs-apply semantics. Only device_name is left undefined, a minor gap against otherwise thorough coverage.

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 specific verb and resource ('Add a static IPv6 route'), ties it to the underlying RouterOS command, and explicitly distinguishes it from the IPv4 sibling by noting it 'Mirrors add_route on the IPv6 menu.' An agent can route IPv4 vs IPv6 intent without opening either 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?

Gives clear context: use this for IPv6 (the IPv4 counterpart is add_route) and follow the confirm=False-preview-then-confirm=True sequence. It stops short of explicitly stating when-not to use it (e.g. vs remove_ipv6_route or ipv6_routes), so it is strong but not exhaustive.

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