Supericons

Use this as the main icon tool. Search 20,000+ curated SVG icons across 11 libraries by meaning, label, visual description, tags, and synonyms. When matches exist, the response includes a paste-ready suggested answer, a direct preview image, and Markdown that can show the image in the final reply. When no supported match exists, it returns an honest structured no-result with a next step and no fabricated icon. If you choose a library yourself, use prefer. Use strict only when the user explicitly requires that library. Library key si means Supericons, not Simple Icons.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Icon concept or search phrase, for example \"database\", \"user profile\", \"chill\", \"trash\", \"upload cloud\", \"AI model\", or \"beautiful\"."
    },
    "library": {
      "type": "string",
      "description": "Optional library key only when the user named a library. Omit it to search all libraries. Do not use all as a library key. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute."
    },
    "library_mode": {
      "$ref": "#/properties/library",
      "description": "Optional library behavior. Omit a self-chosen library and search all, or use prefer with that library. Use strict only when the user explicitly requires the named library. All searches every eligible library. Unsupported or incomplete combinations are safely normalized with a warning."
    },
    "style": {
      "$ref": "#/properties/library",
      "default": "any",
      "description": "Optional style preference. Unsupported values are ignored with a warning."
    },
    "locale": {
      "$ref": "#/properties/library",
      "description": "Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th. Unsupported values are ignored with a warning."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 50,
      "default": 10,
      "description": "Maximum number of icons from 1 to 50. Numeric strings are accepted."
    },
    "include_query_frame": {
      "type": "boolean",
      "default": false,
      "description": "Optional public-safe diagnostics for query understanding. Boolean strings are accepted. Leave false for normal compact responses."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Icon ID without the library prefix."
          },
          "name": {
            "type": "string",
            "description": "Human-readable icon name."
          },
          "library": {
            "type": "string",
            "description": "Source icon library key."
          },
          "library_key": {
            "type": "string",
            "description": "Source icon library key repeated for explicit agent display."
          },
          "library_name": {
            "type": "string",
            "description": "Public source library name, for example Supericons or Simple Icons."
          },
          "library_label": {
            "type": "string",
            "description": "Public source library label, for example Supericons (si)."
          },
          "libraryName": {
            "type": "string",
            "description": "Legacy camelCase public source library name."
          },
          "icon_ref": {
            "type": "string",
            "description": "Stable icon reference in library:id format."
          },
          "icon_preview_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Browser URL for visual inspection of this icon."
          },
          "search_preview_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Browser URL for visual inspection of the source search results."
          },
          "type": {
            "type": "string",
            "description": "Icon asset type, normally svg."
          },
          "style": {
            "type": "string",
            "description": "Icon style such as outline or solid."
          },
          "svg": {
            "type": "string",
            "description": "Inline SVG markup for the icon."
          },
          "semantic": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ],
            "description": "Public semantic guidance for search and agent selection."
          }
        },
        "required": [
          "id",
          "name",
          "library",
          "library_key",
          "library_name",
          "library_label",
          "icon_ref",
          "icon_preview_url",
          "type",
          "style",
          "svg"
        ],
        "additionalProperties": false
      },
      "description": "Matching icons with SVG code and semantic guidance."
    },
    "outcome_type": {
      "type": "string",
      "enum": [
        "results",
        "no_match",
        "tool_error"
      ],
      "description": "Whether this response contains results, an honest no-match, or a tool failure."
    },
    "result_count": {
      "type": "number",
      "description": "Number of verified icons returned by this search."
    },
    "top_result_ref": {
      "type": [
        "string",
        "null"
      ],
      "description": "Top ordered icon ref when results exist."
    },
    "result_interpretation": {
      "type": "string",
      "description": "Plain-language guidance for interpreting this result count and outcome."
    },
    "library_mode": {
      "type": "string",
      "enum": [
        "strict",
        "prefer",
        "all"
      ],
      "description": "Library behavior used for this search."
    },
    "requested_library": {
      "type": [
        "string",
        "null"
      ],
      "description": "Preferred or required library, when supplied."
    },
    "preview_url": {
      "type": "string",
      "description": "Browser URL for visual inspection of this search result set."
    },
    "image_url": {
      "type": "string",
      "description": "Direct PNG URL when usable icons exist."
    },
    "markdown_image": {
      "type": "string",
      "description": "Ready-made Markdown image when usable icons exist."
    },
    "suggested_response_markdown": {
      "type": "string",
      "description": "Compact answer that accurately reflects this response."
    },
    "next_step": {
      "type": "string",
      "description": "Useful next action for the caller."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Unsupported optional inputs that were safely ignored."
    },
    "error": {
      "type": "string",
      "description": "Plain-language error for a structured no-result."
    },
    "code": {
      "type": "string",
      "description": "Stable code for a structured no-result."
    },
    "hint": {
      "type": "string",
      "description": "Plain-language recovery hint for a structured no-result."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether changing the query or filters may produce a result."
    },
    "status": {
      "type": "number",
      "description": "HTTP status from an upstream search failure."
    },
    "retry_after_seconds": {
      "type": "number",
      "description": "Seconds to wait before retrying a rate-limited search."
    },
    "limit_scope": {
      "type": "string",
      "description": "Allowance scope reported by a rate limit."
    },
    "details": {
      "type": "object",
      "additionalProperties": {},
      "description": "Structured rate-limit or upstream failure details."
    },
    "query_frame": {
      "type": "object",
      "additionalProperties": {},
      "description": "Optional public-safe query understanding diagnostics."
    },
    "search_runtime": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local_first",
            "local_fallback",
            "hosted_fallback",
            "hosted",
            "hosted_fused"
          ]
        },
        "fallback_used": {
          "type": "boolean"
        },
        "degraded": {
          "type": "boolean"
        },
        "hosted_search_calls": {
          "type": "number"
        },
        "hosted_failure_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "hosted_failure_status": {
          "type": [
            "number",
            "null"
          ]
        },
        "hosted_result_count": {
          "type": "number"
        },
        "hosted_circuit_state": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "closed",
                "open",
                "half_open_ready"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "local_attempt_count": {
          "type": "number"
        },
        "local_retry_used": {
          "type": "boolean"
        },
        "local_retry_recovered": {
          "type": "boolean"
        },
        "local_failure_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "local_result_count": {
          "type": "number"
        },
        "local_fusion_used": {
          "type": "boolean"
        },
        "index_generated_at": {
          "type": "string"
        }
      },
      "required": [
        "mode",
        "fallback_used",
        "hosted_search_calls",
        "local_failure_code",
        "index_generated_at"
      ],
      "additionalProperties": false,
      "description": "Search execution path used for this request."
    }
  },
  "required": [
    "results",
    "library_mode",
    "requested_library",
    "suggested_response_markdown",
    "next_step"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Recommend a coherent icon set for up to 20 named UI slots in one call. Uses task context to narrow ambiguous meanings. When context is insufficient, returns needs_clarification with labeled interpretation options instead of guessing. Invalid inputs and service failures return a plain-language reason and a next step instead of a bare protocol error. Returns one recommendation and optional alternatives for each resolved slot, with explicit public library labels and visual preview URLs where available. Library key si means Supericons, not Simple Icons.

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "default": "",
      "description": "Overall UI task, for example \"choose icons for an AI dashboard sidebar\" or \"select bottom navigation icons for a finance app\". Missing task text returns a structured recovery message."
    },
    "slots": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": [],
      "description": "List of 1 to 20 UI slots to fill, for example [\"model\", \"prompt\", \"dataset\", \"evaluation\"]. A single string is accepted as one slot. Larger lists return a structured split instruction."
    },
    "library": {
      "$ref": "#/properties/task",
      "description": "Optional library key when the user wants a consistent icon family. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute."
    },
    "style": {
      "$ref": "#/properties/task",
      "default": "any",
      "description": "Optional style preference. Unsupported values are ignored with a warning."
    },
    "locale": {
      "$ref": "#/properties/task",
      "description": "Optional locale for multilingual slot labels. Unsupported values are ignored with a warning."
    },
    "limit_per_slot": {
      "type": [
        "number",
        "string"
      ],
      "default": 3,
      "description": "Number of choices per slot. Values outside 1 to 5 are clamped with a warning. Numeric strings are accepted."
    },
    "response_mode": {
      "$ref": "#/properties/task",
      "default": "plan",
      "description": "Response size mode: plan, assets, or full. Unsupported values use plan with a warning."
    },
    "include_query_frame": {
      "type": "boolean",
      "default": false,
      "description": "Optional public-safe diagnostics for query understanding. Boolean strings are accepted. Leave false for normal compact responses."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "description": "Original UI task."
    },
    "library": {
      "type": "string",
      "description": "Library filter used for recommendations, if provided."
    },
    "style": {
      "type": "string",
      "description": "Style preference used for recommendations."
    },
    "response_mode": {
      "type": "string",
      "enum": [
        "plan",
        "assets",
        "full"
      ],
      "description": "Response size mode used for this recommendation."
    },
    "slot_count": {
      "type": "number",
      "description": "Number of UI slots requested."
    },
    "all_slots_resolved": {
      "type": "boolean",
      "description": "Whether every requested slot received a recommendation without clarification."
    },
    "needs_clarification": {
      "type": "boolean",
      "description": "Whether one or more ambiguous slots require more context."
    },
    "clarification_slots": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Slots that need the caller to choose an interpretation."
    },
    "low_confidence_slots": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Slots whose result is missing or has low confidence."
    },
    "fallback_recommended": {
      "type": "boolean",
      "description": "Whether the caller should consider direct search or clarification."
    },
    "preview_url": {
      "type": "string",
      "description": "Browser URL for visual inspection of the recommended icon set."
    },
    "query_frame": {
      "type": "object",
      "additionalProperties": {},
      "description": "Optional public-safe query understanding diagnostics for the task."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      },
      "description": "Recommended icon choices grouped by requested UI slot."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Unsupported optional inputs that were safely ignored or clamped."
    },
    "error": {
      "type": "string",
      "description": "Plain-language reason the recommendation did not complete."
    },
    "code": {
      "type": "string",
      "description": "Stable error code for programmatic recovery."
    },
    "hint": {
      "type": "string",
      "description": "Plain-language recovery instruction."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether a corrected or later request may succeed."
    },
    "status": {
      "type": "number",
      "description": "HTTP status from a hosted dependency failure."
    },
    "retry_after_seconds": {
      "type": "number",
      "description": "Seconds to wait before retrying a rate-limited recommendation."
    },
    "details": {
      "type": "object",
      "additionalProperties": {},
      "description": "Structured limits or failure details."
    },
    "suggested_response_markdown": {
      "type": "string",
      "description": "Plain-language explanation suitable for the agent response."
    },
    "next_step": {
      "type": "string",
      "description": "Useful next action for the caller."
    },
    "search_runtime": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local_first",
            "hosted_fallback",
            "hosted"
          ]
        },
        "fallback_used": {
          "type": "boolean"
        },
        "hosted_search_calls": {
          "type": "number"
        },
        "local_failure_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "index_generated_at": {
          "type": "string"
        }
      },
      "required": [
        "mode",
        "fallback_used",
        "hosted_search_calls",
        "local_failure_code",
        "index_generated_at"
      ],
      "additionalProperties": false,
      "description": "Search execution path used for this recommendation."
    }
  },
  "required": [
    "task",
    "response_mode",
    "slot_count",
    "all_slots_resolved",
    "needs_clarification",
    "clarification_slots",
    "low_confidence_slots",
    "fallback_recommended",
    "results"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Retrieve one exact SVG icon using an exact ref returned by search_icons, recommend_icons, or preview_icons. Do not guess icon IDs. Use search_icons first if the user only described a concept. Returns SVG code, explicit public library labels, visual preview URL, and public semantic guidance for the exact icon.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Exact icon ID without the library prefix, for example \"database\", \"user-circle\", \"brain-circuit\", or \"arrow-down\"."
    },
    "library": {
      "type": "string",
      "description": "Required library key for the exact icon. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute."
    },
    "style": {
      "type": "string",
      "enum": [
        "any",
        "outline",
        "solid"
      ],
      "default": "any",
      "description": "Optional style preference. Material Symbols supports outline and solid. Other hosted libraries report their verified styles in list_libraries."
    }
  },
  "required": [
    "id",
    "library"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "icon": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Icon ID without the library prefix."
        },
        "name": {
          "type": "string",
          "description": "Human-readable icon name."
        },
        "library": {
          "type": "string",
          "description": "Source icon library key."
        },
        "library_key": {
          "type": "string",
          "description": "Source icon library key repeated for explicit agent display."
        },
        "library_name": {
          "type": "string",
          "description": "Public source library name, for example Supericons or Simple Icons."
        },
        "library_label": {
          "type": "string",
          "description": "Public source library label, for example Supericons (si)."
        },
        "libraryName": {
          "type": "string",
          "description": "Legacy camelCase public source library name."
        },
        "icon_ref": {
          "type": "string",
          "description": "Stable icon reference in library:id format."
        },
        "icon_preview_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Browser URL for visual inspection of this icon."
        },
        "search_preview_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Browser URL for visual inspection of the source search results."
        },
        "type": {
          "type": "string",
          "description": "Icon asset type, normally svg."
        },
        "style": {
          "type": "string",
          "description": "Icon style such as outline or solid."
        },
        "svg": {
          "type": "string",
          "description": "Inline SVG markup for the icon."
        },
        "semantic": {
          "anyOf": [
            {
              "type": "object",
              "additionalProperties": {}
            },
            {
              "type": "null"
            }
          ],
          "description": "Public semantic guidance for search and agent selection."
        }
      },
      "required": [
        "id",
        "name",
        "library",
        "library_key",
        "library_name",
        "library_label",
        "icon_ref",
        "icon_preview_url",
        "type",
        "style",
        "svg"
      ],
      "additionalProperties": false,
      "description": "Exact matching icon when found."
    },
    "error": {
      "type": "string",
      "description": "Recoverable error message when no exact icon is found."
    },
    "code": {
      "type": "string",
      "description": "Stable error code when the exact icon is unavailable."
    },
    "hint": {
      "type": "string",
      "description": "Plain-language explanation of how to recover."
    },
    "next_step": {
      "type": "string",
      "description": "Recommended next tool action."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether repeating the same exact lookup may succeed."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Refine an icon result set or preview known icon refs returned by another Supericons tool. Use search_icons first for normal icon requests. Long icon lists are accepted and safely truncated to 12. Returns ready-to-use Markdown, a hosted preview fallback, a direct PNG image URL, and, when requested, an MCP image contact sheet.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Optional search query to preview visually, for example \"license plate recognition camera scan car\"."
    },
    "icon_refs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Optional fixed icon refs in library:id format. Arrays, a single ref, and comma-separated refs are accepted. Up to 100 are accepted, 24 appear on the browser preview, and 12 are rendered inline. Larger lists are safely truncated with a warning."
    },
    "library": {
      "$ref": "#/properties/query",
      "description": "Optional library key. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute."
    },
    "style": {
      "$ref": "#/properties/query",
      "default": "any",
      "description": "Optional style preference. Unsupported values are ignored with a warning."
    },
    "locale": {
      "$ref": "#/properties/query",
      "description": "Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th. Unsupported values are ignored with a warning."
    },
    "limit": {
      "type": [
        "number",
        "string"
      ],
      "default": 12,
      "description": "Requested inline icon count. Values outside 1 to 12 are safely clamped with a warning. Numeric strings are accepted."
    },
    "include_image": {
      "type": "boolean",
      "default": true,
      "description": "When true, include a PNG contact sheet as MCP image content. Boolean strings are accepted. A preview_url is always returned."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": [
        "string",
        "null"
      ],
      "description": "Search query used for the visual preview, if any."
    },
    "preview_url": {
      "type": "string",
      "description": "Browser URL for visual inspection."
    },
    "image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Direct PNG URL for clients or Markdown renderers that can show remote images."
    },
    "markdown_image": {
      "type": [
        "string",
        "null"
      ],
      "description": "Ready-made Markdown image snippet for final answers in clients that render remote Markdown images."
    },
    "image_included": {
      "type": "boolean",
      "description": "Whether this response includes MCP image content."
    },
    "rendered_count": {
      "type": "number",
      "description": "Number of icons rendered in the inline preview."
    },
    "browser_preview_count": {
      "type": "number",
      "description": "Number of accepted icon refs available at preview_url."
    },
    "truncated_from": {
      "type": "number",
      "description": "Original icon ref count when the input was truncated."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Unsupported optional inputs that were safely ignored."
    },
    "next_step": {
      "type": "string",
      "description": "Useful next action for the caller."
    },
    "client_display_note": {
      "type": "string",
      "description": "Plain-language note for clients that do not render images inline."
    },
    "suggested_response_markdown": {
      "type": "string",
      "description": "Ready-to-use answer with the image, refs, and browser fallback link."
    },
    "error": {
      "type": "string",
      "description": "Recoverable error message when preview inputs are missing or invalid."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Icon ID without the library prefix."
          },
          "name": {
            "type": "string",
            "description": "Human-readable icon name."
          },
          "library": {
            "type": "string",
            "description": "Source icon library key."
          },
          "library_key": {
            "type": "string",
            "description": "Source icon library key repeated for explicit agent display."
          },
          "library_name": {
            "type": "string",
            "description": "Public source library name, for example Supericons or Simple Icons."
          },
          "library_label": {
            "type": "string",
            "description": "Public source library label, for example Supericons (si)."
          },
          "icon_ref": {
            "type": "string",
            "description": "Stable icon reference in library:id format."
          },
          "icon_preview_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Browser URL for visual inspection of this icon."
          },
          "style": {
            "type": "string",
            "description": "Icon style such as outline or solid."
          },
          "semantic": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ],
            "description": "Public semantic guidance for search and agent selection."
          }
        },
        "required": [
          "id",
          "name",
          "library",
          "library_key",
          "icon_ref"
        ],
        "additionalProperties": false
      },
      "description": "Icons included in the visual preview."
    }
  },
  "required": [
    "preview_url",
    "image_included",
    "rendered_count",
    "browser_preview_count",
    "next_step",
    "client_display_note",
    "results"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the free icon libraries available through the hosted Supericons MCP server. Use this before filtering by library or when a user asks which icon libraries are supported.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "libraries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Library key used in tool calls."
          },
          "name": {
            "type": "string",
            "description": "Human-readable library name."
          },
          "label": {
            "type": "string",
            "description": "Human-readable library label with key, for example Supericons (si)."
          },
          "description": {
            "type": "string",
            "description": "Brief public description of the icon library."
          },
          "count": {
            "type": "number",
            "description": "Number of icons in the library."
          },
          "outlineCount": {
            "type": "number",
            "description": "Number of outline icons served by the hosted MCP server."
          },
          "solidCount": {
            "type": "number",
            "description": "Number of solid icons served by the hosted MCP server."
          },
          "supportedStyles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "outline",
                "solid"
              ]
            },
            "description": "Styles verified on the hosted serving path."
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "count",
          "outlineCount",
          "solidCount",
          "supportedStyles"
        ],
        "additionalProperties": false
      },
      "description": "Free icon libraries available through this hosted MCP server."
    },
    "publicRecordCount": {
      "type": "number",
      "description": "Number of public semantic icon records searchable through the hosted MCP server."
    }
  },
  "required": [
    "libraries",
    "publicRecordCount"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}