import_svg

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

Annotations only state readOnlyHint=false and destructiveHint=false. The description adds context: it mentions the implementation via createNodeFromSvg, the default sizing behavior, and the return shape { ok, nodeId, name, type }. It does not disclose error handling or edge cases, but for a non-destructive mutation it covers most relevant behavior.

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 information-dense with no fluff. It front-loads the core function, then gives usage context, alternative guidance, and return value in a tightly structured sequence. Every sentence contributes.

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?

The description is largely complete for a 7-param, no-output-schema tool. It covers purpose, usage, alternatives, return value, and sizing behavior. It omits potential edge cases (e.g., SVG sanitization, positioning semantics), but given the context it is well-rounded. A higher score would require mention of those edge cases.

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?

With 71% schema description coverage, the description adds meaning to svg (raw markup string, read from asset or inline) and width/height (override intrinsic size). It does not address x/y placement, but those are standard and less critical. The added semantics go beyond the schema fields.

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 identifies the verb (import) and resource (SVG), specifying it creates editable vector nodes as a frame of vector paths. It distinguishes from siblings by mentioning vector logos/brand marks/icons and explicitly contrasting with import_image for raster photos and create_instance for existing icon components.

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?

Provides explicit guidance: 'use this for vector logos, brand marks, and icons', and explicitly says 'For raster photos (PNG / JPG) use import_image instead' and 'when a matching icon component already exists, create_instance it rather than re-pasting the SVG.' This gives clear when-to-use and when-not-to-use alternatives.

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