Supericons

Search Icons

search_icons

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of icons from 1 to 50. Numeric strings are accepted.
`query`	Yes	Icon concept or search phrase, for example "database", "user profile", "chill", "trash", "upload cloud", "AI model", or "beautiful".
`style`	No	Optional style preference. Unsupported values are ignored with a warning.	any
`locale`	No	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.
`library`	No	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`	No	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.
`include_query_frame`	No	Optional public-safe diagnostics for query understanding. Boolean strings are accepted. Leave false for normal compact responses.

Output Schema

TableJSON Schema

Name	Required	Description
`code`	No	Stable code for a structured no-result.
`hint`	No	Plain-language recovery hint for a structured no-result.
`error`	No	Plain-language error for a structured no-result.
`status`	No	HTTP status from an upstream search failure.
`details`	No	Structured rate-limit or upstream failure details.
`results`	Yes	Matching icons with SVG code and semantic guidance.
`warnings`	No	Unsupported optional inputs that were safely ignored.
`image_url`	No	Direct PNG URL when usable icons exist.
`next_step`	Yes	Useful next action for the caller.
`retryable`	No	Whether changing the query or filters may produce a result.
`limit_scope`	No	Allowance scope reported by a rate limit.
`preview_url`	No	Browser URL for visual inspection of this search result set.
`query_frame`	No	Optional public-safe query understanding diagnostics.
`library_mode`	Yes	Library behavior used for this search.
`outcome_type`	No	Whether this response contains results, an honest no-match, or a tool failure.
`result_count`	No	Number of verified icons returned by this search.
`markdown_image`	No	Ready-made Markdown image when usable icons exist.
`search_runtime`	No	Search execution path used for this request.
`top_result_ref`	No	Top ordered icon ref when results exist.
`requested_library`	Yes	Preferred or required library, when supplied.
`retry_after_seconds`	No	Seconds to wait before retrying a rate-limited search.
`result_interpretation`	No	Plain-language guidance for interpreting this result count and outcome.
`suggested_response_markdown`	Yes	Compact answer that accurately reflects this response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedAug 31, 2026
- addedOutput schema / properties / search_runtime / properties / hosted_result_count
```
Added value: +{
+  "type": "number"
+}
```
- addedOutput schema / properties / search_runtime / properties / local_attempt_count
```
Added value: +{
+  "type": "number"
+}
```
- addedOutput schema / properties / search_runtime / properties / local_result_count
```
Added value: +{
+  "type": "number"
+}
```
- addedOutput schema / properties / search_runtime / properties / local_retry_recovered
```
Added value: +{
+  "type": "boolean"
+}
```
- addedOutput schema / properties / search_runtime / properties / local_retry_used
```
Added value: +{
+  "type": "boolean"
+}
```

Changed4 schema fields changedAug 22, 2026

addedOutput schema / properties / search_runtime / properties / degraded
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / search_runtime / properties / hosted_circuit_state

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "closed",
+        "open",
+        "half_open_ready"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / search_runtime / properties / hosted_failure_code
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
addedOutput schema / properties / search_runtime / properties / hosted_failure_status
```
Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}
```

Changed1 schema field changedAug 3, 2026

changedInput schema / properties / library_mode / description

Previous value: -"Optional library behavior. Omit it to use all when no library is named and strict when a library is named. Prefer requires a named library. All searches every eligible library. Unsupported or incomplete combinations are safely normalized with a warning."New value: +"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."

Changed7 schema fields changedJul 31, 2026

changedInput schema / properties / library / description

Previous value: -"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."New value: +"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."

removedInput schema / properties / library_mode / default
```
Removed value: -"strict"
```

changedInput schema / properties / library_mode / description

Previous value: -"Library behavior. Strict stays inside the requested library, prefer puts it first and includes labeled alternatives, and all searches every eligible library. Unsupported values are ignored with a warning."New value: +"Optional library behavior. Omit it to use all when no library is named and strict when a library is named. Prefer requires a named library. All searches every eligible library. Unsupported or incomplete combinations are safely normalized with a warning."

addedOutput schema / properties / outcome_type

Added value: +{
+  "description": "Whether this response contains results, an honest no-match, or a tool failure.",
+  "enum": [
+    "results",
+    "no_match",
+    "tool_error"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / result_count

Added value: +{
+  "description": "Number of verified icons returned by this search.",
+  "type": "number"
+}

addedOutput schema / properties / result_interpretation

Added value: +{
+  "description": "Plain-language guidance for interpreting this result count and outcome.",
+  "type": "string"
+}

addedOutput schema / properties / top_result_ref

Added value: +{
+  "description": "Top ordered icon ref when results exist.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed2 schema fields changedJul 22, 2026

addedOutput schema / properties / search_runtime / properties / local_fusion_used
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / properties / search_runtime / properties / mode / enum

Previous value: -[
-  "local_first",
-  "local_fallback",
-  "hosted_fallback",
-  "hosted"
-]New value: +[
+  "local_first",
+  "local_fallback",
+  "hosted_fallback",
+  "hosted",
+  "hosted_fused"
+]

Changed1 schema field changedJul 22, 2026

changedOutput schema / properties / search_runtime / properties / mode / enum

Previous value: -[
-  "local_first",
-  "hosted_fallback",
-  "hosted"
-]New value: +[
+  "local_first",
+  "local_fallback",
+  "hosted_fallback",
+  "hosted"
+]

Changed1 schema field changedJul 21, 2026

addedOutput schema / properties / search_runtime

Added value: +{
+  "additionalProperties": false,
+  "description": "Search execution path used for this request.",
+  "properties": {
+    "fallback_used": {
+      "type": "boolean"
+    },
+    "hosted_search_calls": {
+      "type": "number"
+    },
+    "index_generated_at": {
+      "type": "string"
+    },
+    "local_failure_code": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "mode": {
+      "enum": [
+        "local_first",
+        "hosted_fallback",
+        "hosted"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "mode",
+    "fallback_used",
+    "hosted_search_calls",
+    "local_failure_code",
+    "index_generated_at"
+  ],
+  "type": "object"
+}

Changed29 schema fields changedJul 21, 2026

changedInput schema / properties / include_query_frame / description

Previous value: -"Optional public-safe diagnostics for query understanding. Leave false for normal compact responses."New value: +"Optional public-safe diagnostics for query understanding. Boolean strings are accepted. Leave false for normal compact responses."

addedInput schema / properties / library_mode / $ref
```
Added value: +"#/properties/library"
```

changedInput schema / properties / library_mode / description

Previous value: -"Library behavior. Strict stays inside the requested library, prefer puts it first and includes labeled alternatives, and all searches every eligible library."New value: +"Library behavior. Strict stays inside the requested library, prefer puts it first and includes labeled alternatives, and all searches every eligible library. Unsupported values are ignored with a warning."

removedInput schema / properties / library_mode / enum

Removed value: -[
-  "strict",
-  "prefer",
-  "all"
-]

removedInput schema / properties / library_mode / type
```
Removed value: -"string"
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of icons to return. Use 5-10 for browsing and 1-3 for quick agent choices."New value: +"Maximum number of icons from 1 to 50. Numeric strings are accepted."

