Supericons

Recommend Icons

recommend_icons

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`task`	No	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`	No	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.
`style`	No	Optional style preference. Unsupported values are ignored with a warning.	any
`locale`	No	Optional locale for multilingual slot labels. Unsupported values are ignored with a warning.
`library`	No	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.
`response_mode`	No	Response size mode: plan, assets, or full. Unsupported values use plan with a warning.	plan
`limit_per_slot`	No	Number of choices per slot. Values outside 1 to 5 are clamped with a warning. Numeric strings are accepted.
`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 error code for programmatic recovery.
`hint`	No	Plain-language recovery instruction.
`task`	Yes	Original UI task.
`error`	No	Plain-language reason the recommendation did not complete.
`style`	No	Style preference used for recommendations.
`status`	No	HTTP status from a hosted dependency failure.
`details`	No	Structured limits or failure details.
`library`	No	Library filter used for recommendations, if provided.
`results`	Yes	Recommended icon choices grouped by requested UI slot.
`warnings`	No	Unsupported optional inputs that were safely ignored or clamped.
`next_step`	No	Useful next action for the caller.
`retryable`	No	Whether a corrected or later request may succeed.
`slot_count`	Yes	Number of UI slots requested.
`preview_url`	No	Browser URL for visual inspection of the recommended icon set.
`query_frame`	No	Optional public-safe query understanding diagnostics for the task.
`response_mode`	Yes	Response size mode used for this recommendation.
`search_runtime`	No	Search execution path used for this recommendation.
`all_slots_resolved`	Yes	Whether every requested slot received a recommendation without clarification.
`clarification_slots`	Yes	Slots that need the caller to choose an interpretation.
`needs_clarification`	Yes	Whether one or more ambiguous slots require more context.
`retry_after_seconds`	No	Seconds to wait before retrying a rate-limited recommendation.
`fallback_recommended`	Yes	Whether the caller should consider direct search or clarification.
`low_confidence_slots`	Yes	Slots whose result is missing or has low confidence.
`suggested_response_markdown`	No	Plain-language explanation suitable for the agent response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed43 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 / $ref
```
Added value: +"#/properties/task"
```
removedInput schema / properties / library / type
```
Removed value: -"string"
```

changedInput schema / properties / limit_per_slot / description

Previous value: -"Number of choices to return for each slot. Use 1 for a final pick or 2-3 when the user wants alternatives."New value: +"Number of choices per slot. Values outside 1 to 5 are clamped with a warning. Numeric strings are accepted."

removedInput schema / properties / limit_per_slot / maximum
```
Removed value: -5
```
removedInput schema / properties / limit_per_slot / minimum
```
Removed value: -1
```

changedInput schema / properties / limit_per_slot / type

Previous value: -"number"New value: +[
+  "number",
+  "string"
+]

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

changedInput schema / properties / locale / description

Previous value: -"Optional locale for multilingual slot labels. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th."New value: +"Optional locale for multilingual slot labels. 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 / response_mode / $ref
```
Added value: +"#/properties/task"
```

changedInput schema / properties / response_mode / description

Previous value: -"Response size mode. Use plan for compact icon IDs and reasons, assets to include SVG only for each top recommendation, or full to include SVG and semantic payloads for all returned choices."New value: +"Response size mode: plan, assets, or full. Unsupported values use plan with a warning."

removedInput schema / properties / response_mode / enum

Removed value: -[
-  "plan",
-  "assets",
-  "full"
-]

removedInput schema / properties / response_mode / type
```
Removed value: -"string"
```
addedInput schema / properties / slots / default
```
Added value: +[]
```

changedInput schema / properties / slots / description

Previous value: -"List of UI slots to fill, for example [\"model\", \"prompt\", \"dataset\", \"evaluation\"]."New value: +"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."

removedInput schema / properties / slots / items / minLength
```
Removed value: -1
```
removedInput schema / properties / slots / maxItems
```
Removed value: -12
```
removedInput schema / properties / slots / minItems
```
Removed value: -1
```
addedInput schema / properties / style / $ref
```
Added value: +"#/properties/task"
```

changedInput schema / properties / style / description

