icon_map

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

The description discloses extensive behavioral details beyond the readOnlyHint annotation: gitignore-aware scanning, name-based and near-exact matching, fallthrough on uncertainty, color contract extraction (currentColor/fixed/multi-color), recolor guidance, importHint variants, and the fact that it does not fabricate import lines. This far exceeds the annotation's minimal information.

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 concise relative to the tool's complexity, with every sentence adding value (matching behavior, import hints, return shape). It is front-loaded with the core purpose. However, a long single paragraph is slightly dense; bullet points could improve scannability, but it is still well within acceptable length.

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?

Despite no output schema, the description clearly states the return shape: 'Returns { mappings, unmapped, iconLibraries, profile }' and explains what each part contains (file path, color contract, recolor info, importHint forms). It also covers failure handling, defaults, and integration with project imports. This is a complete, self-contained description for a complex tool.

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 100% for all three parameters, so the schema already documents their meanings and defaults (e.g., rootDir defaults to cwd, threshold default 0.7). The description adds context about matching thresholds indirectly but does not provide additional parameter-specific syntax or edge-case details beyond the schema. Baseline 3 is appropriate.

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 specifies the tool's function: 'Map the Figma icon nodes in a selection/subtree to the project's existing `.svg` files'. It also explains the goal 'so codegen reuses the designer-curated asset instead of re-exporting a duplicate', which distinguishes it from sibling mapping tools like token_map and component_map.

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 gives clear context for when to use the tool (during codegen to reuse existing SVG assets) and describes fallback behavior ('unsure matches fall through to a fresh export'). It does not explicitly state when not to use it or name alternative tools, but the 'iconLibraries' mention and distinct purpose imply alternatives. The lack of explicit exclusions prevents a 5.

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