addedInput schema / properties / locale / $ref
```
Added value: +"#/properties/library"
```

changedInput schema / properties / locale / description

Previous value: -"Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th."New value: +"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."

removedInput schema / properties / locale / enum

Removed value: -[
-  "zh-Hans",
-  "zh-Hant",
-  "ja",
-  "ko",
-  "es",
-  "de",
-  "pt",
-  "ar",
-  "hi",
-  "vi",
-  "th"
-]

removedInput schema / properties / locale / type
```
Removed value: -"string"
```
addedInput schema / properties / query / minLength
```
Added value: +1
```
addedInput schema / properties / style / $ref
```
Added value: +"#/properties/library"
```

changedInput schema / properties / style / description

Previous value: -"Optional style preference. Material Symbols supports outline and solid. Other hosted libraries report their verified styles in list_libraries."New value: +"Optional style preference. Unsupported values are ignored with a warning."

removedInput schema / properties / style / enum

Removed value: -[
-  "any",
-  "outline",
-  "solid"
-]

removedInput schema / properties / style / type
```
Removed value: -"string"
```

addedOutput schema / properties / code

Added value: +{
+  "description": "Stable code for a structured no-result.",
+  "type": "string"
+}

addedOutput schema / properties / details

Added value: +{
+  "additionalProperties": {},
+  "description": "Structured rate-limit or upstream failure details.",
+  "type": "object"
+}

