fgui_insert_loader

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

With no annotations supplied, the description carries the full load and does it well: fixed autoSize=false, coordinate truncation toward zero with a 'rounded' report, default no-save, non-participation in the Agent undo stack, discarding unsaved changes, and the fact that save writes the entire document. It omits auth/permission context and return shape details, but the mutation and persistence semantics are unusually well disclosed.

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 dense and front-loaded, leading with what is created and how url behaves before the state/persistence notes. The terse phrasing is efficient rather than noisy, though the bullet-like fragments border on note form rather than prose.

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 described, and the tricky state behavior (undo stack exclusion, save scope, discard) is covered. Against 13 undocumented parameters with no annotations, the five unexplained layout/style parameters remain unaddressed.

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 13 parameters, so the description must compensate; it covers url, x/y/width/height, save, verify, and external_reload, which is real added meaning. It leaves fill, name, align, v_align, and shrink_only entirely unexplained, so roughly a third of the parameters have no semantics anywhere.

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 names a specific verb and resource (create a Loader under the current document's root component) and adds a version constraint (0.8.25+), so the agent knows exactly which object type is produced. It does not explicitly contrast itself with fgui_insert_object or explain when the generic insert should be preferred 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?

It states concrete preconditions: url may be empty or must reference an in-project image/MovieClip, external URLs are rejected, and external_reload requires save=true with verify=true. However, there is no guidance on when to choose this tool over the sibling fgui_insert_object, nor any exclusions for the other 13 parameters.

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