Icons8

Search icons

search_icons

Read-only

Search for icons using the Icons8 API - the ONLY source for genuine Icons8 icons. Use English terms and consider Icon8's metaphors for better results.

SEARCH TIPS - Use these general approaches for better matches: • Use simple, descriptive terms (e.g., "home", "user", "settings") • Try action words for functions (e.g., "search", "download", "edit") • Use object names for items (e.g., "phone", "computer", "car") • Consider synonyms if first search doesn't work • Think about what the icon represents conceptually • Use single words or short phrases for best results

Args: query: The search term to find icons (use metaphors above for better results) ctx: MCP context for API access platform: Optional filter by platform/style (e.g., 'ios', 'fluent', 'color') category: Optional filter by category (e.g., 'transport', 'business') animated: Optional filter for icons that move. True returns only animated icons, False only static ones, and the default returns both. About one icon in fifty is animated. An animated result carries permanent animation.gif and animation.apng links that need no credential, so embedding one takes no further call. They render at the icon style's own size, whatever it is - do not upscale them, and call get_icon_animation if you need the number amount: Maximum number of results to return (default: 10) offset: Number of results to skip (for pagination)

Returns: {"icons": [...]} or {"error"}. Each entry of icons carries id: pass it as icon_id to get_icon_svg, get_icon_png_url or get_icon_animation. It is the only way to get an icon's id.

Input Schema

Name	Required	Description	Default
`query`	Yes
`amount`	No
`offset`	No
`animated`	No
`category`	No
`platform`	No

Output Schema

Name	Required	Description
`note`	No
`error`	No	Set only on failure.
`icons`	No	Matching icons. Absent when error is set.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "IconHit": {
+      "additionalProperties": true,
+      "properties": {
+        "animation": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Animation"
+        },
+        "category": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Category"
+        },
+        "commonName": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Commonname"
+        },
+        "id": {
+          "description": "Icon id. Pass it as icon_id to get_icon_svg, get_icon_png_url or get_icon_animation.",
+          "title": "Id",
+          "type": "string"
+        },
+        "isAnimated": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Present and true only for an animated icon, which get_icon_animation accepts.",
+          "title": "Isanimated"
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Name"
+        },
+        "platform": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Platform"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "title": "IconHit",
+      "type": "object"
+    }
+  },
+  "additionalProperties": true,
+  "properties": {
+    "error": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Set only on failure.",
+      "title": "Error"
+    },
+    "icons": {
+      "anyOf": [
+        {
+          "items": {
+            "$ref": "#/$defs/IconHit"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Matching icons. Absent when error is set.",
+      "title": "Icons"
+    },
+    "note": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Note"
+    }
+  },
+  "title": "IconSearchResult",
+  "type": "object"
+}

First observedOct 13, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the ~1-in-50 animation rarity, that animated results carry credential-free animation.gif/apng links needing no further call, that they must not be upscaled, and that the response is either {icons:[...]} or {error}. That is exactly the operational detail annotations cannot carry.

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

Conciseness3/5

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

Front-loaded and readable, but the six SEARCH TIPS bullets are largely paraphrases of each other ('simple, descriptive terms', 'action words', 'object names', 'synonyms', 'conceptually', 'single words'), so several sentences don't earn their place. Claiming to be 'the ONLY source for genuine Icons8 icons' adds no decision-relevant information.

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 six-parameter search tool with an output schema, it covers everything an agent needs: query formulation, all filters, pagination, the interlock with the get_icon_* siblings via icon_id, and the error return. Nothing required to invoke it correctly is missing.

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?

Schema description coverage is 0%, so the description carries the whole burden and does: platform and category get example values ('ios', 'fluent', 'color'; 'transport', 'business'), offset is explained as pagination, amount as a maximum/cap, and animated gets non-obvious tri-state semantics (True/False/default) plus the note that about one icon in fifty is animated.

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?

States a specific verb+resource ('Search for icons') and scopes the source ('using the Icons8 API'), and the Returns section routes to the correct sibling tools (get_icon_svg, get_icon_png_url, get_icon_animation). It never distinguishes itself from the parallel search_illustrations sibling, so an agent choosing between icon and illustration search gets no explicit help.

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?

Gives concrete usage context via the SEARCH TIPS block and names follow-up tools when more data is needed ('call get_icon_animation if you need the number'). There is no when-not-to-use guidance and no routing to search_illustrations or list_categories/list_platforms for browsing instead of searching.

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

All Icons8 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.

Resources

Need Help?