addedOutput schema / properties / error

Added value: +{
+  "description": "Plain-language error for a structured no-result.",
+  "type": "string"
+}

addedOutput schema / properties / hint

Added value: +{
+  "description": "Plain-language recovery hint for a structured no-result.",
+  "type": "string"
+}

addedOutput schema / properties / image_url

Added value: +{
+  "description": "Direct PNG URL when usable icons exist.",
+  "type": "string"
+}

addedOutput schema / properties / limit_scope

Added value: +{
+  "description": "Allowance scope reported by a rate limit.",
+  "type": "string"
+}

addedOutput schema / properties / markdown_image

Added value: +{
+  "description": "Ready-made Markdown image when usable icons exist.",
+  "type": "string"
+}

addedOutput schema / properties / next_step

Added value: +{
+  "description": "Useful next action for the caller.",
+  "type": "string"
+}

addedOutput schema / properties / retry_after_seconds

Added value: +{
+  "description": "Seconds to wait before retrying a rate-limited search.",
+  "type": "number"
+}

addedOutput schema / properties / retryable

Added value: +{
+  "description": "Whether changing the query or filters may produce a result.",
+  "type": "boolean"
+}

addedOutput schema / properties / status

Added value: +{
+  "description": "HTTP status from an upstream search failure.",
+  "type": "number"
+}

addedOutput schema / properties / suggested_response_markdown

Added value: +{
+  "description": "Compact answer that accurately reflects this response.",
+  "type": "string"
+}

addedOutput schema / properties / warnings

Added value: +{
+  "description": "Unsupported optional inputs that were safely ignored.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "results",
-  "library_mode",
-  "requested_library"
-]New value: +[
+  "results",
+  "library_mode",
+  "requested_library",
+  "suggested_response_markdown",
+  "next_step"
+]

Changed5 schema fields changedJul 15, 2026

addedInput schema / properties / library_mode

Added value: +{
+  "default": "strict",
+  "description": "Library behavior. Strict stays inside the requested library, prefer puts it first and includes labeled alternatives, and all searches every eligible library.",
+  "enum": [
+    "strict",
+    "prefer",
+    "all"
+  ],
+  "type": "string"
+}

changedInput schema / properties / style / description

Previous value: -"Optional style preference. Use \"any\" unless the user asks for outline or solid icons."New value: +"Optional style preference. Material Symbols supports outline and solid. Other hosted libraries report their verified styles in list_libraries."

addedOutput schema / properties / library_mode

