> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokencraft.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Tokens

> Search for tokens by name, type, or value across all tokensets and modes

# Search Tokens

Search for tokens across all tokensets and modes in a workspace. This powerful search tool helps you find existing tokens by name, type, or value, making it easy to discover and reuse tokens.

## Description

This helper tool provides comprehensive token search capabilities across your entire workspace. It searches through token names, values, and descriptions, and can optionally filter by token type.

## Parameters

| Parameter      | Type   | Required | Description                                         |
| -------------- | ------ | -------- | --------------------------------------------------- |
| `workspace_id` | string | Yes      | The ID of the workspace                             |
| `query`        | string | Yes      | Search query (name, type, or value pattern)         |
| `type`         | string | No       | Optional token type filter (color, dimension, etc.) |

## Response

Returns matching tokens grouped by tokenset with:

* `query`: The search query used
* `type_filter`: The type filter applied (if any)
* `results`: Array of tokensets containing matching tokens
* `total_found`: Total number of matching tokens
* `usage`: Instructions on how to use the returned IDs

## Example Usage

```bash theme={null}
# Search for all tokens containing "primary"
search_tokens(
  workspace_id: "0afa0a8a-5e59-4ef9-9619-c12ecdad3c1a",
  query: "primary"
)

# Search for color tokens only
search_tokens(
  workspace_id: "0afa0a8a-5e59-4ef9-9619-c12ecdad3c1a",
  query: "blue",
  type: "color"
)

# Search by value
search_tokens(
  workspace_id: "0afa0a8a-5e59-4ef9-9619-c12ecdad3c1a",
  query: "#0066CC"
)
```

## Example Response

```json theme={null}
{
  "query": "primary",
  "type_filter": null,
  "results": [
    {
      "tokenset": {
        "id": "164809aa-cbd2-4c5f-ac1a-af6902c29f6e",
        "name": "Core"
      },
      "tokens": [
        {
          "id": "6422fc25-bfd0-4c97-8e23-bea8e7b6a77a",
          "name": "primary-oxygrox-tete",
          "type": "color",
          "value": "#ce3bf7",
          "description": null,
          "mode_id": "2edd637b-5088-4c9b-abbc-e431e5816e94",
          "alias_to": null
        },
        {
          "id": "44432f60-d9ae-4a50-b3ca-9727bc705e7d",
          "name": "colors.primary.50",
          "type": "color",
          "value": "#eff6ff",
          "description": "Lightest primary color",
          "mode_id": "2edd637b-5088-4c9b-abbc-e431e5816e94",
          "alias_to": null
        }
      ]
    }
  ],
  "total_found": 2,
  "usage": "Use these token IDs and mode IDs in other tools"
}
```

## Use Cases

* **Token discovery**: Find existing tokens by name or value
* **Avoiding duplicates**: Check if a token already exists before creating
* **Pattern matching**: Find all tokens matching a specific pattern
* **Cross-tokenset search**: Search across multiple tokensets at once
* **Type filtering**: Find tokens of a specific type

## Search Examples

### By Name Pattern

```bash theme={null}
search_tokens(workspace_id: "id", query: "button")
search_tokens(workspace_id: "id", query: "spacing")
search_tokens(workspace_id: "id", query: "font")
```

### By Value

```bash theme={null}
search_tokens(workspace_id: "id", query: "#0066CC")
search_tokens(workspace_id: "id", query: "16px")
search_tokens(workspace_id: "id", query: "bold")
```

### By Type

```bash theme={null}
search_tokens(workspace_id: "id", query: "color", type: "color")
search_tokens(workspace_id: "id", query: "spacing", type: "dimension")
search_tokens(workspace_id: "id", query: "font", type: "fontFamily")
```

## Related Tools

* `list_resources` - Get workspace and tokenset IDs
* `get_default_mode_tokens` - Get all tokens from default mode
* `create_token` - Create new tokens
* `update_token` - Update existing tokens

## Workflow Example

```bash theme={null}
# 1. Get workspace info
list_resources()

# 2. Search for existing tokens
search_tokens(
  workspace_id: "0afa0a8a-5e59-4ef9-9619-c12ecdad3c1a",
  query: "primary"
)

# 3. Use found token IDs for operations
update_token(
  tokenset_id: "164809aa-cbd2-4c5f-ac1a-af6902c29f6e",
  mode_id: "2edd637b-5088-4c9b-abbc-e431e5816e94",
  token_id: "6422fc25-bfd0-4c97-8e23-bea8e7b6a77a",
  value: "#0066CC"
)
```

## Best Practices

1. **Use descriptive queries**: Be specific with your search terms
2. **Check before creating**: Search before creating new tokens to avoid duplicates
3. **Use type filters**: Narrow down results with type filters when needed
4. **Copy exact IDs**: Use the exact token and mode IDs from results

## Error Prevention

This tool helps prevent common errors:

* ❌ Creating duplicate tokens
* ❌ Using invalid token IDs
* ❌ Missing existing tokens
* ✅ Finding existing tokens by name or value
* ✅ Getting valid IDs for operations