router_set_dns

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

With no annotations, the description carries the full load. It usefully discloses an internal safety gate ('Network Guard') and how to bypass it, which is real behavioral context. It does not say whether the change is immediate or requires a reconnect, whether it is reversible, what Network Guard actually blocks, or what happens on invalid IPs.

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?

One front-loaded sentence establishes the operation, followed by a compact Args block with no filler. Every line carries information; only the redundant 'default 8.8.8.8' duplication with the schema is mildly wasteful.

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 explained. However, for an unannotated mutation tool that rewrites WAN DNS, the description omits blast-radius information: whether existing connectivity drops, whether the router validates the resolvers, and what Network Guard protects against. Adequate but with a clear safety-context gap.

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 it does: it explains primary_dns with concrete examples (8.8.8.8, 1.1.1.1), states secondary_dns's default, and explains that force bypasses a safety check rather than restating its type. It stops short of describing IP format/validation rules.

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: 'Configures custom DNS resolvers on the router's WAN connection.' The WAN-scoping detail is beyond what the name conveys. No sibling tool touches DNS, so there is nothing to disambiguate against explicitly.

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?

Usage is implied by the purpose, and the description does give one useful conditional (set force=True to bypass the Network Guard safety check), but it never says when to prefer this tool over e.g. router_set_wifi_radio or the other configuration tools, nor what prerequisites exist.

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