Added value: +{
+  "description": "Library behavior used for this search.",
+  "enum": [
+    "strict",
+    "prefer",
+    "all"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / requested_library

Added value: +{
+  "description": "Preferred or required library, when supplied.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "results"
-]New value: +[
+  "results",
+  "library_mode",
+  "requested_library"
+]

Changed5 schema fields changedJul 15, 2026

removedInput schema / properties / library_mode

Removed value: -{
-  "default": "strict",
-  "description": "Library behavior. Strict stays inside the requested library, prefer puts it first and includes labeled alternatives, and all searches every eligible library.",
-  "enum": [
-    "strict",
-    "prefer",
-    "all"
-  ],
-  "type": "string"
-}

changedInput schema / properties / style / description

Previous value: -"Optional style preference. Material Symbols supports outline and solid. Other hosted libraries report their verified styles in list_libraries."New value: +"Optional style preference. Use \"any\" unless the user asks for outline or solid icons."

removedOutput schema / properties / library_mode

Removed value: -{
-  "description": "Library behavior used for this search.",
-  "enum": [
-    "strict",
-    "prefer",
-    "all"
-  ],
-  "type": "string"
-}

removedOutput schema / properties / requested_library

Removed value: -{
-  "description": "Preferred or required library, when supplied.",
-  "type": [
-    "string",
-    "null"
-  ]
-}

changedOutput schema / required

Previous value: -[
-  "results",
-  "library_mode",
-  "requested_library"
-]New value: +[
+  "results"
+]

Changed5 schema fields changedJul 15, 2026

addedInput schema / properties / library_mode

Added value: +{
+  "default": "strict",
+  "description": "Library behavior. Strict stays inside the requested library, prefer puts it first and includes labeled alternatives, and all searches every eligible library.",
+  "enum": [
+    "strict",
+    "prefer",
+    "all"
+  ],
+  "type": "string"
+}

changedInput schema / properties / style / description

Previous value: -"Optional style preference. Use \"any\" unless the user asks for outline or solid icons."New value: +"Optional style preference. Material Symbols supports outline and solid. Other hosted libraries report their verified styles in list_libraries."

addedOutput schema / properties / library_mode

Added value: +{
+  "description": "Library behavior used for this search.",
+  "enum": [
+    "strict",
+    "prefer",
+    "all"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / requested_library

Added value: +{
+  "description": "Preferred or required library, when supplied.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "results"
-]New value: +[
+  "results",
+  "library_mode",
+  "requested_library"
+]

Changed10 schema fields changedJul 3, 2026

changedInput schema / properties / library / description

Previous value: -"Optional library key. Supported values include si, lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute."New value: +"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."

addedOutput schema / properties / preview_url

Added value: +{
+  "description": "Browser URL for visual inspection of this search result set.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / icon_preview_url

Added value: +{
+  "description": "Browser URL for visual inspection of this icon.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / icon_ref

Added value: +{
+  "description": "Stable icon reference in library:id format.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / libraryName

Added value: +{
+  "description": "Legacy camelCase public source library name.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / library_key

Added value: +{
+  "description": "Source icon library key repeated for explicit agent display.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / library_label

Added value: +{
+  "description": "Public source library label, for example Supericons (si).",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / library_name

Added value: +{
+  "description": "Public source library name, for example Supericons or Simple Icons.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / search_preview_url

Added value: +{
+  "description": "Browser URL for visual inspection of the source search results.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "id",
-  "name",
-  "library",
-  "type",
-  "style",
-  "svg"
-]New value: +[
+  "id",
+  "name",
+  "library",
+  "library_key",
+  "library_name",
+  "library_label",
+  "icon_ref",
+  "icon_preview_url",
+  "type",
+  "style",
+  "svg"
+]

Changed2 schema fields changedJul 2, 2026

addedInput schema / properties / include_query_frame

Added value: +{
+  "default": false,
+  "description": "Optional public-safe diagnostics for query understanding. Leave false for normal compact responses.",
+  "type": "boolean"
+}

addedOutput schema / properties / query_frame

Added value: +{
+  "additionalProperties": {},
+  "description": "Optional public-safe query understanding diagnostics.",
+  "type": "object"
+}

Changed1 schema field changedJun 27, 2026

changedInput schema / properties / library / description

Previous value: -"Optional library key. Supported values include lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute."New value: +"Optional library key. Supported values include si, lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute."

Changed1 schema field changedMay 13, 2026

addedInput schema / properties / locale

Added value: +{
+  "description": "Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th.",
+  "enum": [
+    "zh-Hans",
+    "zh-Hant",
+    "ja",
+    "ko",
+    "es",
+    "de",
+    "pt",
+    "ar",
+    "hi",
+    "vi",
+    "th"
+  ],
+  "type": "string"
+}

First observedMay 5, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations are all false, so the description carries the full behavioral burden. It thoroughly discloses match behavior (paste-ready answer, direct preview image, Markdown), no-match behavior (honest structured no-result with next step, no fabricated icon), and library-mode semantics. The si/Supericons disambiguation also prevents a likely misuse. This exceeds the minimum expected transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: the primary-role statement, search capability, match/no-match response behavior, library-mode guidance, and the si/Supericons warning. It is front-loaded with the most important usage directive and remains compact for a tool with 7 parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for correct invocation: it covers query style, result behavior, failure handling, library selection, and a known naming trap. The output schema exists, so detailed return-value documentation is already available to the agent. No critical operational context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema by explaining the prefer/strict library_mode behavior, the condition for strict usage, and the si key ambiguity. This additional context raises the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Use this as the main icon tool' and names a specific action and resource: searching 20,000+ curated SVG icons across 11 libraries by meaning, labels, visual description, tags, and synonyms. It clearly establishes this as the primary search tool and distinguishes it from siblings like get_icon and list_libraries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use this tool ('main icon tool') and how to choose library modes: 'If you choose a library yourself, use prefer' and 'Use strict only when the user explicitly requires that library.' It does not explicitly compare against sibling tools, but the primary-tool framing and mode rules provide clear usable context.

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

All Supericons tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Search Icons

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources