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

Behavior5/5

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

The description goes far beyond the false hints in annotations by detailing ambiguity resolution via needs_clarification, plain-language error recovery with next steps, output structure with alternatives and preview URLs, and the specific 'si means Supericons, not Simple Icons' caveat. This substantially enriches behavioral understanding.

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 a compact paragraph where every sentence adds value, starting with the core purpose, then covering edge cases and error behavior. It avoids redundancy with schema descriptions and is appropriately front-loaded.

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 a tool with 8 parameters, full schema coverage, and an output schema, the description covers key aspects: batch size limits, ambiguity handling, error recovery, output format, and a critical library name disambiguation. The only minor gap is sibling differentiation, but that is not essential given the clear purpose and output schema.

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

Parameters5/5

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

Even though schema coverage is 100%, the description adds crucial meaning beyond the schema: it clarifies the si library key, notes that numeric strings are accepted for limit_per_slot, and explains clamping and warning behaviors. This directly improves parameter usage.

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 'Recommend a coherent icon set for up to 20 named UI slots in one call,' clearly stating the verb (recommend), resource (icon set), and scope (batch). It distinguishes from siblings like search_icons by emphasizing coherence and multi-slot batching.

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 indicates the tool's context (batch icon recommendation with task context and ambiguity handling), but does not explicitly state when to use it instead of sibling tools like search_icons or list_libraries. The context is clear, but explicit exclusions or alternative references are missing.

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

Disambiguation5/5

Each tool has a clearly distinct role: search finds icons, recommend builds sets for UI slots, preview refines result sets, get retrieves exact SVG code, and list_libraries enumerates available libraries. Despite some overlapping concepts like 'preview' and 'get', the descriptions explicitly differentiate when to use each one.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: list_libraries, search_icons, recommend_icons, preview_icons, get_icon. The naming style is uniform and predictable across the entire set.

Tool Count5/5

Five tools is well-scoped for an icon service: library discovery, search, recommendation, preview, and exact retrieval. Each tool addresses a necessary part of the icon selection workflow without unnecessary bloat.

Completeness5/5

The tool surface covers the full icon workflow: discover libraries, search by meaning, get multi-icon recommendations, preview sets in Markdown/PNG, and fetch exact SVG code. There are no obvious missing operations for the stated purpose.

Resources

Need Help?