Safely update Lucky settings

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

The description adds substantial context beyond annotations: it reveals partial-patch merge semantics (not a full overwrite) and names three protected fields that cannot be changed. This complements the annotations' idempotentHint=true and destructiveHint=false. It stops short of a 5 because the mechanics of 'prohibiting' are ambiguous—whether the patch is rejected outright or the protected fields are silently preserved.

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 sentence with zero filler. The verb and resource are front-loaded, and the critical safety constraint is delivered immediately. Every clause earns its place, and the title reinforces the safety angle with 'Safely'.

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 mutation tool with no output schema and a 0%-coverage input schema, the description covers the safety-critical invocation knowledge but leaves gaps: what happens when a protected field is included in the patch, which setting keys are valid, and what the tool returns on success or failure. The existence of lucky_get_settings as a sibling partially mitigates the missing key enumeration.

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?

With schema description coverage at 0%, the description carries the full burden and compensates well: it explains that 'patch' is a partial object merged into settings and identifies the fields that will be preserved. It does not enumerate the valid settings keys beyond the three protected ones, so an agent must infer the rest (possibly from lucky_get_settings).

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 states a specific verb ('Merge'), a precise resource ('Lucky base settings'), and a defining constraint (preserving/prohibiting changes to admin account, admin password, and OpenToken). This distinguishes it unambiguously from the resource-specific sibling update tools (certificates, port forwards, web services, DDNSS) and the read-focused lucky_get_settings.

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 usage context is implied clearly: this tool modifies the global Lucky settings, not any resource-specific configuration. However, it never explicitly names alternatives or states when-not-to-use, such as 'for certificate settings use lucky_update_certificate' or 'use lucky_get_settings to read first'. An agent can infer the use case but receives no explicit routing.

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