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

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. Lists of up to a few hundred slots return a structured split instruction; send at most 20 per call.
`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

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.

Changed1 schema field changedOct 23, 2026

changedInput schema / properties / slots / description

Previous 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."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. Lists of up to a few hundred slots return a structured split instruction; send at most 20 per call."

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.2/5.0

Behavior5/5

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

The description adds substantial behavioral context beyond the annotations: it discloses task-context narrowing, needs_clarification fallback with labeled options, plain-language error handling with next steps, per-slot recommendations plus alternatives, and preview URLs. These details help an agent understand how the tool behaves in ambiguous and failure cases.

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 front-loaded with the core purpose, then moves through ambiguity handling, error behavior, return shape, and a key naming clarification. Every sentence contributes useful information with no filler.

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?

For an 8-parameter recommendation tool with an output schema, the description covers the crucial behavioral edges: slot limits, clarification fallback, error recovery, return structure, and library-key ambiguity. The output schema can carry detailed return fields, so no major completeness gap remains.

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, but the description adds meaningful semantics not fully captured elsewhere, especially that 'si' means Supericons rather than Simple Icons and that invalid style, locale, response_mode, and limit values are handled with warnings or clamping. It does not explain the plan/assets/full modes in detail.

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

Purpose4/5

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

The description uses a specific verb and resource: 'Recommend a coherent icon set' for named UI slots, with a clear scope of up to 20 slots per call. It does not explicitly differentiate itself from sibling tools such as search_icons or preview_icons, so it falls short of a 5.

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

Usage Guidelines3/5

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

The description implies the tool's usage through 'for up to 20 named UI slots in one call' and explains clarification behavior when context is insufficient. However, it never states when to use this tool instead of alternatives like search_icons, get_icon, or preview_icons, leaving selection to inference.

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

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

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