wave_create_widget

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

No annotations exist, so the description carries the full burden, and it does disclose the key traits: this is a mutating write scoped to ~/.waveterm/widgets.json, and it is gated behind a two-phase approval. It omits what happens if 'id' collides with an existing widget (overwrite vs. error) and any permission/file-existence requirements.

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?

Two tight sentences: purpose and side effect first, then the approval mechanic. Nothing is redundant and no sentence could be removed without losing a decision-relevant fact.

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 12-parameter mutation tool with no annotations and no output schema, the description covers purpose, write target, and the approval gate, and it even hints at the first-call return value. It is slightly thin on duplicate-id behavior and what a successful approved call returns, but nothing critical to calling it correctly is absent.

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% and all 12 parameters, including the nested env object, are documented in the schema, so the baseline is 3. The description reinforces only the approved flag's role in the confirmation flow and adds no semantics for id, view, env, or the defaulted booleans.

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?

Uses a specific verb + resource ('Create a new custom widget in Wave Terminal') and names the persistence target, which distinguishes it from read-side siblings like wave_get_widgets and from wave_update_widget. It never explicitly contrasts itself with near-neighbors such as wave_create_fish_widget or wave_create_block, so it stops short of full sibling differentiation.

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 procedural rule: the first call is a confirmation stub and the write only happens on a follow-up with approved=true. That is actionable guidance an agent would otherwise have to discover by trial. It does not say when to prefer this over wave_create_fish_widget or save_template, so no explicit exclusions.

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