write_router_setting

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

With no annotations at all, the description carries full burden and does it well: it discloses the refusal behavior for unverified writes, the required user confirmation, the ~60-90 s router lock side effect, and the requirement to report the read-back rather than just 'success'. These are exactly the operational traits an agent cannot infer from the schema.

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?

Dense and front-loaded: the core action comes first, then the workflow, then the guardrail, then the return contract and side effect. Slightly fragmented by parentheticals, but every sentence carries information an agent needs.

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 three-parameter mutation tool with no annotations and no output schema, the description covers the mutation workflow, the safety gate, the post-write side effect, and what is returned ('after' read-back) — enough to invoke it correctly and report results faithfully. Nothing critical is left to guess.

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, and it mostly does: 'name' is illustrated (led_set, led_schedule), 'params' is defined as the whole object as read from the matching read with the change applied, and allow_unverified is explained behaviorally. It never explicitly maps these to the parameter names, so an agent must infer the correspondence.

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 ('Write a setting') and points to list_writes for the valid settings, which distinguishes it from read-side siblings like get_router_data and list_reads. It stops short of naming the other siblings it competes with, so identification is solid but not fully framed.

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 a concrete read-modify-write workflow ('read led_schedule, flip enable_night_mode, send it to led_set') and an explicit gate: refuses unverified writes unless allow_unverified=True, and the user must be asked first. It doesn't contrast with read-only alternatives (e.g., when a snapshot is preferable), but the when-to-use path is clear.

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