Tools Reference

Complete API reference for Yoku's MCP tools.

Overview

Yoku's MCP server provides two powerful tools for accessing brand intelligence data. This reference documents all parameters, response formats, and usage examples.

Available Tools

`brand.get`

Retrieve complete brand identity data by domain, company name, stock ticker, or ISIN code.

Purpose

Use brand.get when you need comprehensive information about a specific brand, including:

Visual assets (logos, icons)
Brand colors and typography
Company metadata
Social media profiles
Customer ratings and reviews
Industry classification

Input Schema

{
  domain?: string;      // Company domain (e.g., "stripe.com")
  name?: string;        // Company name (e.g., "Stripe")
  ticker?: string;      // Stock ticker (e.g., "AAPL")
  isin?: string;        // ISIN code (e.g., "US0378331005")
}

Parameters:

Parameter	Type	Required	Description	Example
`domain`	string	No*	Company's primary domain	`"stripe.com"`
`name`	string	No*	Company or brand name	`"Stripe"`
`ticker`	string	No*	Stock exchange ticker symbol	`"AAPL"`
`isin`	string	No*	International Securities ID	`"US0378331005"`

*At least one parameter is required. If multiple are provided, the query will attempt to match on any of them.

Response Format

{
  "id": "uuid",
  "title": "Stripe",
  "canonicalDomain": "stripe.com",
  "description": "Stripe is a technology company that builds economic infrastructure for the internet.",
  "slogan": "Payments infrastructure for the internet",
  "email": "support@stripe.com",
  "phone": "+1-888-926-2289",
  "industryLabel": "Financial Technology",
  "subindustryLabel": "Payment Processing",
  "naicsPrimaryCode": "522320",
  "countryCode": "US",
  "isNsfw": false,
  "status": "ACTIVE",
  "reviewStatus": "APPROVED",
  "websiteUrl": "https://stripe.com",
  "careersUrl": "https://stripe.com/jobs",
  "privacyUrl": "https://stripe.com/privacy",
  "termsUrl": "https://stripe.com/terms",
  "contactUrl": "https://stripe.com/contact",
  "blogUrl": "https://stripe.com/blog",
  "pricingUrl": "https://stripe.com/pricing",
  "identifiers": [
    {
      "type": "DOMAIN",
      "value": "stripe.com"
    },
    {
      "type": "TICKER",
      "value": "STRIPE"
    }
  ],
  "assets": [
    {
      "id": "asset-uuid",
      "url": "https://cdn.yoku.app/assets/asset-uuid",
      "type": "LOGO",
      "width": 512,
      "height": 512,
      "mimeType": "image/png",
      "fileSize": 12345
    }
  ],
  "colors": [
    {
      "hex": "#635BFF",
      "name": "Stripe Purple",
      "usage": "PRIMARY",
      "confidence": 0.95,
      "weight": 1.0,
      "source": "OFFICIAL"
    }
  ],
  "socials": [
    {
      "type": "TWITTER",
      "url": "https://twitter.com/stripe",
      "handle": "@stripe"
    },
    {
      "type": "LINKEDIN",
      "url": "https://linkedin.com/company/stripe",
      "handle": "stripe"
    }
  ],
  "ratings": [
    {
      "source": "TRUSTPILOT",
      "sourceUrl": "https://trustpilot.com/review/stripe.com",
      "rating": 4.5,
      "reviewCount": 1234
    }
  ]
}

Response Fields

Core Fields:

Field	Type	Description
`id`	string	Unique brand identifier (UUID)
`title`	string	Official brand/company name
`canonicalDomain`	string	Primary domain for the brand
`description`	string	Company description (AI-friendly)
`slogan`	string	Brand tagline or slogan

Contact Information:

Field	Type	Description
`email`	string	Official contact email
`phone`	string	Contact phone number
`websiteUrl`	string	Main website URL
`careersUrl`	string	Careers/jobs page URL
`privacyUrl`	string	Privacy policy URL
`termsUrl`	string	Terms of service URL
`contactUrl`	string	Contact page URL
`blogUrl`	string	Company blog URL
`pricingUrl`	string	Pricing page URL

Classification:

Field	Type	Description
`industryLabel`	string	Primary industry category
`subindustryLabel`	string	More specific industry segment
`naicsPrimaryCode`	string	NAICS industry code
`countryCode`	string	ISO 3166-1 alpha-2 country code

Status:

