fgui_set_publish_settings

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

With no annotations supplied, the description carries the full disclosure burden and does so thoroughly: it states the write does not enter the component document undo stack, does not go through the component persistence verification ladder, preserves unprovided fields, applies full-replacement semantics to atlasList, defaults missing packSettings keys to editor new-object defaults, and warns that external_reload is a same-process reopen rather than cross-restart persistence. These are exactly the non-obvious side effects an agent needs.

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 purpose is front-loaded in the first line, followed by short focused paragraphs each covering one behavioral risk (undo/persistence, partial updates, atlasList replacement, external_reload). The bolding marks the high-risk semantics, and no sentence is filler.

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?

An output schema exists so return values need not be explained, and the description covers the mutation, undo, and persistence caveats thoroughly. What is left implicit is the role of save and verify (both default true) and any failure or permission behavior, which matters for a write tool with nested free-form settings.

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 0% across five parameters, including a free-form nested settings object, so the description must compensate and largely does: it maps settings to output path, code generation, PackSettings, and the exclusion list, and clarifies both atlasList's replace semantics and external_reload's meaning. It does not explain save or verify, and the settings key space remains open-ended since additionalProperties is true.

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 opening line names a specific verb and resource — writing per-package publish settings — and enumerates the domains affected (output path, code generation, PackSettings atlas constraints, exclusion list). It is unambiguous what the tool mutates. Sibling differentiation is only implicit through the get/set naming symmetry with fgui_get_publish_settings rather than stated outright.

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 explains an important routing fact — package-level settings have no DocElement entry, so the object model path is used — but it never states when an agent should call this instead of fgui_get_publish_settings, fgui_publish, or fgui_save_document. Field-level guidance ('only write fields you actually intend to change') is useful but is scoping advice, not use-case selection.

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