Set KeenDNS mapping

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds meaningful context beyond that: dry_run is TRUE by default (a safety-critical detail), protected names (MCP servers, Home Assistant) are refused in code, and the mapping is published with ssl redirect on the ndns domain. It doesn't mention permission requirements or what an update overwrites, hence not a 5.

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?

A single dense sentence that front-loads the core action and then appends the key safety facts (protected names refused, dry_run default). Efficient with no filler, though the parenthetical and colon-separated clauses make it slightly packed rather than ideally scannable.

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 destructive, idempotent mutation tool with no output schema, the description covers the essential agent needs: what it changes, the safe-by-default dry_run behavior, and the protected-name guard. It omits what an update does to pre-existing fields and any auth requirements, but annotations carry the safety profile, so this is largely complete.

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 100%, so the schema already documents all six parameters including defaults. The description restates the name->host:port mapping and the ssl/ndns publication semantics, adding some conceptual clarity, but no format, range, or validation details beyond what the schema provides. Baseline 3 applies.

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+resource ('Create or update a KeenDNS web-access mapping') plus the underlying RCI concept ('ip http proxy') and the exact data flow (name -> upstream host:port, published on the ndns domain with ssl redirect). This clearly distinguishes it from the sibling readers get_keendns_mappings and the mutator remove_keendns_mapping.

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 implies usage (create/update a web-access mapping, dry_run defaults to TRUE, protected names are refused), which gives the agent useful operating context. However it never states when to choose this over alternatives like set_port_forwarding or set_dns_host, nor when-not to use it, so guidance is implied rather than explicit.

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