illustrator_path_import_svg

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

Annotations already declare readOnly=False, destructive=False, idempotent=False, and openWorld=False, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: it parses SVG server-side, converts arcs to cubic Beziers, enforces safety limits (50,000 chars, 5,000 segments, 100 subpaths, +/-100,000 coords), returns bounds in Y-up space, and explains fill/stroke semantics (None=leave default, False=force off, {r,g,b}=force color). It also discloses that id collisions raise errors. This is rich behavioral disclosure that goes well beyond the structured annotations.

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 well-structured with clear sections (CONTRACT, WHEN TO USE, EXAMPLES, NOTES) and front-loads the core purpose in the first sentence. The examples are valuable but somewhat lengthy, and the NOTES section contains a mix of critical behavioral details and minor parameter clarifications. Every section earns its place, though the examples could be trimmed slightly without losing value.

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 tool with no output schema and 0% schema description coverage, the description carries a heavy burden. It covers the input format, safety limits, return bounds, fill/stroke semantics, id uniqueness, and the alternative tool for new shapes. The main gaps are the lack of explanation for tag, name, layer, and jobId parameters, and no explicit statement about what the return value looks like beyond bounds. However, the description is substantially complete for an agent to call this tool correctly in most scenarios.

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%, so the description must compensate for the schema's lack of parameter documentation. The description does this well: it explains the fill/stroke tri-state semantics (None=leave default, False=force off, {r,g,b}=force color), the id uniqueness requirement, and the d string parsing behavior. The examples also demonstrate how to structure fill, stroke, and id parameters. However, it doesn't explicitly explain the tag, name, layer, or jobId parameters, which are left to the schema (which has no descriptions for them either). Still, the description covers the most critical parameters and the examples are instructive.

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 opens with a specific verb and resource: 'Import an SVG path d attribute into the active document.' This clearly distinguishes the tool from siblings like illustrator_place_file (which imports files) and illustrator_execute_task (which creates new shapes). The WHEN TO USE section reinforces the purpose by naming the exact input type (SVG d strings) and use cases (complex outlines, organic shapes, arcs).

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 explicitly states when to use this tool ('Importing existing SVG path data') and provides a direct alternative: 'For new shapes prefer illustrator_execute_task + element_create with smooth:true.' This gives the agent a clear decision rule between this tool and its closest sibling. The examples also demonstrate realistic usage patterns, which further guide correct invocation.

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