- Read tools (33) return data: projects, brands, model channels, prompts, chats, reports, actions, scraped source content, custom classifications, the brand profile, products and the shopping catalog, shopping performance/demand/trend metrics, the Peec documentation, and Agent Analytics (known bots and access-log visit counts).
- Write tools (43) create, update, archive, or delete brands, prompts, tags, tag groups, topics, products, categories, custom domain/URL classifications, and the brand profile. Your assistant confirms before calling one.
All tools except
list_projects, search_docs, and read_doc require a project_id. Your AI assistant handles this automatically after you pick a project.Write tools require organization-owner access on the project. Any project member can use the read tools.
Tool calls are rate limited to 1,000 calls per minute per user. If you hit the limit, the server tells your assistant to retry after a few seconds.
Response format
Most tools return compact columnar JSON:columns order. List tools (list_brands, list_topics, list_tags, list_prompts, list_chats, list_search_queries, list_shopping_queries, list_products, list_categories, list_global_brands, list_shopping_demand, list_shopping_performance, list_domain_classifications, list_url_classifications) also return a totalCount field with the total matching records across pages, so you can tell whether to paginate. get_chat, get_url_content, get_project_profile, get_product, get_shopping_trend, get_shopping_attributes, read_doc, list_bots, and get_agent_visits are exceptions: they return their object directly.
list_projects
Lists all projects your account has access to. This is always called first. Columns:id, name, status
list_brands
List brands (your brand and tracked competitors) in a project.
Columns:
id, name, domains, aliases, is_own
aliases are alternate names the brand is matched under. is_own indicates whether this is your brand (true) or a competitor (false).
list_topics
Lists topic groupings in a project. Each prompt belongs to one topic.
Columns:
id, name
list_tags
Lists tags (cross-cutting labels) in a project.
Columns:
id, name, is_system, group
System tags (is_system: true) are Peec-managed branding/intent tags; their group is branding or intentType. User tags carry their user-defined group name in group (or null when ungrouped). Use list_tag_groups to enumerate the user-defined groups.
list_tag_groups
Lists the user-defined tag groups in a project, each with its shared color and tag count. System groups (branding/intentType) are not included — seelist_tags.
Returns:
{ data: [{ group, color, tag_count }] }.
list_models
Lists all AI engines (models) configured for a project. Use this to resolve model names (e.g. “ChatGPT”, “Perplexity”) to IDs before filtering reports, and to label model IDs with human-readable names when presenting results.
Columns:
id, name, is_active
The is_active field indicates whether the model is enabled for this project. Inactive models return empty data in reports.
Filtering and breaking down reports by
model_id is deprecated. Prefer model_channel_id (see list_model_channels) — channels are stable engine identifiers that survive model version upgrades.list_model_channels
Lists the AI engine channels tracked by Peec. A model channel is a stable identifier for an engine (e.g.openai-0 = ChatGPT UI) that persists as the underlying model is upgraded. Use it to filter or break down reports without tying yourself to a specific model version.
Columns:
id, description, current_model_id, is_active, unsupported_country_codes
current_model_idis the model ID currently active in the channel. Pass this asmodel_idif a report still requires the deprecated filter.is_activemirrors the engine’s status for this project. Inactive channels return empty data.unsupported_country_codeslists ISO 3166-1 alpha-2 codes the channel can’t serve. Chats requested for those countries are not created.
list_prompts
Lists prompts in a project. You can filter by topic or tag.
Columns:
id, text, tag_ids, topic_id, volume
tag_ids is an array of tag IDs. topic_id is the topic ID or null. volume is a relative search-volume bucket: very low, low, medium, high, very high, or null when the prompt does not have a volume signal yet.
list_chats
List individual AI responses (chats) for a project over a date range. Each chat is one prompt run against one AI engine on a given date. Combine withget_chat to inspect the full response.
Columns:
id, prompt_id, model_id, model_channel_id, date, features
features is an array of feature flags marking special elements detected in the assistant response. Use the same values listed under the features filter above.
By default, chats are excluded if their prompt has been deleted or archived. Pass include_archived_prompts=true to include chats for archived prompts (e.g. for a historical lookback against a prompt no longer being tracked). Chats for deleted prompts are always excluded.
get_chat
Get the full content of a single chat: the user prompt, the AI response, every source URL the model retrieved, every brand it mentioned, every search query it issued, and any extracted products.
Returns:
list_search_queries
Lists the search sub-queries an AI engine fanned out to while answering prompts in a project over a date range. Each row is one sub-query issued for a given chat. Combine withget_chat to inspect the full response.
Columns:
prompt_id, chat_id, model_id, model_channel_id, date, query_index, query_text
list_shopping_queries
Lists the product/shopping sub-queries an AI engine fanned out to while answering prompts. Each row is one shopping sub-query and the distinct products returned for it in a given chat.
Columns:
prompt_id, chat_id, model_id, model_channel_id, date, query_text, products
products is an array of product names extracted for that sub-query.
list_products
List a project’s products with headline AI-visibility metrics over a date range.
Columns:
id, name, brand, image_url, price_range, categories, mention_count, win_count, avg_position, visibility, share_of_voice
get_product
Detailed metrics for one product over a date range — the drill-down companion tolist_products.
Returns:
{ data, primary_currency }. data is null if the product isn’t in the project, otherwise: id, name, brand, description, image_url, source, first_seen_at, price_range, visibility, win_rate, avg_position, mention_count, a *_delta for each metric (vs the immediately preceding equal-length period), and ai_price_map / ai_price_delta_map (per-currency median price across the product’s AI mentions).
get_shopping_attributes
The LLM-extracted attribute grid — characteristics the AI associates with a product (or the whole catalog), compared against competitors.
Returns: a nested grid
{ tab, competitors[], groups[], total_groups } (not columnar). Every group’s per-competitor arrays align to the competitors order. Group shape depends on tab (characteristics, facts, or dimensions). Deltas are computed against an explicit comparison window (previous_start_date / previous_end_date) or the equal-length window immediately before.
get_shopping_summary
Aggregate shopping metrics for a project over a date range, as a single columnar row. Deltas compare against the explicitprevious_start_date / previous_end_date window when given, otherwise the auto-derived previous period.
Columns:
avg_visibility, avg_visibility_delta, avg_win_rate, avg_win_rate_delta, avg_position, avg_position_delta
get_shopping_trend
A product or brand shopping time series. Requiresbucket and exactly one of product_ids or brand_ids.
Returns: a nested object
{ entity_type, series } (not columnar). Each series entry is { entity_id, points }, and each point carries date, visibility, win_rate, avg_position, sov, has_data.
list_shopping_demand
Ranked shopping queries, search fan-out queries, or query terms over a date range — what shoppers are asking that surfaces your category.
Columns:
kind, text, distinct_chat_count, distinct_chat_count_previous, delta
list_shopping_performance
Ranked product or category shopping performance over a date range.
Columns:
entity_type, entity_id, name, visibility, visibility_delta, win_rate, win_rate_delta, avg_position, avg_position_delta, appearances, appearances_delta
list_categories
List the project’s product categories. Categories are an org-wide tree (e.g.Footwear > Shoes > Running Shoes); each row carries its full path and parent_id, so the flat list rebuilds the tree. Use a row’s id as a category_id when creating or updating products.
Columns:
id, name, path, parent_id
list_global_brands
Search Peec’s global brand catalog — the shared registry of real-world brands (e.g. Nike, Apple) that products attach to. Use it to find theglobal_brand_id before create_products. This is not the same as list_brands: that returns the brands tracked inside a project, while this searches every brand in Peec’s catalog. The two have different ids.
Columns:
id, name, domain, description, mention_count, is_own
list_bots
Lists every AI agent bot tracked in Agent Analytics. Each entry has the bot’s ID (the user agent string Peec matches), its provider, and its type. Use the returned IDs withget_agent_visits to filter visit counts by specific bots.
Returns:
{ data: [{ id, provider, type }] }.
Bot types:
training— crawlers that collect data to build or refine AI models (e.g.GPTBot,ClaudeBot)search— bots that browse the web to find up-to-date information for AI-powered search (e.g.PerplexityBot)userQuery— bots triggered by a real-time user query that fetch content on the user’s behalfother— miscellaneous bots
Agent Analytics requires a connected data source (Cloudflare Workers or a CSV/CLF log upload). See Crawl Insights for setup.
get_agent_visits
Aggregate AI bot visit counts from your connected access logs over a date range. Withoutgroup_by, returns the total as a single { visits: N } row. With group_by, returns one row per distinct value of the chosen dimension(s), sorted by visits descending.
Group-by dimensions
Multiple values produce a cross-dimensional breakdown — for example,
["bot_id", "response_status"] gives per-bot, per-status counts. Combine with time_bucket to get e.g. per-bot, per-day counts.
Response fields
{ data: [...], totalCount }.
list_domain_classifications
Lists the custom domain classifications defined for a project. These complement the built-in classifications (Corporate, Competitor, Editorial, Institutional, Other, Reference, UGC, You, Related) and can be assigned to specific domains via assign_domain_classification.
Columns:
name, color
list_url_classifications
Lists the custom URL classifications defined for a project. These complement the built-in classifications (Homepage, Category Page, Product Page, Listicle, Comparison, Profile, Alternative, Discussion, How-To Guide, Article, Other) and can be assigned to specific URLs via assign_url_classification.
Columns:
name, color
get_brand_report
Returns brand visibility, sentiment, position, and share of voice across AI search engines.Parameters
Response fields
The response also includes raw aggregation fields (
visibility_count, visibility_total, sentiment_sum, sentiment_count, position_sum, position_count) for custom calculations across segments.
get_domain_report
Returns source domain retrieval and citation metrics across AI search engines.Parameters
Response fields
get_url_report
Returns URL-level retrieval and citation metrics across AI search engines.Parameters
Response fields
get_url_content
Returns the scraped markdown content of a source URL Peec has indexed. Use this afterget_url_report to inspect the actual content an AI engine read. Useful for content gap analysis and comparing why a competitor URL wins citations.
Response fields
Returns a 404 if the URL has never been retrieved by any Peec project. Peec only scrapes URLs that appear as AI sources.
get_actions
Returns Peec’s opportunity-scored action recommendations for a project and date range. Use this whenever the user asks what to do next, how to improve visibility, or wants ranked next steps instead of raw data. The tool is two-step: always callscope=overview first to see which slices have the biggest opportunity, then drill into owned, editorial, reference, or ugc for the actual textual recommendations.
Parameters
Response (scope=overview)
Each overview row surfaces exactly one of
url_classification or domain. Pass that value into the matching scope in the follow-up call.
Response (scope=owned | editorial | reference | ugc)
get_project_profile
Read the project’s brand profile: the description, industry, brand-identity adjectives, target markets, audience distribution, and product or service list that Peec uses to generate prompt suggestions. Call this beforeset_project_profile so the assistant can show you the current values before changing anything.
Returns:
{ profile }. profile is null if the project hasn’t been profiled yet, otherwise an object with the fields described under set_project_profile.
search_docs
Search the Peec product documentation at docs.peec.ai and return the most relevant pages. The assistant uses this for any question about how Peec works — what a metric means, how a feature behaves, setup steps, plan and credit rules — then reads the best result withread_doc. Needs no project_id or project access.
Columns:
title, path, url, snippet
Pass a result’s path to read_doc.
read_doc
Read the full markdown content of a single documentation page. Pass thepath returned by search_docs (e.g. metrics/brand-metrics/visibility). Needs no project_id or project access.
Returns:
{ title, path, url, content }. Returns a 404 if no page matches the path.
Write tools
Write tools let the assistant edit your project configuration: brands, prompts, tags, topics, products, categories, and the brand profile. Every write tool is flaggedreadOnlyHint: false, and every delete_* tool is flagged destructiveHint: true. Clients that honor MCP annotations (Claude, Cursor, and most others) prompt for explicit confirmation before the call runs. Some deletes cascade, as noted below.
Brands, prompts, tags, and topics also have bulk variants (create_brands, update_brands, delete_brands, create_prompts, update_prompts, delete_prompts, create_tags, update_tags, delete_tags, create_topics, update_topics, delete_topics) for handling up to 50 items in one call. Bulk tools return per-item results so partial failures don’t block the rest of the batch.
Products and categories are managed only in bulk (create_products, update_products, delete_products, create_categories, update_categories, delete_categories), up to 1000 items per call.
Prompts can also be archived (archive_prompt / unarchive_prompt) to stop or resume running them without deleting their history.
There’s also a small CRUD set for custom domain and URL classifications that extends the built-in classification taxonomy. Create the classification once, then assign it to specific domains or URLs as you find them.
All write tools require organization-owner access and a
project_id. Ask the assistant to look up IDs with the matching list_* tool before any write call so you see exactly what is about to change.create_brand
Create a new tracked brand in a project (own brand or competitor).
Returns:
{ id }. The created brand ID.
update_brand
Update a brand’s name, regex, aliases, domains, or color. Changes to name, regex, or aliases trigger a background metric recalculation. Further edits during the recalc will fail; wait a few minutes and retry. Color changes don’t trigger recalculation.
Returns:
{ success: true }.
delete_brand
Soft-delete a brand. Destructive.
Returns:
{ success: true }.
create_brands
Create up to 50 brands in a single call. Duplicates (matched case-insensitively on name) are returned inskipped instead of failing the batch.
Returns:
{ created, skipped }.
created:[{ id, name }]skipped:[{ name, reason: "duplicate" }]
delete_brands
Soft-delete up to 50 brands in a single call. Destructive.
Returns:
{ deleted, skipped }.
deleted:[{ id }]skipped:[{ id, reason: "not_found" | "already_deleted" }]
update_brands
Update up to 50 brands in a single call. Per item, set any ofname, regex, aliases, domains, color. Changes to name, regex, or aliases trigger a background metric recalculation per brand; a brand updated mid-recalculation is rejected.
Returns:
{ updatedCount, skipped, rejected }. Successful items collapse to updatedCount; skipped and rejected list any items that didn’t apply.
create_prompt
Create a new prompt in a project. May consume plan credits.
Returns:
{ id }. The created prompt ID.
update_prompt
Update a prompt’s topic and/or tags.tag_ids fully replaces the existing tag set. Pass topic_id: null to detach the prompt from its topic.
Returns:
{ success: true }.
delete_prompt
Soft-delete a prompt. Destructive. Cascades to the prompt’s chats, which are soft-deleted too.
Returns:
{ success: true }.
create_prompts
Create up to 50 prompts in a single call. May consume plan credits. Accepts existingtopic_id and tag_ids only. This tool does not auto-create topics or tags; unknown IDs land in rejected.
Returns:
{ created, skipped, rejected, warning? }.
created:[{ id, text, country_code }]skipped:[{ text, country_code, reason: "duplicate" }]rejected:[{ text, country_code, reason: "limit_exceeded" | "invalid_topic" | "invalid_tag", message }]warning: optional plan-credit warning string when the batch was partially accepted
delete_prompts
Soft-delete up to 50 prompts. Destructive. Each delete is enqueued asynchronously; the response reports which IDs were queued, skipped, or could not be enqueued.
Returns:
{ queued, skipped, rejected }.
queued:[{ id }]skipped:[{ id, reason: "not_found" | "already_deleted" }]rejected:[{ id, reason: "enqueue_failed", message }]
update_prompts
Update the topic and/or tags of up to 50 prompts in a single call. Per item, passtag_ids to fully replace the prompt’s tag set, or topic_id: null to detach its topic. Topic and tag IDs must already exist.
Returns:
{ updatedCount, skipped, rejected }. Successful items collapse to updatedCount; skipped and rejected list any items that didn’t apply.
archive_prompt
Archive a prompt (setsis_archived = true) so it stops running while its chats and history stay intact. Use this instead of delete_prompt when the data should be retained.
Returns:
{ success: true }.
unarchive_prompt
Unarchive a prompt (setsis_archived = false), reactivating it so it resumes running. Subject to the project’s active-prompt plan limit.
Returns:
{ success: true }.
create_tag
Create a new tag. Tags are cross-cutting labels that can be attached to prompts.
Returns:
{ id }. The created tag ID.
update_tag
Update a tag’s name, color, or group.
Returns:
{ success: true }.
delete_tag
Soft-delete a tag and detach it from every prompt it’s attached to. Destructive.
Returns:
{ success: true }.
create_tags
Create up to 50 tags in a single call. Duplicates (matched case-insensitively on name) land inskipped.
Returns:
{ created, skipped }.
created:[{ id, name }]skipped:[{ name, reason: "duplicate" }]
delete_tags
Soft-delete up to 50 tags in a single call and detach them from every prompt they’re attached to. Destructive.
Returns:
{ deleted, skipped }.
deleted:[{ id }]skipped:[{ id, reason: "not_found" }]
update_tags
Update up to 50 tags in a single call (name and/or color per item). System tags are skipped.
Returns:
{ updatedCount, skipped, rejected }. Successful items collapse to updatedCount; skipped (includes system tags) and rejected list any items that didn’t apply.
update_tag_group
Rename and/or recolor a user-defined tag group. The change applies to every tag in the group. Provide a newname, a new color, or both.
Returns:
{ tag_count }. The number of tags affected.
delete_tag_group
Delete a user-defined tag group. Destructive. By default its tags are kept and ungrouped; setdelete_tags: true to delete the tags themselves and detach them from every prompt.
Returns:
{ tag_count }. The number of tags affected.
create_topic
Create a new topic. Topics group related prompts.
Returns:
{ id }. The created topic ID.
update_topic
Rename a topic.
Returns:
{ success: true }.
delete_topic
Soft-delete a topic. Destructive. Associated prompts are detached (not deleted); any AI-generated prompt suggestions under the topic are deleted.
Returns:
{ success: true }.
create_topics
Create up to 50 topics in a single call. Duplicates (matched case-insensitively on name) land inskipped. Items beyond the project’s topic limit land in rejected.
Returns:
{ created, skipped, rejected }.
created:[{ id, name }]skipped:[{ name, reason: "duplicate" }]rejected:[{ name, reason: "limit_exceeded", message }]
delete_topics
Soft-delete up to 50 topics in a single call. Destructive. Associated prompts are detached (not deleted); any AI-generated prompt suggestions under the topics are deleted.
Returns:
{ deleted, skipped }.
deleted:[{ id }]skipped:[{ id, reason: "not_found" | "already_deleted" }]
update_topics
Rename up to 50 topics in a single call.
Returns:
{ updatedCount, skipped, rejected }. Successful items collapse to updatedCount; skipped and rejected list any items that didn’t apply.
create_products
Create products in a project. Up to 1000 per call. Each product needs aglobal_brand_id (resolve via list_global_brands) and a name unique within that brand.
Returns:
{ created, rejected } per item. Rejection reasons: name_conflict, brand_not_found, category_not_found.
update_products
Update products by id (resolve vialist_products). Up to 1000 per call. Per item, set any of name (unique within the brand), description, image_url, price_override (replaces all overrides; {} clears them), category_ids (replaces the product’s categories; [] uncategorizes). Omitted fields are left unchanged.
Returns:
{ updated, skipped, rejected } per item. An item with nothing to apply is skipped; an unsatisfiable change (name conflict, unknown category) is rejected.
delete_products
Delete products by id. Destructive. Up to 1000 per call.
Returns:
{ deleted, skipped } per item (skipped reason: not_found).
create_categories
Create product categories. Up to 1000 per call, applied in order. Each needs aname and an optional parent_id — omit it for a top-level category, or pass another category’s id to nest it underneath. A name must be unique among its siblings.
Returns:
{ created, rejected } per item. Rejection reasons: parent_not_found, name_conflict.
update_categories
Rename and/or move categories by id (resolve vialist_categories). Up to 1000 per call. Each item sets name (rename), parent_id (move under that category, or null to promote to the top level), or both.
Returns:
{ updated, rejected } per item. Rejection reasons: not_found, name_conflict, invalid_move (nesting a category inside itself).
delete_categories
Delete categories by id. Destructive. Up to 1000 per call. A deleted category’s children and products move up to its parent — a top-level delete sends children to the top level and its products to Uncategorized.
Returns:
{ deleted, rejected } per item. Rejection reasons: not_found, name_conflict (a child moved up would clash with an existing sibling name).
create_domain_classification
Define a new custom domain classification entity on a project. This creates the classification but does not assign it to any domain — useassign_domain_classification for that.
Returns:
{ id }.
delete_domain_classification
Permanently delete a custom domain classification entity. Destructive. Cascades through the override table — any domain currently assigned this classification falls back to its heuristic classification. To clear a single domain instead, useunassign_domain_classification.
Returns:
{ success: true }.
assign_domain_classification
Assign a built-in classification (Corporate, Competitor, Editorial, Institutional, Other, Reference, UGC, You, Related) or the name of a custom domain classification to a domain. Overrides any heuristic classification. The override applies at apex granularity.
If a display label collides with an existing custom classification name, the custom classification wins — pass the built-in enum value (e.g. OTHER) to force the built-in.
Returns:
{ success: true }.
unassign_domain_classification
Clear the classification override on a domain, restoring its heuristic classification. Does not delete the custom classification entity itself.
Returns:
{ success: true }.
create_url_classification
Define a new custom URL classification entity on a project. This creates the classification but does not assign it to any URL — useassign_url_classification for that.
Returns:
{ id }.
delete_url_classification
Permanently delete a custom URL classification entity. Destructive. Cascades through the override table — any URL currently assigned this classification falls back to its heuristic classification. To clear a single URL instead, useunassign_url_classification.
Returns:
{ success: true }.
assign_url_classification
Assign a built-in classification (Homepage, Category Page, Product Page, Listicle, Comparison, Profile, Alternative, Discussion, How-To Guide, Article, Other) or the name of a custom URL classification to a URL. Overrides any heuristic classification. The override applies to the normalized URL form.
If a display label collides with an existing custom classification name, the custom classification wins — pass the built-in enum value (e.g. OTHER) to force the built-in.
Returns:
{ success: true }.
unassign_url_classification
Clear the classification override on a URL, restoring its heuristic classification. Does not delete the custom classification entity itself.
Returns:
{ success: true }.
set_project_profile
Replace the project’s brand profile. Every field is required, so callget_project_profile first, merge your changes into the existing values, then send the complete profile here. Saving triggers a background refresh of the project’s prompt suggestions. The project display name is not part of the profile and can’t be changed via this tool.
marketSize is one of: Neighborhood, City, State/Province, National, Continental Bloc, Global.
Returns: { success: true }.
Report filters and dimensions
Filtering
The three report tools support filters to narrow results. Each filter looks like this:Standard filter fields
These all usein / not_in operators with a values array.
Numeric filters
Domain and URL reports also accept two numeric filters. These usegt / gte / lt / lte operators with a single value (not values).
mentioned_brand_count: filter by number of unique brands mentioned alongside a source.
gap: gap analysis. Excludes sources where your own brand is mentioned, then filters by how many competitor brands are present. This is Peec’s most actionable competitive filter: it finds content where competitors appear but you don’t.
Operators
You can combine multiple filters. They’re joined with AND logic.
Sorting
The three report tools accept anorder_by array that sorts results before pagination. Each entry is { field, direction }. direction is asc or desc and defaults to desc. Multiple entries create a multi-key sort, applied in order.
When
order_by is omitted, each report falls back to a sensible default ordering.
Dimensions
Dimensions break down results into rows grouped by a specific field. Without dimensions, results are totals for the entire date range.
You can combine dimensions. For example,
["date", "model_channel_id"] gives you daily trends per AI engine.