set_settings

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

With no annotations provided, the description carries the full burden and does so well. It discloses conflict behavior (no handler execution, returns latest doc), prohibits automatic retry with the same arguments, warns that communication errors may leave application results unknown, and advises checking state with await_change.

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?

The description is front-loaded with the tool's purpose and then covers the important revision-conflict protocol and error caveats. It is dense and mixes languages, but every sentence conveys a necessary behavioral or procedural 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 complex 8-parameter mutation tool with no output schema, the description covers conflict semantics, latest-doc review, no-auto-resend behavior, communication-error ambiguity, and the await_change precondition. It does not describe the success return shape or the exact meaning of every visual setting, but it is substantially 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 low at 13%, and the description only restates most parameter names without adding meaning beyond their schema constraints. However, it provides substantial semantics for baseRevision: pass the observed revision string, old numeric formats are invalid, and conflicts occur if the version changed. This partial compensation makes it adequate but incomplete.

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 clearly states a specific action ('Set') and a specific resource: canvas-level settings including heading, notes, visibility, grid, style, color, and opacity. This distinguishes it from sibling tools like set_text and set_box, which target different resources.

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 gives clear procedural guidance: call await_change first to confirm current state, pass the observed baseRevision, and do not automatically resend with a new revision on conflict. It does not explicitly contrast with sibling tools, but the resource scope and preconditions make the intended usage clear.

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