Field	Type	Description
`status`	string	Brand status: ACTIVE, INACTIVE, ACQUIRED
`reviewStatus`	string	Review status: APPROVED, PENDING, REJECTED
`isNsfw`	boolean	Whether content is NSFW

Identifiers Array:

Field	Type	Description
`type`	string	Type: DOMAIN, COMPANY_NAME, TICKER, ISIN
`value`	string	The identifier value

Assets Array:

Field	Type	Description
`id`	string	Asset UUID
`url`	string	CDN URL for the asset
`type`	string	Type: LOGO, ICON, WORDMARK, etc.
`width`	number	Image width in pixels
`height`	number	Image height in pixels
`mimeType`	string	MIME type (e.g., "image/png")
`fileSize`	number	File size in bytes

Colors Array:

Field	Type	Description
`hex`	string	Color in hex format (#RRGGBB)
`name`	string	Color name or description
`usage`	string	Usage: PRIMARY, SECONDARY, ACCENT, etc.
`confidence`	number	Confidence score (0-1)
`weight`	number	Visual weight in brand palette
`source`	string	Source: OFFICIAL, DERIVED, EXTRACTED

Socials Array:

Field	Type	Description
`type`	string	Platform: TWITTER, LINKEDIN, FACEBOOK, INSTAGRAM, etc.
`url`	string	Full profile URL
`handle`	string	Username/handle on the platform

Ratings Array:

Field	Type	Description
`source`	string	Rating platform: TRUSTPILOT, G2, CAPTERRA, etc.
`sourceUrl`	string	URL to the review page
`rating`	number	Rating value (scale varies by source)
`reviewCount`	number	Total number of reviews

Usage Examples

By Domain:

Get brand details for stripe.com

By Company Name:

Get brand information for "Netflix"

By Stock Ticker:

Fetch brand data for ticker AAPL

By ISIN:

Get brand using ISIN US0378331005

Multiple Identifiers:

Get brand for Spotify (domain: spotify.com or ticker: SPOT)

Example AI Prompts

"Use brand.get to fetch Stripe's logo and brand colors"

"Get complete brand information for netflix.com including social profiles"

"Fetch brand data for Apple using ticker AAPL and show me their color palette"

"Get brand details for domain shopify.com and list all available assets"

"Use brand.get with name 'Tesla' and show the company description"

Error Responses

Brand Not Found:

{
  "found": false
}

Missing Parameters:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: at least one identifier required"
  },
  "id": null
}

`brand.search`

Perform fuzzy search to discover brands, with support for filtering and pagination.

Purpose

Use brand.search when you need to:

Find brands by partial name or keyword
Discover companies in a specific industry
Filter brands by country
Provide autocomplete suggestions
Explore brand catalogs

Input Schema

{
  q: string;           // Search query (required)
  limit?: number;      // Results per page (default: 10, max: 100)
  offset?: number;     // Pagination offset (default: 0)
  country?: string;    // ISO 3166-1 alpha-2 country code
}

Parameters:

Parameter	Type	Required	Description	Example
`q`	string	Yes	Search query (1-255 chars)	`"fintech"`
`limit`	number	No	Results per page (1-100)	`10`
`offset`	number	No	Skip N results for pagination	`0`
`country`	string	No	Filter by 2-letter country code	`"US"`

Response Format

{
  "total": 42,
  "results": [
    {
      "id": "uuid",
      "title": "Stripe",
      "title_normalized": "stripe",
      "canonical_domain": "stripe.com",
      "description": "Stripe is a technology company...",
      "country_code": "US",
      "industry_label": "Financial Technology",
      "subindustry_label": "Payment Processing",
      "status": "ACTIVE",
      "is_nsfw": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T15:45:00Z"
    }
    // ... more results
  ]
}

Response Fields

Field	Type	Description
`total`	number	Total number of results found
`results`	array	Array of brand objects

Brand Object Fields:

Field	Type	Description
`id`	string	Brand UUID
`title`	string	Official brand name
`title_normalized`	string	Normalized name for search
`canonical_domain`	string	Primary domain
`description`	string	Brand description
`country_code`	string	ISO country code
`industry_label`	string	Primary industry
`subindustry_label`	string	Subindustry category
`status`	string	ACTIVE, INACTIVE, ACQUIRED
`is_nsfw`	boolean	NSFW flag
`created_at`	string	ISO timestamp
`updated_at`	string	ISO timestamp

Search Behavior

Fuzzy Matching:

Uses PostgreSQL trigram similarity
Tolerates typos and partial matches
Example: "spotfy" will match "Spotify"

Ranking Algorithm:

