Tools Reference

All MCP tools available through the Particl server. These tools are automatically discovered by your AI client.

How tools work

Your AI assistant automatically selects and calls the right tools based on your questions. You don't need to reference tool names directly — just ask naturally and the AI will figure out which tools to use.

Free tools

These tools don't consume any export credits.

search_companies

Free

Search for companies by name or domain. Returns matching companies with basic metadata. Use this to find company IDs for other tools.

Parameters

searchstringrequired

Search term — company name or domain (max 200 characters)

page_sizeinteger

Results per page (default: 25, max: 100)

pageinteger

Page number, 0-indexed (default: 0)

sort_bystring

"popularity" (default) or "start_date"

country_codestring

Filter by country code (default "US"). Common values: "US", "CA", "AU", "GB". Pass empty string to search all countries.

get_product_types

Free

Browse the product type taxonomy to discover valid categories for filtering. Call with no parameters to get root-level categories, then pass a product_type_id to drill into subcategories.

Parameters

parent_product_type_idstring

Get child categories under this product type. Omit to get root-level categories.

get_credit_balance

Free

Check how many export credits remain on your account. Useful for monitoring usage before running paid queries.

No parameters required

Company tools

Look up details and browse the product catalog for a specific company.

get_company_details

1 credit/call

Get metadata for a specific company — name, domain, country, and tracking start date.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

get_company_products

1 credit/row

Deep-dive into a specific company’s product catalog. The primary tool for company-level analysis — supports full pagination and custom date ranges. Use search_companies first to find the company ID.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

product_type_idstring

Product type UUID from get_product_types. Pass the product_type_id value, not the name.

keywordstring

Tag filter (e.g. "wool", "recycled", "organic"). Searches product tags only, not titles.

title_searchstring

Search products by title (e.g. "tank top", "winter jacket"). Use this instead of keyword for title matching.

brandstring

Filter by brand name

min_pricefloat

Minimum price filter

max_pricefloat

Maximum price filter

sort_bystring

"sales_revenue" (default), "sales_volume", "price", or "launch_date"

sort_directionstring

"desc" (default) or "asc"

page_sizeinteger

Results per page (default: 25, max: 100)

pageinteger

Page number, 0-indexed (default: 0)

start_datestring

Start of date range (YYYY-MM-DD, defaults to ~30 days ago)

end_datestring

End of date range (YYYY-MM-DD, defaults to today)

confidence_thresholdfloat

Minimum data confidence score (0-10, default 6.0). Lower to 0 to include all products regardless of data quality.

Product tools

Drill into individual products — full details, variant-level data, attribute breakdowns, and historical sales trends.

get_product_details

1 credit/call

Get full details for a specific product — pricing, brand, gender, ratings, reviews, images, materials, keywords, and category data. Use get_company_products first to find product IDs.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

product_idstringrequired

The product ID from get_company_products or get_market_top_products

get_product_variants

1 credit/row

Get variant-level data for a specific product — colors, sizes, individual pricing and sales. Use get_company_products first to find product IDs.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

product_idstringrequired

The product ID from get_company_products or get_market_top_products

start_datestring

Start of sales data window (YYYY-MM-DD, defaults to ~30 days ago)

end_datestring

End of sales data window (YYYY-MM-DD, defaults to today)

get_product_breakdown

1 credit/row

Get product data broken down by a specific attribute. Useful for understanding product mix — e.g., which colors sell best, which brands dominate, or what materials are most popular.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

breakdown_typestringrequired

"keyword", "material", "colors", "brands", "gender", or "locations"

product_type_idstring

Product type UUID from get_product_types to filter by category

keywordstring

Tag filter (e.g. "sustainable"). Searches product tags only.

start_datestring

Start of date range (YYYY-MM-DD, defaults to ~30 days ago)

end_datestring

End of date range (YYYY-MM-DD, defaults to today)

confidence_thresholdfloat

Minimum data confidence score (0-10, default 6.0). Lower to 0 to include all products regardless of data quality.

get_sales_timeseries

1 credit/data point

Get historical sales timeseries data for a company or a single product. Returns daily, weekly, or monthly data points showing revenue, volume, and pricing over time. Essential for understanding trends, seasonality, and growth.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

product_idstring

