Update widget settings

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

Annotations indicate readOnly=false and destructive=false, and the description complements this by disclosing immediate effect on the stream and durable template changes for alerts. This adds behavioral context beyond the annotations, though it doesn't detail error handling or reversibility.

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 concise sentences, front-loaded with the primary action and immediate effect. The round-trip pattern and alert-specific note add necessary detail without waste. Every sentence contributes substantive information.

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?

Given three parameters, two required, and no output schema, the description covers purpose, usage pattern, and side effects. It mentions active scene, format behavior, and alert durability. Missing details like error behavior or validation are minor for a well-scoped mutation tool.

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%, but the description enriches parameter semantics by explaining the settings object should be a full round-trip copy and that format omission applies to both canvases. This goes beyond the schema's basic property descriptions.

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 explicitly states 'Apply new settings to a widget in the active scene', using a specific verb (apply) with a clear resource (widget settings) and scope (active scene). It distinguishes from sibling tools like get_widget_settings (retrieval) and source-level setters by focusing on widget-level restyling.

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?

Provides concrete usage guidance via the round-trip pattern: 'Pass the full settings object from get_widget_settings with your changes applied (round-trip: get, modify, update).' Also clarifies format omission defaults to both canvases and alerts update the canonical template. Lacks explicit 'when not to use' or alternative tool comparisons, but gives strong contextual direction.

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