# Tools All available tools for accessing and managing your AirOps workspace data. Tools are organized into two main areas: **AEO** (Answer Engine Optimization) for AI visibility analytics, and **Brand Management** for managing brand identity, writing style, and content creation. Additional tools provide access to Knowledge Bases for semantic search. Each tool supports filtering, field selection, sorting, and pagination. ## Workspace & Brand Kit ### `list_workspaces` List all workspaces you have access to. **Returns:** Workspace ID, name, slug, and subscription tier. | Parameter | Values | | ----------- | ----------------- | | **Filters** | name, tier | | **Sort** | name, created\_at | *** ### `list_brand_kits` List all Brand Kits you have access to. Returns `brand_management_enabled` and `aeo_enabled` flags for each Brand Kit, so you know which capabilities are available. * Use `get_brand_kit` for Brand Kits with `brand_management_enabled: true` * Use `get_insights_settings` for Brand Kits with `aeo_enabled: true` **Returns:** Brand Kit ID, name, about, URL, workspace name, `brand_management_enabled`, and `aeo_enabled`. | Parameter | Values | | ----------- | ---------------------------------------------------------------------------------- | | **Filters** | workspace\_name, brand\_name, brand\_url, brand\_management\_enabled, aeo\_enabled | | **Sort** | brand\_name, created\_at | *** ### `get_brand_kit` Get a specific Brand Kit by ID for brand management and content creation. Returns brand identity, writing style, and related entities. **Requires:** `id` **Returns:** Brand name, URL, about, writing persona, writing tone, status, and timestamps. Optionally includes related entities with nested data. | Parameter | Values | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Includes** | product\_lines, product\_lines.competitors, audiences, audiences.writing\_rules, content\_types, content\_types.content\_samples, content\_types.writing\_rules, regions, regions.writing\_rules, writing\_rules, custom\_variables | *** ### `get_insights_settings` Get AEO insights configuration for a Brand Kit. Returns the information needed to use any AEO and analytics tools. **Requires:** `id` **Returns:** Brand Kit ID, name, URL, countries, AEO status, prompt count, customer description, competitors with domain URLs, and personas. *** ### `update_brand_kit` Update a Brand Kit's base fields. Only provided fields are changed. **Requires:** `brand_kit_id` **Updatable fields:** `brand_name`, `brand_url`, `brand_about`, `writing_persona`, `writing_tone` *** ### `list_topics` List topics configured for a Brand Kit. **Requires:** `brand_kit_id` **Returns:** Topic ID, name, and color. | Parameter | Values | | ----------- | ----------------- | | **Filters** | name | | **Sort** | name, created\_at | *** ### `list_personas` List personas configured for a Brand Kit. **Requires:** `brand_kit_id` **Returns:** Persona ID, title, and description. | Parameter | Values | | ----------- | ------------------ | | **Filters** | title | | **Sort** | title, created\_at | *** ### `publish_brand_kit` Publish a Brand Kit's current draft so changes become active. All changes made via `update_brand_kit`, `manage_brand_kit_*`, and `suggest_brand_kit_edits` are applied to a draft. Publishing promotes the draft to active and creates a fresh draft from it. **Requires:** `brand_kit_id` {% hint style="warning" %} Always confirm with the user before publishing — this makes all pending changes live. {% endhint %} *** ### `get_legacy_brand_kit` Get a legacy Brand Kit by ID for migration workflows. Returns flat base fields from the old Brand Kit structure. Use `get_brand_kit` for Brand Kits with the new structure (`brand_management_enabled: true`). **Requires:** `id` **Returns:** Brand name, URL, about, writing persona, writing tone, visual branding (colors), writing samples, header case, countries, and legacy fields (brand\_customer, brand\_competitors, brand\_point\_of\_view, writing\_cta, writing\_cta\_url, writing\_rules). *** ## Brand Kit Management Tools for creating and updating Brand Kit entities. Each tool supports both create (omit `id`) and update (provide `id`) operations. On update, only provided fields are changed. {% hint style="info" %} Changes are saved to a **draft**. Use `publish_brand_kit` to make them active. {% endhint %} ### `manage_brand_kit_product_line` Create or update a product line for a Brand Kit. **Requires:** `brand_kit_id` **Fields:** `name` (required on create), `url`, `details`, `positioning`, `ideal_customer_profile` *** ### `manage_brand_kit_competitor` Create or update a competitor for a Brand Kit. Competitors must be associated with at least one product line. **Requires:** `brand_kit_id` **Fields:** `name` (required on create), `domain`, `product_line_ids` (at least one required) *** ### `manage_brand_kit_audience` Create or update an audience for a Brand Kit. **Requires:** `brand_kit_id` **Fields:** `name` (required on create), `description` *** ### `manage_brand_kit_region` Create or update a region for a Brand Kit. **Requires:** `brand_kit_id` **Fields:** `name` (required on create), `description`, `icon_name` (flag icon, e.g., `flag-us`) *** ### `manage_brand_kit_content_type` Create or update a content type for a Brand Kit. On create, you can provide a `sample_url` to seed the content type — the system will scrape the URL and use AI to generate fields automatically. **Requires:** `brand_kit_id` **Fields:** `name` (required on create), `template_outline`, `cta_text`, `cta_url`, `header_case` (title\_case, sentence\_case, custom), `header_case_custom_value`, `sample_url` (create only) *** ### `manage_brand_kit_content_sample` Create or update a content sample for a Brand Kit. On create, the sample URL is processed asynchronously to extract content. **Requires:** `brand_kit_id` **Fields:** `url` (required on create), `content_type_id` (required on create), `content` (update only), `audience_ids`, `region_ids` *** ### `manage_brand_kit_writing_rule` Create or update a writing rule for a Brand Kit. Rules can be global or scoped to a single content type, audience, or region (mutually exclusive). Scoping is set on create only. **Requires:** `brand_kit_id` **Fields:** `text` (required on create), `content_type_id` (create only), `audience_id` (create only), `region_id` (create only) *** ### `manage_brand_kit_custom_variable` Create or update a custom variable for a Brand Kit. Custom variables are discouraged for most use cases — prefer using regions, audiences, content types, or writing rules instead. **Requires:** `brand_kit_id` **Fields:** `name` (required on create), `value` (required on create) *** ### `suggest_brand_kit_edits` {% hint style="info" %} **Interactive App** — This tool renders a review UI in the conversation. Available on **Claude Web and Desktop only**. {% endhint %} Suggest edits to a Brand Kit's fields without applying them directly. Returns a side-by-side comparison of current vs suggested values, and the user can accept or reject each suggestion through an interactive UI before changes are applied. Call this tool once per entity (e.g., once per audience, once per content type). **Requires:** `brand_kit_id`, `suggestions` **Parameters:** | Parameter | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entity_type` | Which entity to edit: `brand_kit`, `audience`, `content_type`, `product_line`, `region`, `writing_rule`, `competitor`, `content_sample`, `custom_variable` | | `id` | Record ID for existing records (omit to suggest creating a new record) | | `suggestions` | Field name to suggested value pairs (valid fields depend on entity type) | | `title` | Optional heading for the review UI | **Supported fields by entity type:** | Entity Type | Fields | | ----------------- | ----------------------------------------------------------------------------------------------------- | | `brand_kit` | brand\_name, brand\_url, brand\_about, writing\_persona, writing\_tone | | `audience` | name, description | | `content_type` | name, template\_outline, cta\_text, cta\_url, header\_case, header\_case\_custom\_value | | `product_line` | name, details, positioning, ideal\_customer\_profile, url | | `region` | name, description | | `writing_rule` | text, region\_id (create only), content\_type\_id (create only), audience\_id (create only) | | `competitor` | name, domain, product\_line\_ids | | `content_sample` | url (create only), content\_type\_id (create only), content (update only), audience\_ids, region\_ids | | `custom_variable` | name, value | *** ## AEO Prompts & Answers ### `list_aeo_prompts` List tracked AI prompts for a Brand Kit. **Requires:** `brand_kit_id` **Returns:** Prompt ID, text, keyword, whether brand is mentioned, volume, topic ID, timestamps, mention\_rate, citation\_rate, and trends. | Parameter | Values | | ---------------- | ------------------------------------------------------------------------------------------ | | **Filters** | text, strategy, brand\_mentioned, topic\_id, prompt\_volume, mention\_rate, citation\_rate | | **Sort** | text, created\_at, prompt\_volume, mention\_rate, citation\_rate | | **Includes** | topic, tags | | **Date filters** | start\_date, end\_date, providers, countries, personas | *** ### `get_prompt_answers` Get AI answers for a specific prompt. **Requires:** `prompt_id` **Returns:** Answer ID, text (truncated), provider, country, brand\_mentioned, brand\_cited, timestamps. | Parameter | Values | | ------------ | ------------------- | | **Filters** | countries, personas | | **Sort** | created\_at | | **Includes** | persona | *** ### `get_answer` Get a specific AI answer by ID with full text content. **Requires:** `id` **Returns:** Full answer text (not truncated), provider, country, brand\_mentioned, brand\_cited, and optionally citations, mentions, and persona details. | Parameter | Values | | ------------ | ---------------------------- | | **Includes** | citations, mentions, persona | Use this after `get_prompt_answers` to retrieve complete answer text with citation URLs and positions. *** ## Citations & Domains ### `list_aeo_citations` List citations (URLs) with metrics for a Brand Kit. Shows individual URLs being cited in AI answers. **Requires:** `brand_kit_id` **Returns:** URL, domain name, domain category, citation count, citation share, citation rate, influence score, page type, brand sentiment, and trends. | Parameter | Values | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Filters** | domain\_category, domain\_id, topic\_id, brand\_mentioned, page\_type, brand\_referenced, brand\_sentiment, mentioned\_competitor\_domains | | **Sort** | citation\_count, citation\_share, citation\_rate, influence\_score | | **Date filters** | start\_date, end\_date, providers, countries, personas | **Domain categories:** Owned, Competitors, Social, Communities, Reviews, Media, Educational, Marketplaces, Products, Affiliates, Other *** ### `get_aeo_citation` Get details and prompts citing a specific URL. **Requires:** `brand_kit_id`, `id` (the citation/URL ID) **Returns:** URL details, citation metrics, influence score breakdown, page type, brand sentiment, and mentioned competitors. *** ### `list_aeo_domains` List domains cited in AI answers for a Brand Kit. Aggregated by domain with citation metrics. **Requires:** `brand_kit_id` **Returns:** Domain ID, name, category, logo URL, citation count, URL count, citation share, citation rate, and trends. | Parameter | Values | | ---------------- | ---------------------------------------------------------------------------------------------- | | **Filters** | domain\_category, topic\_id, brand\_mentioned, page\_type, brand\_referenced, brand\_sentiment | | **Sort** | citation\_count, citation\_share, citation\_rate | | **Date filters** | start\_date, end\_date, providers, countries, personas | *** ## Page Analytics ### `list_pages` List pages with AEO, Google Search Console, and GA4 metrics. **Requires:** `brand_kit_id` **Returns:** For each page: URL, folder path, primary keyword, and metrics: * **AEO:** citations\_count, citation\_rate, prompts\_count, and trends * **GSC:** clicks, impressions, ctr, position, and trends * **GA4:** traffic, sessions, engagement, average\_session\_engagement, and trends | Parameter | Values | | ----------------- | ------------------------------------------------------------------------------------------------------ | | **Filters** | Any metric field, url, folder\_name, primary\_keyword, session\_source, session\_medium | | **Sort** | All metric fields, url, folder\_name | | **Smart filters** | almost\_page\_one, losing\_clicks, rankings\_slipping, losing\_ai\_visibility, citation\_rate\_decline | **Smart filters** (use instead of manual filtering): | Filter | Description | | ----------------------- | -------------------------------------------- | | `almost_page_one` | Pages ranking #11-20 (quick wins for page 1) | | `losing_clicks` | Declining clicks with stable position | | `rankings_slipping` | Position declining over time | | `losing_ai_visibility` | Losing AEO citations | | `citation_rate_decline` | Losing AI authority with stable SEO | *** ### `get_page_details` Get detailed metrics for a specific page. **Requires:** `id` **Returns:** URL, folder, primary keyword, citation share, citation rate, unique cited questions count, GSC metrics (clicks, impressions, position, CTR), and all trends. | Parameter | Values | | -------------- | ---------------------- | | **Date range** | start\_date, end\_date | *** ### `get_page_prompts` Get AI prompts that cite a specific page. **Requires:** `brand_kit_id`, `web_page_id` **Returns:** Prompt ID, text, keyword, topic\_id, volume, total\_answers, answers\_with\_citations, citation\_rate, mention\_rate, and trends. | Parameter | Values | | -------------- | ------------------------------------------ | | **Filters** | providers, countries, personas, topic\_ids | | **Includes** | topic | | **Date range** | start\_date, end\_date | *** ## Analytics ### `query_analytics` Query analytics with flexible metrics, dimensions, and filters. BI-style interface for custom analysis. **Requires:** `brand_kit_id`, `metrics` **Returns:** Query results with requested metrics grouped by dimensions, plus metadata. **Metrics:** | Metric | Description | | -------------------- | ---------------------------------------- | | `mention_rate` | % of answers mentioning brand (0-100) | | `share_of_voice` | Brand mentions vs competitors (0-100) | | `citation_rate` | % of answers citing brand domain (0-100) | | `citation_share` | Brand citations vs all citations (0-100) | | `citation_count` | Absolute citation count | | `sentiment_score` | Average sentiment (0-100) | | `average_position` | Mean rank in answer lists | | `answer_count` | Total answers analyzed | | `first_mention_rate` | % where brand is mentioned first (0-100) | **Dimensions** (max 3): | Dimension | Description | | ----------------- | ----------------------------- | | `date` | Group by time period | | `provider` | Group by AI provider | | `topic` | Group by tracked topic | | `competitor` | Group by competitor | | `country` | Group by region/country | | `persona` | Group by customer persona | | `domain` | Group by cited domain | | `domain_category` | Group by citation source type | | Parameter | Values | | -------------- | -------------------------------------------------------- | | **grain** | daily, weekly, monthly, total (default: total) | | **Date range** | start\_date, end\_date (default: last 7 days) | | **Filters** | providers, topics, countries, personas, brand\_mentioned | | **Limit** | max rows (default 100, max 1000) | | **order\_by** | custom sort (e.g., "citation\_count DESC") | *** ### `analytics_chart` {% hint style="info" %} **Interactive App** — This tool renders a chart in the conversation. Available on **Claude Web and Desktop only**. {% endhint %} Query analytics and display as an interactive chart. Returns data with a UI reference for visualization. **Requires:** `brand_kit_id`, `metrics` **Returns:** Chart data with interactive visualization rendered in the conversation. | Parameter | Values | | --------------- | -------------------------------------------------------------- | | **chart\_type** | line, bar, pie, area (default: line) | | **metrics** | Same as query\_analytics | | **dimensions** | Same as query\_analytics (max 2 for line charts with grouping) | | **grain** | daily, weekly, monthly, total | | **Date range** | start\_date, end\_date | | **Filters** | providers, topics, countries, personas, brand\_mentioned | | **title** | Optional chart title | **Constraints:** * Only metrics from the same scale can be plotted together (percentage, count, or position) * Area and bar charts support single metrics with single dimensions * Line charts support up to 2 dimensions but only single metric when using 2 *** ## Reports ### `create_report` Create a saved analytics report with visualization modules. **Requires:** `brand_kit_id`, `name`, `modules` **Returns:** Report ID, name, and URL to view in AirOps. **Module configuration:** | Field | Description | Values | | --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | Display title | Any string | | `metrics` | What to measure | mention\_rate, share\_of\_voice, citation\_rate, citation\_share, citation\_count, sentiment\_score, average\_position, answer\_count, first\_mention\_rate | | `dimensions` | How to group | date, provider, topic, country, persona, domain, competitor, domain\_category | | `grain` | Time aggregation | daily, weekly, monthly, total | | `visualization` | Chart type | value (KPI), line (trend), bar (comparison), table (data) | | `filters` | Data filters | start\_date, end\_date (required), providers, topic\_ids, personas, region | | `layout` | Grid position | x, y, w, h (optional) | *** ### `list_reports` List saved analytics reports. **Requires:** `brand_kit_id` **Returns:** Report ID, name, created\_at, updated\_at. | Parameter | Values | | ------------ | ------------------------------ | | **Filters** | name | | **Sort** | name, created\_at, updated\_at | | **Includes** | modules | *** ### `get_report` Get a specific report by ID. **Requires:** `brand_kit_id`, `id` **Returns:** Report ID, name, timestamps. With `includes: ['modules']`, returns full module configurations. *** ## Action Grids ### `create_action_grid` Create an action grid for page optimization with power agents. **Requires:** `brand_kit_id`, `action_type`, `rows` **Returns:** Grid ID and URL to view in AirOps. **Action types:** | Action Type | Row Fields | Use Case | | ------------------------------ | ---------------------------------------------------- | ------------------------------ | | `visibility_gap` | url, folder, questions | Pages needing content refresh | | `popular_query_gap` | keyword, questions, relative\_volume\_score | High-volume keywords to target | | `content_outreach` | url, questions, competitors | Content for outreach campaigns | | `community_outreach` | url, thread, questions | Community threads to engage | | `competitor_dominated_keyword` | keyword, questions, competitors, mention\_rate | Keywords competitors own | | `highly_cited_thread` | cited\_url, domain\_url, questions, citation\_rate | High-performing threads | | `rising_third_party_content` | cited\_url, domain\_name, questions, citation\_rates | Rising competitor content | | `losing_ai_visibility` | url, folder, questions, citation\_loss\_percent | Pages losing citations | | `almost_page_one` | url, folder, average\_serp\_position | Pages close to page 1 | | `blue_ocean` | keyword, questions | Untapped keyword opportunities | Each action type has specific row fields. The grid is created in AirOps with power agent columns configured for the action type. *** ## Knowledge Bases ### `list_knowledge_bases` List all Knowledge Bases you have access to. Knowledge Bases store documents for semantic search. **Returns:** Knowledge Base ID, name, workspace ID, status, and document count. Only Knowledge Bases with status `ready` can be searched. | Parameter | Values | | ----------- | ------------------------------------ | | **Filters** | workspace\_name, name, workspace\_id | | **Sort** | name, created\_at | *** ### `search_knowledge_base` Search a Knowledge Base for relevant content using semantic similarity. **Requires:** `knowledge_base_id`, `query` **Parameters:** `top_k` (number of results, 1-20, default 5) **Returns:** Matching content ranked by relevance. *** ## Automated Feedback {% hint style="info" %} The MCP server includes a built-in `automated_feedback_report` tool that the AI assistant uses automatically behind the scenes. When a query can't be resolved or tool errors occur repeatedly, the assistant submits a feedback report to the AirOps team — no action needed on your part. This helps us continuously improve the MCP experience. {% endhint %} *** ## Query Options All list tools support: | Option | Description | | -------------- | ------------------------------------------------------------------------ | | **Filters** | Narrow by field values (EQUALS, CONTAINS, EQ, NEQ, GT, LT, GEQ, LEQ, IN) | | **Includes** | Request related data in one call | | **Fields** | Select specific fields to return | | **Sort** | Order by supported fields (prefix `-` for descending) | | **Pagination** | Control results with `page` and `per_page` (max 100) | *** ## AI Providers Available provider values for filtering: * `chat_gpt` * `gemini` * `perplexity` * `google_ai_mode` * `google_ai_overview` *** ## Next Steps * [Use Cases](https://docs.airops.com/mcp/use-cases) — Reporting and optimization examples * [FAQ](https://docs.airops.com/mcp/faq) — Common questions