Previous value: -"Optional style preference. Use \"outline\" for most sidebar and toolbar icon sets unless the user asks otherwise."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"
```
addedInput schema / properties / task / default
```
Added value: +""
```

changedInput schema / properties / task / description

Previous value: -"Overall UI task, for example \"choose icons for an AI dashboard sidebar\" or \"select bottom navigation icons for a finance app\"."New value: +"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."

removedInput schema / required

Removed value: -[
-  "task",
-  "slots"
-]

addedOutput schema / properties / all_slots_resolved

Added value: +{
+  "description": "Whether every requested slot received a recommendation without clarification.",
+  "type": "boolean"
+}

addedOutput schema / properties / code

Added value: +{
+  "description": "Stable error code for programmatic recovery.",
+  "type": "string"
+}

addedOutput schema / properties / details

Added value: +{
+  "additionalProperties": {},
+  "description": "Structured limits or failure details.",
+  "type": "object"
+}

addedOutput schema / properties / error

Added value: +{
+  "description": "Plain-language reason the recommendation did not complete.",
+  "type": "string"
+}

addedOutput schema / properties / fallback_recommended

Added value: +{
+  "description": "Whether the caller should consider direct search or clarification.",
+  "type": "boolean"
+}

addedOutput schema / properties / hint

Added value: +{
+  "description": "Plain-language recovery instruction.",
+  "type": "string"
+}

addedOutput schema / properties / low_confidence_slots

Added value: +{
+  "description": "Slots whose result is missing or has low confidence.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / next_step

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

addedOutput schema / properties / response_mode

Added value: +{
+  "description": "Response size mode used for this recommendation.",
+  "enum": [
+    "plan",
+    "assets",
+    "full"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / retry_after_seconds

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

addedOutput schema / properties / retryable

Added value: +{
+  "description": "Whether a corrected or later request may succeed.",
+  "type": "boolean"
+}

addedOutput schema / properties / search_runtime

Added value: +{
+  "additionalProperties": false,
+  "description": "Search execution path used for this recommendation.",
+  "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"
+}

addedOutput schema / properties / status

Added value: +{
+  "description": "HTTP status from a hosted dependency failure.",
+  "type": "number"
+}

addedOutput schema / properties / suggested_response_markdown

Added value: +{
+  "description": "Plain-language explanation suitable for the agent response.",
+  "type": "string"
+}

addedOutput schema / properties / warnings

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

changedOutput schema / required

Previous value: -[
-  "task",
-  "slot_count",
-  "needs_clarification",
-  "clarification_slots",
-  "results"
-]New value: +[
+  "task",
+  "response_mode",
+  "slot_count",
+  "all_slots_resolved",
+  "needs_clarification",
+  "clarification_slots",
+  "low_confidence_slots",
+  "fallback_recommended",
+  "results"
+]

Changed3 schema fields changedJul 15, 2026

addedOutput schema / properties / clarification_slots

Added value: +{
+  "description": "Slots that need the caller to choose an interpretation.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / needs_clarification

Added value: +{
+  "description": "Whether one or more ambiguous slots require more context.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "task",
-  "slot_count",
-  "results"
-]New value: +[
+  "task",
+  "slot_count",
+  "needs_clarification",
+  "clarification_slots",
+  "results"
+]

Changed3 schema fields changedJul 15, 2026

removedOutput schema / properties / clarification_slots

Removed value: -{
-  "description": "Slots that need the caller to choose an interpretation.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

removedOutput schema / properties / needs_clarification

Removed value: -{
-  "description": "Whether one or more ambiguous slots require more context.",
-  "type": "boolean"
-}

changedOutput schema / required

Previous value: -[
-  "task",
-  "slot_count",
-  "needs_clarification",
-  "clarification_slots",
-  "results"
-]New value: +[
+  "task",
+  "slot_count",
+  "results"
+]

Changed3 schema fields changedJul 15, 2026

addedOutput schema / properties / clarification_slots

Added value: +{
+  "description": "Slots that need the caller to choose an interpretation.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / needs_clarification

Added value: +{
+  "description": "Whether one or more ambiguous slots require more context.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "task",
-  "slot_count",
-  "results"
-]New value: +[
+  "task",
+  "slot_count",
+  "needs_clarification",
+  "clarification_slots",
+  "results"
+]

Changed2 schema fields changedJul 3, 2026

changedInput schema / properties / library / description

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

addedOutput schema / properties / preview_url

Added value: +{
+  "description": "Browser URL for visual inspection of the recommended icon set.",
+  "type": "string"
+}

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 for the task.",
+  "type": "object"
+}

Changed1 schema field changedJun 27, 2026

changedInput schema / properties / library / description

Previous value: -"Optional library key when the user wants a consistent icon family. Supported values include lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute."New value: +"Optional library key when the user wants a consistent icon family. Supported values include si, lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute."

Changed1 schema field changedMay 22, 2026

addedInput schema / properties / response_mode

Added value: +{
+  "default": "plan",
+  "description": "Response size mode. Use plan for compact icon IDs and reasons, assets to include SVG only for each top recommendation, or full to include SVG and semantic payloads for all returned choices.",
+  "enum": [
+    "plan",
+    "assets",
+    "full"
+  ],
+  "type": "string"
+}

Changed1 schema field changedMay 13, 2026

addedInput schema / properties / locale

Added value: +{
+  "description": "Optional locale for multilingual slot labels. 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?

With all annotations false, the description carries the full burden and does so thoroughly. It states behavior for insufficient context ('returns needs_clarification with labeled interpretation options instead of guessing'), error handling ('plain-language reason and a next step'), and a specific disambiguation ('Library key si means Supericons, not Simple Icons'). This goes beyond annotations and adds significant behavioral insights.

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?

The description is five sentences, each carrying essential information without fluff. It front-loads the primary action, then covers edge cases, return values, and a key library clarification. No sentence is wasted, making it dense yet structured.

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?

Given the tool's complexity (8 parameters, no required params), the description is remarkably complete. It covers return behavior, error handling, clarification requests, and a library naming caveat. An output schema exists, so it does not need to explain return structure. The description addresses both typical and edge-case usage.

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 description coverage is 100%, so the baseline is 3. The description adds extra meaning beyond schema by noting the slot limit ('up to 20 named UI slots'), clarifying the 'si' library key, and mentioning response modes and alternatives. This added context raises it above the baseline.

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?

The description opens with a specific verb and resource: 'Recommend a coherent icon set for up to 20 named UI slots in one call.' This clearly differentiates from sibling tools like search_icons or get_icon by emphasizing the 'coherent set' and 'up to 20 named UI slots' scope.

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 implies usage context: use when you need multiple cohesive icon recommendations in one call. However, it does not explicitly mention alternatives or exclusion criteria, though the sibling list in context signals provides some differentiation. The phrase 'coherent icon set' and 'up to 20 named UI slots' effectively frames its intended use.

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.

Recommend Icons

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources