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.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool targets a distinct stage of the icon workflow: list_libraries for discovery, search_icons for concept search, recommend_icons for UI slot sets, preview_icons for refining/previewing results, and get_icon for exact retrieval. The descriptions explicitly state when to use each tool, so there is little risk of misselection.

Naming Consistency5/5

All tool names follow a consistent lowercase snake_case verb_noun pattern: list, search, preview, recommend, get. The object nouns are plural for set-level operations and singular for exact retrieval, which is predictable and clear.

Tool Count5/5

Five tools is well-scoped for an icon retrieval server. Each tool serves a necessary and non-redundant function, and the set is neither bloated nor too thin.

Completeness5/5

The tool surface covers the full icon workflow: library discovery, semantic search, preview/refinement, exact SVG retrieval, and multi-slot recommendation. No-result and insufficient-context cases are handled with next steps, so there are no obvious dead ends for the stated domain.

Recommend Icons

Input Schema

Output Schema

TDQS

Glama MCP Gateway

TDQS

Resources