Tools

Reference for all AirOps MCP tools

All available tools for accessing and managing your AirOps workspace data. Tools are organized into several areas: AEO (Answer Engine Optimization) for AI visibility analytics, Brand Management for managing brand identity, writing style, and content creation, Grids for reading, writing, and executing grid workflows programmatically, and 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

Always confirm with the user before publishing — this makes all pending changes live.

---

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.

Changes are saved to a draft. Use publish_brand_kit to make them active.

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

Interactive App — This tool renders a review UI in the conversation. Available on Claude Web and Desktop only.

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

Interactive App — This tool renders a chart in the conversation. Available on Claude Web and Desktop only.

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.

---

Grids

Tools for reading, writing, and executing workflows in AirOps Grids programmatically. Use these to automate grid operations — populate data, trigger workflow execution, monitor progress, and retrieve results.

list_grids

List grids the authenticated user has access to. Use includes: ["grid_tables.grid_columns"] to get the table and column structure needed for other grid tools.

Returns: Grid ID, name, workspace ID, and optionally table and column details (ID, title, data type, position).

Parameter	Values
Filters	name, workspace_id
Sort	name, updated_at, created_at
Includes	grid_tables.grid_columns

---

read_grid

Read rows from a grid table. Returns rows as objects with column titles as keys.

Requires: grid_id, grid_table_id

Returns: Grid metadata, columns (with writable flag), and row data with pagination info.

Parameter	Type	Default	Description
filters	array	—	Filter by column values
filters[].column_id	integer	—	Column ID to filter on
filters[].operator	string	—	CONTAINS, NOT_CONTAINS, EMPTY, NOT_EMPTY, =, !=, >=, <=, >, <
filters[].value	string	—	Filter value (not required for EMPTY/NOT_EMPTY)
column_ids	array	all	Column IDs to include in results
limit	integer	50	Rows per page (1–100)
offset	integer	0	Row offset for pagination
truncate	integer	0	Max characters per cell (0 = no truncation)

---

write_grid

Create or update rows in a grid table. Maximum 1000 rows per call.

Requires: grid_id, grid_table_id, mode, rows

Parameter	Type	Description
mode	string	create to add new rows, update to modify existing rows
rows	array	Row objects with column titles as keys. For update mode, include __id with the row ID

Returns: rows_created (create mode) or rows_updated and cells_updated (update mode).

Values can be strings, numbers, booleans, arrays, or objects. Arrays and objects are stored as JSON. Column titles must exactly match existing grid columns — use add_grid_column to create new columns first.

---

add_grid_column

Add a new column to a grid table. Use this before write_grid when you need to write to a column that doesn't exist yet.

Requires: grid_id, grid_table_id, title, data_type

Parameter	Type	Description
title	string	Column title
data_type	string	text, number, datetime, markdown, url, html, image_from_url, json, single_select
position	integer	Optional column position (appended at end if omitted)

Returns: Created column's ID, title, data type, and position.

---

run_grid_rows

Trigger execution of one or more grid rows. Runs all workflow columns for each row in dependency order. Execution is asynchronous — returns immediately with execution metadata. Use get_grid_row_execution_status to check progress. Maximum 50 rows per call.

Requires: grid_id, grid_table_id, grid_row_ids

Parameter	Type	Description
grid_row_ids	array of integers	IDs of the rows to execute (max 50)

Returns: For each row: grid_row_id, row_execution_id (for status polling), and columns_to_execute count.

---

get_grid_row_execution_status

Check the status of grid row executions after calling run_grid_rows. Maximum 50 executions per call.

Requires: grid_id, row_execution_ids

Parameter	Type	Description
row_execution_ids	array of integers	Execution IDs returned by run_grid_rows (max 50)

Returns: Per-execution overall status and per-column status details.

Status	Description
running	Execution in progress
completed	All columns executed successfully
error	One or more columns failed
cancelled	Execution was cancelled
review_needed	Waiting for human review

---

Example: Automated Grid Pipeline

A typical programmatic workflow using grid tools:

1. Discover — Call list_grids with includes to find the grid and its column structure

2. Populate — Call write_grid with mode create to add rows

3. Execute — Call run_grid_rows to trigger workflow columns

4. Monitor — Poll get_grid_row_execution_status until all rows complete

5. Retrieve — Call read_grid to pull the results

6. Update — Optionally call write_grid with mode update to write data back

---

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

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.

---

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 — Reporting and optimization examples

• FAQ — Common questions