usages
Find exact inbound or outbound relations for a Figma node or resource—instances, variables, styles, images, prototype links, and library usage—within a stored file or prepared workspace scope.
Instructions
Exact relations of one node or resource in one stored scope, from the same effective index as search (nested instances and swaps included): direction in (default) lists the locations that point at it, out lists what it points at; with out, an instance_of, uses_style or binds_variable result whose cached library copy names it carries library {kind, namespace, key}, the selector the library argument takes. Relations: instance_of (instance to main component, recorded symbolData or resolved definition/swap), variant_of (component to its set; a COMPONENT_SET node also lists its known members and returns their instances with via), binds_variable (paint, effect and field variable bindings, local or library), uses_style, uses_image (a text range's style comes from the last row of its styleID, as REST nodes give it; its paint images and variables from the first such row with fills, as rendered), prototype_target (recorded transitions; never a claim that a flow is reachable) and contains (asked for explicitly). Every result keeps an exact ref {sourceId, snapshotId, nodeId}, relation, state (resolved, missing, unresolved, unsupported, external, recorded), basis (recorded or resolved), evidence, page, scopeRoot and path; names never establish identity. The definition may lie outside the scope; scope limits only the returned locations. No total is reported; coverage says complete or partial with reasons (work limits, hidden content not expanded, truncated members, library_identity unavailable), and nextCursor pages in a stable order (a workspace library cursor lasts one hour, then cursor_expired). Give file to read that .fig now (nothing is written), or workspaceId to read a source's prepared index of exactly this scope (never builds). Pass snapshotId from the ref you hold: another current snapshot is source_stale. With workspaceId, library {kind, namespace, key} instead of node or resource lists uses_library locations of that library component, style or variable across every visible source's prepared scope (basis cached_copy: the namespace comes from each file's cached copy); the definition stays unresolved (library_source_unproven) unless library.definition selects it by exact ref (selected, keyEvidence unverified), coverage lists each source's state and reasons (source_not_ready, index_partial, namespace_unknown, hidden_excluded, authorization_restricted), and snapshotId, relation and direction do not apply; its results carry ref, name, type, relation, basis, state, evidence, hidden, internal, page and scopeRoot but no path or origin.
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": "usages"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | the saved .fig to read now: a local path or gs://bucket/object; give file or workspaceId | |
| node | No | the exact layer id, stored or an instance sublayer I...;...; give node or resource | |
| limit | No | 1-200 results per page, default 50 | |
| scope | No | stored scope root whose locations are returned; default the document; a workspace needs a prepared scope | 0:0 |
| cursor | No | nextCursor from the previous page of the same query and snapshot | |
| library | No | with workspaceId, a library reference instead of a node or resource: {kind: component, style or variable, namespace, key}, as an out result's library names it; lists the layers in every visible source (or sourceId) whose cached copy records it. Optional definition {sourceId, snapshotId, nodeId} selects the definition by exact ref; without namespace only copies that record none are listed | |
| storage | No | absolute custom storage directory, only for a workspace kept outside the default storage; must be under the server's --storage-root | |
| relation | No | relations to keep, comma-separated; default every one but contains | |
| resource | No | a resource id instead of a layer: VariableID:..., StyleKey:... or image:<hash> | |
| sourceId | No | with workspaceId, the source to read; needed when several have this scope; with library, narrows to that one consumer source | |
| direction | No | in (what points at it) or out (what it points at, with library {kind, namespace, key} on a use of a cached library copy) | in |
| snapshotId | No | the snapshot your ref came from; a different current snapshot is source_stale | |
| workspaceId | No | ws_... from the index tool: read its prepared index instead of the file | |
| includeHidden | No | also return hidden locations |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | ||
| state | No | workspace queries without a ready index: pending or not_prepared | |
| source | No | sourceId and snapshotId; stateless calls add freshness | |
| hasMore | Yes | ||
| library | No | library queries: the kind, namespace and key asked | |
| members | No | COMPONENT_SET queries: the known member ids and whether they are complete | |
| results | Yes | in: each location's ref, name, type, origin, hidden, page, scopeRoot, path, relation, state, basis, evidence and via (the member a set query matched); library queries: ref, name, type, relation, state, basis, evidence, hidden, internal, page and scopeRoot, no origin or path, plus definitionMatch when a definition is selected: equal (the use's cached copy has the selected definition's fingerprint on every facet; not proof the library published it), definition_mismatch (a facet differs) or unknown (a facet unread or unsupported, such as a field holding a file-local GUID, or no copy to compare); out: target ref or resource, its definition and the edge fields, plus library {kind, namespace (null with unknownReason when no copy records one), key, basis cached_copy} on an instance_of, uses_style or binds_variable use whose cached library copy names it: the selector a library query takes | |
| coverage | Yes | complete, layers.relations kinds and version, reasons; library queries: complete, sources (sourceId, path, state, snapshotId, freshness when ready, nextSteps) and reasons; never a total count | |
| direction | No | ||
| nextSteps | No | the jobs or index call that makes the scope ready | |
| relations | No | ||
| definition | Yes | library queries: state unresolved with a reason (library_source_unproven when none is selected), or selected with basis caller_ref, the selected ref and keyEvidence unverified; null while a workspace scope is pending or not_prepared; else ref or resource, state (indexed in scope, outside_scope, or the state of the edges that name it: missing, unresolved, external, recorded), name, type, setId and page when known | |
| nextCursor | Yes | ||
| workspaceId | No | workspace queries only |