search
Find layer names and full text in saved Figma files or prepared workspace indexes, with ranked results, exact node refs, and coverage/page state.
Instructions
Ranked search of layer names and full text in one stored scope, including instance text overrides, text/boolean properties and nested swaps as REST nodes resolve them. Each result has an exact ref {sourceId, snapshotId, nodeId} (instance sublayer IDs work with inspect/nodes/export), origin stored or instance-effective, textSource, page, scopeRoot (a navigation container, not a screen claim), path, and matches with reasons and UTF-16 spans. coverage says whether the scope was fully indexed (ready) or a work limit stopped it (partial, totalRecords null); hasMore/nextCursor page the same candidates. Hidden layers and internal pages are excluded unless requested. Give file to read and hash that .fig now (nothing is written), or workspaceId to rank the workspace's prepared indexes of exactly this scope across its sources as one corpus (sourceId narrows it, refs keep each source's sourceId); a workspace search never builds: sources without a ready index are listed in sources with state pending, not_prepared, stale, incompatible or unreadable and the nextSteps index call, and coverage then says partial.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| crop | No | {x, y, width, height} in whole pixels of the query image (of the stored 256-pixel render for imageRef) | |
| file | No | the saved .fig to read now: a local path or gs://bucket/object; give file or workspaceId | |
| mode | No | text (default); semantic or hybrid with a configured local model (see models); with image or imageRef, visual (default without query) or hybrid (default with query: image plus text channels) | |
| node | No | stored scope root; default the document; narrow it when coverage is partial | 0:0 |
| type | No | Figma node types to keep, comma-separated, e.g. TEXT or TEXT,INSTANCE | |
| image | No | with workspaceId: a local PNG (at most 8 MiB, 4 MP) inside the server's roots to search by; read for this call only, never stored or sent anywhere. Not with imageRef | |
| limit | No | 1-200 results per page, default 20; independent of indexing work limits | |
| query | No | words or a phrase; case, width and accents fold, CJK matches by character pairs or a single character; no regex. Required unless image or imageRef is given | |
| cursor | No | nextCursor from the previous page of the same query, filters and snapshot; a workspace cursor lasts one hour (then cursor_expired) | |
| storage | No | absolute custom storage directory, only for a workspace kept outside the default storage; must be under the server's --storage-root | |
| imageRef | No | with workspaceId: {sourceId, snapshotId, nodeId} of a node in a search result, to search by its stored render; the snapshot must still be the source's current one. Not with image | |
| sourceId | No | with workspaceId, search only this registered source | |
| workspaceId | No | ws_... from the index tool: search its prepared indexes instead of reading a file | |
| includeHidden | No | also return hidden layers and instance copies hidden by overrides or properties | |
| includeInternal | No | also return layers on Figma's internal-only page |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | the query as given, its normalized phrase, mode and the whole tokens actually searched; an image search adds image (kind path|bytes|ref and crop, never the path), requestedMode and usedModes (text, semantic, visual_hash, visual_exact, visual_embedding) | |
| scope | No | ||
| state | No | workspace searches: ready, pending or not_prepared | |
| source | No | sourceId (opaque, from this path), snapshotId (sha256 of the exact .fig bytes decoded) and freshness: file-stamp reuse, not a per-query disk hash | |
| hasMore | Yes | ||
| ranking | No | ranking and tokenizer versions, field weights and tie order; an image search names its fusion (visual-rrf-1), channels and candidatesPerChannel | |
| results | Yes | ranked rows; in an image search each match names its basis (lexical, semantic, normalized_pixels, perceptual_hash, visual_embedding) and each row has visual {state rendered|failed|absent, bounds, diagnostics, diagnosticsTruncated, error} | |
| sources | No | workspace searches: each visible source's sourceId, state, snapshotId, freshness and active job | |
| coverage | Yes | complete, scannedRecords, totalRecords (null unless complete), layers.text.state ready|partial, layers.visual in image searches (hash and embedding state per source, ready|partial|pending|building|failed|stale|unavailable, and the approximate signal), layers.semantic in semantic and hybrid modes (state ready|partial|pending|unavailable, profileId, counts, reasons; workspace searches per source), layers.relations (per kind: ready or partial when built; stateless search builds contains, instance_of and variant_of and lists the others not_built, which says nothing about absence; library_identity relation_unavailable), reasons with counts, excluded hidden/internal matches, knownGaps and work limits | |
| nextSteps | No | workspace searches: the index or jobs calls that make more sources ready | |
| nextCursor | Yes | ||
| workspaceId | No | workspace searches only |