Exact matches ranked first
Similarity score (higher = better match)
Title length (shorter titles preferred for ambiguous queries)

Search Targets:

Brand titles
Company name identifiers
Normalized variations

Usage Examples

Basic Search:

Search for "stripe"

With Limit:

Search for "fintech" with limit 5

With Pagination:

Search for "technology" with limit 20 and offset 40

Country Filter:

Search for "tech" in Germany (country: DE)

Complex Query:

Find French fintech companies (query: "fintech", country: "FR", limit: 10)

Example AI Prompts

"Search for payment processing companies"

"Find all brands matching 'spotify'"

"Search for tech companies in the US, limit to 5 results"

"Find German automotive brands"

"Search for 'stream' and show the first 3 results"

"Look for fintech companies, skip the first 10 results (offset 10)"

"Find brands in France containing 'luxury'"

Pagination Example

To paginate through results:

Page 1 (results 1-10):

{
  "q": "technology",
  "limit": 10,
  "offset": 0
}

Page 2 (results 11-20):

{
  "q": "technology",
  "limit": 10,
  "offset": 10
}

Page 3 (results 21-30):

{
  "q": "technology",
  "limit": 10,
  "offset": 20
}

Error Responses

Invalid Query Length:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: query must be 1-255 characters"
  },
  "id": null
}

Invalid Limit:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: limit must be between 1 and 100"
  },
  "id": null
}

Invalid Country Code:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: country must be 2-letter ISO code"
  },
  "id": null
}

Best Practices

1. Choose the Right Tool

Use brand.get when you know a specific identifier (domain, name, ticker)
Use brand.search for discovery, exploration, or autocomplete

2. Optimize Search Queries

Good queries:

"stripe" - Clear, specific
"fintech payment" - Descriptive keywords
"automotive germany" - Industry + location

Avoid:

"a" - Too vague
"the best company" - Subjective, not searchable
Very long queries (>255 chars)

3. Handle Empty Results

Always check if results exist:

const result = await brand_get({ domain: "example.com" });
if (!result.found) {
  console.log("Brand not found");
}

4. Use Pagination Wisely

For large result sets:

Start with reasonable page sizes (10-20)
Only fetch more if needed
Cache results when possible

5. Respect Rate Limits

Monitor your quota in the dashboard
Implement exponential backoff for retries
Cache frequently accessed data
Batch similar queries together

6. Leverage Country Filters

When searching specific markets:

Search for "fashion" in country "FR"

This is more efficient than searching all brands then filtering client-side.

7. Combine Tools Effectively

Pattern: Search then Get

Use brand.search to find candidates
Use brand.get to fetch complete details

"Search for 'payment processors', then get full details for the top result"

Tool Comparison

Feature	brand.get	brand.search
Purpose	Get specific brand	Discover brands
Input	Identifiers	Keywords/query
Returns	Complete data	Basic info list
Best For	Known brands	Exploration
Pagination	N/A	Supported
Filtering	N/A	By country
Response Size	Large (~5-20 KB)	Small (~1-5 KB)

Common Workflows

Workflow 1: Brand Lookup

1. User provides domain: "stripe.com"
2. Call: brand.get({ domain: "stripe.com" })
3. Display logo, colors, description

Workflow 2: Autocomplete

1. User types: "spot"
2. Call: brand.search({ q: "spot", limit: 5 })
3. Show dropdown with matches
4. User selects "Spotify"
5. Call: brand.get({ domain: "spotify.com" })
6. Show full details

Workflow 3: Industry Analysis

1. Call: brand.search({ q: "fintech", limit: 50 })
2. Iterate through results
3. For each interesting brand:
   Call: brand.get({ domain: result.canonical_domain })
4. Analyze and compare

Workflow 4: Geographic Market Research

1. Call: brand.search({ q: "automotive", country: "DE", limit: 100 })
2. Collect all German automotive brands
3. For top brands:
   Call: brand.get() to get detailed data
4. Generate market report

Next Steps

Setup Guide - Learn about authentication and rate limits
Cursor Integration - Use these tools in Cursor
Jan Integration - Query these tools with Jan AI
API Documentation - REST API alternative

Need Help?

Questions about the tools?

Email Support: contact@yoku.app
Dashboard: Monitor usage and quota
API Keys: Manage keys in settings

Pro Tip: Test in Cursor First

Before building complex integrations, test tool calls interactively in Cursor to understand response formats and behavior. This makes debugging much easier.

Jan Integration

Connect Jan AI to Yoku's MCP server for conversational brand intelligence.