# search_icons

> Page: https://docs.plotwork.dev/mcp/tools/search-icons. Index of every page: https://docs.plotwork.dev/llms.txt

Find bundled icon names by keyword, idea, product, or abbreviation ("postgres", "token exchange", "s3", "cosmos db"). It is a single tool of the MCP server and the HTTP API, with the title "Search icons".

## TL;DR

| Question | Answer |
|---|---|
| What is it? | A single tool: it does one thing. |
| What does it do? | Find bundled icon names by keyword, idea, product, or abbreviation ("postgres", "token exchange", "s3", "cosmos db"). |
| How do I call it over HTTP? | [`GET /v1/icons`](https://docs.plotwork.dev/api/get-v1-icons.md) |
| Does it change anything? | No. It is read-only and idempotent, and it talks to nothing outside itself. It saves no file and returns its answer as data. |
| Which bounds apply? | None beyond the limits of each argument, which are in the schema below. |
| Where do I read its schema as data? | An MCP client gets the name, description, and JSON Schema of every tool from `tools/list`. |

## What it does

Find bundled icon names by keyword, idea, product, or abbreviation ("postgres", "token exchange", "s3", "cosmos db"). Returns set:name references, best first, at most 100, such as lucide:database, simple:postgresql, aws:lambda. Cloud products are in one set per provider (aws, gcp, azure, alibaba, oci, ibm, cloudflare, digitalocean, vercel), with every official aws, azure, and gcp icon; <provider>:cloud is the provider, for a group. Use it before setting icon= or a name in stack=. Search with the product name exactly as the user wrote it and take the first result; never invent a name, because an unknown icon is an error. For several names prefer map_icons: up to 40 in one call, and it never guesses. Hosted calls also find the organisation icons, as org:name.

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `q` | `string` | yes | Words to look for: a name such as "database", an idea such as "token exchange", or a cloud product such as "lambda" or "gke". at least 1 character; at most 64 characters. |
| `limit` | `integer` | no | Most names to return. minimum 1; maximum 100; default 20. |

## Result

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | `string` | yes | The query that was searched. |
| `items` | `string[]` | yes | Matching icon references as set:name, best match first. |

## Behavior hints

| Hint | Value |
|---|---|
| `readOnlyHint` | true |
| `destructiveHint` | false |
| `idempotentHint` | true |
| `openWorldHint` | false |

## See also

| Doc | Why |
|---|---|
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Every tool, with the workflows first |
| [`GET /v1/icons`](https://docs.plotwork.dev/api/get-v1-icons.md) | The same operation over HTTP |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | What the diagram source may contain |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The loop in practice |