ai_applyEffect

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

Annotations already declare non-read-only, non-destructive, non-open-world, so the safety profile is covered. The description adds the useful fact that plugin effects are accepted and shows the required XML shape, but says nothing about whether the effect is reversible, whether it fails on locked items, or what a successful call returns.

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?

A single front-loaded sentence with the resource first, then the concrete example, then effect categories — no filler. The trailing 'plugin effects.' fragment is slightly tacked-on but still carries information about valid input scope.

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 3-parameter mutation with no output schema, the description covers input format well but omits preconditions (open document, editable/unlocked artwork) and outcome (what happens on malformed XML, whether the effect appears in the Appearance panel). Adequate but with clear gaps for a write operation.

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 67%: 'items' and 'document' are already documented structurally, but 'xml' has no schema description at all. The description compensates for exactly that gap with a full worked XML example including the Dict attribute encoding, which is meaningfully more than the schema provides.

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?

States a specific verb and resource ('apply a Live Effect') scoped to Illustrator, and pins down the exact mechanism (XML definition) plus target (items/selection). The inline XML sample and named effects (Drop Shadow, Gaussian Blur, Round Corners, Offset Path) make it unmistakable versus siblings like ai_modifyItems or After Effects' ae_addEffect.

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 makes the invocation clear: supply a LiveEffect XML string, and the schema note ('omit to use the current selection') identifies the selection fallback. It names effect families to steer the agent toward valid inputs, but never states when to prefer ai_modifyItems or what to do if no document is open.

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