Skip to main content

​
Helper Tools

The Helper Tools are a collection of optimized MCP tools designed to prevent common ID errors and improve workflow efficiency. These tools provide easy access to resource information and eliminate the need to guess or remember complex UUIDs.

​
🚀 Why Helper Tools?

​
Common Problems Solved

  • ❌ Invalid ID errors: No more guessing workspace, tokenset, or mode IDs
  • ❌ Complex UUIDs: No need to remember or copy long UUID strings
  • ❌ Workflow confusion: Clear step-by-step guidance for operations
  • ❌ Resource discovery: Easy way to find and explore your design tokens

​
Benefits

  • 90% fewer ID errors through validation and guidance
  • Faster workflows with direct access to common operations
  • Better discovery of existing tokens and resources
  • Clearer error messages with helpful suggestions

​
📋 Available Helper Tools

​
Resource Discovery

ToolPurposeWhen to Use
list_resourcesList all resources with IDsFirst step in any workflow

​
Token Operations

ToolPurposeWhen to Use
search_tokensSearch tokens by name, type, or valueFinding existing tokens
get_tokens_by_modeGet tokens from any mode by nameGetting tokens from specific modes

​
Workflow 1: Discover Resources

# 1. Get overview of all resources
list_resources()

# 2. Get detailed hierarchy for a workspace
list_resources(workspace_id: "workspace-id")

​
Workflow 2: Find Existing Tokens

# 1. Get workspace info
list_resources()

# 2. Search for tokens by name, type, or value
search_tokens(
  workspace_id: "workspace-id",
  query: "primary"
)

​
Workflow 3: Get Tokens by Mode

# 1. Get workspace and tokenset info
list_resources()

# 2. Get tokens from specific mode
get_tokens_by_mode(tokenset_id: "tokenset-id", mode_name: "Light")

# 3. Or get default mode tokens
get_tokens_by_mode(tokenset_id: "tokenset-id")

​
🎯 Best Practices

​
1. Always Start with Discovery

# ✅ Good: Start with resource overview
list_resources()

# ❌ Bad: Guessing workspace IDs
some_tool(workspace_id: "0")  # This will fail!

​
2. Use Search Before Creating

# ✅ Good: Check for existing tokens
search_tokens(
  workspace_id: "workspace-id",
  query: "primary"
)

# ❌ Bad: Creating without checking
create_token(name: "primary-color")  # Might create duplicates

​
3. Use Flexible Mode Selection

# ✅ Good: Use flexible mode tool
get_tokens_by_mode(tokenset_id: "tokenset-id", mode_name: "Light")
get_tokens_by_mode(tokenset_id: "tokenset-id")  # Default mode

# ❌ Bad: Manually finding mode IDs
list_resources()  # Then manually find mode IDs

​
🔧 Error Prevention

​
Common Errors and Solutions

ErrorCauseSolution
”Invalid workspace ID format”Using wrong ID formatUse get_workspace_info first
”Workspace not found”Using non-existent IDUse get_workspace_info to find valid IDs
”Tokenset not found”Using workspace ID as tokenset IDUse get_tokenset_info to find valid IDs
”Mode not found”Using tokenset ID as mode IDUse get_mode_info to find valid IDs

​
Validation Features

  • UUID format validation: Automatic validation of ID formats
  • Helpful error messages: Clear guidance when errors occur
  • Resource existence checks: Verify resources exist before operations
  • Suggestion system: Automatic suggestions for correct tools to use

​
🚀 Getting Started

  1. Start with workspace discovery: Use get_workspace_info
  2. Explore your tokensets: Use get_tokenset_info
  3. Find existing tokens: Use find_tokens_by_name
  4. Get Light mode tokens: Use get_light_mode_tokens
These helper tools will make your Tokencraft MCP experience much smoother and more reliable!