Optional product ID to get timeseries for a single product

product_type_idstring

Product type UUID from get_product_types to filter by category

keywordstring

Tag filter (e.g. "sustainable"). Searches product tags only.

start_datestring

Start of date range (YYYY-MM-DD, defaults to ~30 days ago)

end_datestring

End of date range (YYYY-MM-DD, defaults to today)

aggregation_typestring

"daily", "weekly", or "monthly". Auto-selected if omitted.

confidence_thresholdfloat

Minimum data confidence score (0-10, default 6.0). Lower to 0 to include all products regardless of data quality.

Marketing tools

Browse a company's marketing assets — emails, social posts, ads, and engagement metrics.

get_company_marketing_assets

1 credit/row

List a company’s marketing assets — emails, Instagram posts, Facebook/Meta ads, SMS messages, and homepage screenshots. Use search_companies first to find the company ID.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

asset_typesstring[]

Filter by asset type(s): "email", "instagram_post", "facebook_ads", "sms", "homepage_screenshot". Defaults to all types.

start_datestring

Start of date range (YYYY-MM-DD, defaults to ~30 days ago)

end_datestring

End of date range (YYYY-MM-DD, defaults to ~2 days ago)

page_sizeinteger

Results per page (default: 25, max: 100)

pageinteger

Page number, 0-indexed (default: 0)

get_company_marketing_stats

1 credit/call

Get aggregated marketing engagement statistics for a company — posting frequency by type, average likes, engagement rate, most liked post, and posting hour distribution.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

get_marketing_asset_details

1 credit/call

Get full details of a specific marketing asset — email content, social post with engagement metrics, ad creative, or homepage screenshot.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

asset_idstringrequired

The asset ID returned from get_company_marketing_assets

Event tools

Track promotional events — product launches, sales, restocks, and more — with associated marketing assets and products.

get_company_events

1 credit/row

Get promotional events for a company — product launches, sales, restocks, price changes, and discounts — with associated marketing assets and products.

Parameters

company_idstringrequired

Particl company ID (e.g. "lululemon-com")

start_datestring

Start of date range (YYYY-MM-DD, defaults to ~30 days ago)

end_datestring

End of date range (YYYY-MM-DD, defaults to ~2 days ago)

event_typesstring[]

Filter by event type(s): "Promotion", "Product Release", "Special Event", "Collaboration", "Restock", and more

channelsstring[]

Filter by marketing channel(s): "email", "instagram_post", "facebook_ads", "sms", "homepage_screenshot"

page_sizeinteger

Results per page (default: 10, max: 100)

pageinteger

Page number, 0-indexed (default: 0)

Market tools

Search products across all brands, see top sellers, top companies, and pricing analysis for any category.

get_market_top_products

1 credit/row

Get the best-selling products in a category over the trailing 30 days. High-level summary with no pagination.

Parameters

product_type_idstring

Product type UUID from get_product_types. Pass the product_type_id value, not the name.

keywordstring

Tag filter

end_datestring

End of the 30-day window (YYYY-MM-DD, defaults to ~2 days ago)

get_market_top_companies

1 credit/row

Get the top-performing companies in a category over the trailing 30 days. Great for understanding competitive landscape at a glance.

Parameters

product_type_idstring

Product type UUID from get_product_types. Pass the product_type_id value, not the name.

keywordstring

Tag filter

end_datestring

End of the 30-day window (YYYY-MM-DD, defaults to ~2 days ago)

get_market_pricing_analysis

1 credit/call

Get price distribution and statistics for a product category. Returns min, max, average, and percentile breakdowns.

Parameters

product_type_idstring

Product type UUID from get_product_types. Pass the product_type_id value, not the name.

keywordstring

Tag filter

end_datestring

End of the 30-day window (YYYY-MM-DD, defaults to ~2 days ago)

get_market_sales

1 credit/call

Get aggregated market-level sales data with monthly timeseries. Returns total market revenue and volume, plus monthly trends. Use with get_market_top_companies and get_market_top_products for complete market analysis.

Parameters

product_type_idstring

Product type UUID from get_product_types. Pass the product_type_id value, not the name.

keywordstring

Tag filter

end_datestring

End of the 30-day window (YYYY-MM-DD, defaults to ~2 days ago)