wave_set_setting

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

With no annotations, the description carries the full burden, and it does disclose the important two-phase confirm/execute behavior for this mutation. It does not say whether changes persist to disk immediately, whether a restart or reload is required for the setting to take effect, or what happens on an invalid key.

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?

Three short sentences, with the action stated first and the confirmation flow immediately after — well front-loaded. The trailing examples list is mildly redundant with the key parameter description but still useful for key discovery.

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?

The two-step write flow is covered and no output schema exists to explain, so the essentials are present. For a mutation tool with zero annotations, it is thin on persistence, validation, and error behavior, and says nothing about how it relates to the many specialized set_* siblings.

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 100%, so both key and approved are fully documented in the schema, and the description's key examples ('ai:model', 'term:theme') repeat what the schema already shows. Baseline 3 applies; no additional semantics (value coercion, key format edge cases) are added beyond the schema.

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: 'Update a single Wave Terminal setting in settings.json', and scopes it to one setting at a time. It does not distinguish itself from near-siblings like wave_set_theme, wave_set_appearance, or wave_set_ai_preset, which an agent could reasonably pick instead.

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 clear operational context: first call returns a confirmation and approved=true is required to execute, which tells the agent exactly how to drive the call sequence. It stops short of saying when to prefer this generic tool over the dedicated siblings (wave_set_theme, wave_set_ai_preset, wave_set_appearance).

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