AirOps

Initiate a direct file upload for use with Brand Kit visual tools. This returns an upload URL (pointing directly to the storage service), upload headers, and a signed_id. The workflow is: 1. Call this tool with the Brand Kit ID and file metadata (filename, content_type, byte_size, checksum). The checksum must be the Base64-encoded MD5 digest of the file contents. 2. Upload the file to the returned `upload_url` using an HTTP PUT with **all** the provided `upload_headers`. No additional authentication is needed — the URL is a time-limited presigned URL. Example: curl -X PUT -H "Content-Type: <type>" -H "Content-MD5: <checksum>" --upload-file <path> "<upload_url>" 3. Pass the returned `signed_id` to a manage tool (e.g. manage_brand_kit_logo_variant, manage_brand_kit_visual_example, or manage_brand_kit_font). IMPORTANT: Always confirm with the user before initiating an upload.

create_brand_kit_direct_upload

Record a recap entry summarizing the changes you made to a Brand Kit. Call this once, near the end of a session that mutated the Brand Kit draft — not for every edit. Do not call this tool if you made no Brand Kit draft mutations this session (for example, you only read the Brand Kit, suggested edits the user rejected, or worked on Playbooks, Campaigns, or Insights). Never create a recap that says nothing changed. Put the evidence behind the changes in `body_markdown`: verbatim quotes, source URLs, and pages. Example: create_brand_kit_recap_entry( brand_kit_id: 123, title: "Refreshed tone & voice and added 2 regions", body_markdown: "Made the tone more concise per the latest brand guidelines (https://acme.com/brand). Added US East and US West to support the Q3 launch." )

create_brand_kit_recap_entry

Create a new empty, general-purpose grid with the given name. The grid is created with a single empty sheet (zero rows, zero columns). Use add_grid_column to add columns and write_grid to add rows. If the user belongs to more than one workspace, workspace_id is required. Do not use this tool to act on AEO insights — use create_action_grid instead, which pre-populates power step columns and rows for a given AEO action type.

create_grid

Create a new sheet (grid table) within an existing grid. The sheet is created with zero rows and zero columns. Use add_grid_column to add columns and write_grid to add rows. A grid can contain at most 10 sheets.

create_grid_sheet

Initiate a direct file upload for a Knowledge Base. Returns a presigned S3 upload URL, the required upload headers, and a `signed_id` you'll use with `knowledge_base_add_file` to register the document. This is the first call in the two-step file ingestion flow — large files (PDFs, DOCX, MD, HTML, etc.) don't fit through the MCP transport, so the file bytes go directly from your client to S3. Workflow: 1. Call this tool with the file metadata (filename, content_type, byte_size, checksum). The checksum must be the Base64-encoded MD5 digest of the file contents. 2. PUT the raw file bytes to the returned `upload_url` with **all** the provided `upload_headers`. No additional authentication is needed — the URL is a time-limited presigned URL. 3. Pass the returned `signed_id` to `knowledge_base_add_file` to register the document. Only after step 3 is the file searchable. Example: > knowledge_base_create_direct_upload(knowledge_base_id: 1, filename: "report.pdf", content_type: "application/pdf", byte_size: 1234567, checksum: "...") # → { signed_id: "abc...", upload_url: "https://s3...", upload_headers: { ... } } > knowledge_base_add_file(knowledge_base_id: 1, signed_id: "abc...", name: "Q4 Report", document_type: "application/pdf") # → { document_ids: [42], status: "pending" } Maximum file size is 256 MB.

knowledge_base_create_direct_upload

Create one pending opportunity for a Campaign. In interactive Quill or OAuth sessions, summarize the proposed name, description, and target resources and get explicit confirmation first. Campaign strategy Playbooks infer their own Campaign. Other Playbooks must provide play_id, inspect existing Opportunities before creating more, and may create pending Opportunities without interactive confirmation when the Campaign write feature is enabled. For page_refresh, page_creation, reddit_thread_creation, youtube_video_creation, and youtube_engagement Campaigns, read the matching Opportunity rationale skill and pass its complete Markdown brief unchanged in description.

create_opportunity

Add a web page to a Brand Kit's AEO pages. The URL is normalized before the page is created, and the page is associated with the Brand Kit's configured AEO domain. The URL must be unique within the Brand Kit. IMPORTANT: Always show the user the URL and Brand Kit you plan to use and get explicit confirmation before calling this tool. You can verify the page was created by calling `list_pages` filtered by URL.

create_page

Create a new AEO topic on a Brand Kit. Topics are categories used to group AEO prompts. Behavior: - `name` must be unique within the Brand Kit. - `color` is optional. If omitted, a color is auto-assigned from the platform palette. Valid colors: light_grey, grey, green, teal, blue, purple, lilac, pink, red, coral, orange. - This tool does NOT create or assign prompts. Use `create_aeo_prompt` with the returned topic ID to add prompts to the topic. IMPORTANT: Always show the user the topic you plan to create (name and color) and get explicit confirmation before calling. You can verify the topic was created by calling `list_topics` filtered by name.

create_topic

Delete an AEO prompt from a Brand Kit. Use `list_aeo_prompts` to find the prompt ID and verify the prompt text before deletion. IMPORTANT: This action is destructive. Always show the user the exact prompt text and get explicit confirmation before calling this tool.

delete_aeo_prompt

Delete an AEO tag from a Brand Kit. Behavior: - This is a HARD delete. The tag is removed from the Brand Kit entirely. - All taggings on prompts that referenced this tag are also deleted (cascade via `Aeo::Tag has_many :taggings, dependent: :destroy`). Every prompt that had this tag will lose it. - The response includes `tagged_prompts_count`: the number of prompts that lost the tag. Use this to communicate the blast radius back to the user. IMPORTANT: This action is destructive and cannot be undone via this tool. Always show the user the tag name AND `tagged_prompts_count` (look it up first via `list_tags` + `list_aeo_prompts` if needed) and get explicit confirmation before calling.

delete_aeo_tag

Delete one or more writing rules from a Brand Kit. This edits the Brand Kit draft version only; it does not change the active (live) version. A failure deleting one rule does not block or roll back the others: the response reports which rules were deleted and which could not be. IMPORTANT: Always show the user exactly which writing rules will be deleted and ask for confirmation before calling this tool.

delete_brand_kit_writing_rules

Delete a grid column and any dependent columns (e.g. workflow output columns, playbook artifact columns). Cannot delete while row executions are running for the grid table. Returns the IDs of all columns deleted.

delete_grid_column

Permanently delete a Knowledge Base and ALL of its documents. This cascades through every document in the KB and drops the underlying vectors. This action cannot be undone. IMPORTANT: Always warn the user that deletion is permanent and irreversible, name the Knowledge Base being deleted, and ask for explicit confirmation before calling this tool.

knowledge_base_delete

Permanently delete a single document from a Knowledge Base. This action cannot be undone. IMPORTANT: Always warn the user that deletion is permanent and ask for explicit confirmation before calling this tool.

knowledge_base_delete_document

Delete one draft artifact reference by ID after removing its definition references. Also removes this artifact's Content Review configuration. Other artifacts and their score configurations, published versions, and session output files remain unchanged. Never publishes.

delete_playbook_artifact_reference

Delete one input by ID after removing its definition references. If Content Review uses it, ask the user to update Content Review in the web editor first. Never publishes.

delete_playbook_input_reference

Delete an AEO topic from a Brand Kit. Behavior: - This is a HARD delete. The topic is removed from the Brand Kit entirely. - Deletion is blocked when the topic has associated prompts. Use `list_aeo_prompts` filtered by `topic_id` to inspect prompts before deleting. - Candidate questions and question recommendations for the topic are deleted by model associations when the topic is deleted. IMPORTANT: This action is destructive and cannot be undone via this tool. Always show the user the topic name and associated prompt count, then get explicit confirmation before calling.

delete_topic

Discard the current prompt-assignment draft for a Brand Kit. Throws away ALL uncommitted edits — both your own and any unsaved edits the human user made in the UI — and re-mirrors a fresh empty draft from live. Live assignments are never touched. IMPORTANT: - This action is destructive and unrecoverable. Pending UI edits the user has not committed will be lost. - Always get explicit user confirmation before calling. - Calling discard when no draft exists is a no-op; a fresh empty draft is still created so further `update_aeo_prompt_assignments` calls work without setup.

discard_aeo_prompt_assignments

Apply targeted edits to one emitted Playbook session artifact. Read it with read_artifact first. Replace, insert before, or insert after an existing node using its _hash. An empty replacement deletes that node. Whole-document replacement is not supported. Markdown and HTML use rich-text nodes; CSV uses table rows and cells; target a cell's paragraph hash to edit its content. Changes apply directly to the collaborative artifact. Other artifacts and the Playbook configuration stay unchanged.

edit_artifact

Replace only the draft description. Read it first. Other fields stay unchanged. Never publishes.

edit_playbook_description

Replace only the live draft title. Read it first. Other fragments stay unchanged. Never publishes.

edit_playbook_title

Find possible existing or planned page matches for a bounded batch of Page Creation proposals. Searches the Brand Kit page inventory index using proposal-title tokens and also checks pending and accepted-but-unpublished Page Creation opportunities. Returns ranked candidates and match evidence; it does not classify candidates as duplicate, overlapping, or distinct.

find_page_creation_matches

Get one ad observed in ChatGPT or Google AI Mode answers. The 'id' parameter is the observed_creative_id returned by list_aeo_ads. Pass its provider in the providers array.

get_aeo_ad

Get prompts citing a specific URL. The 'id' parameter is the URL to look up. Request decay metrics or weekly_series through fields; they are omitted by default. Decay uses the selected date range and scope, with Monday-based weekly buckets.

get_aeo_citation

Get a specific page content update by ID. Its change_detection object carries the detection status and categories, plus a nested changes array (the before/after diff) on this single-update fetch. Track content updates.

get_aeo_page_content_update

Inspect the current prompt-assignment draft state for a Brand Kit without modifying anything. Read-only. This is the authoritative source for workspace estimated-answers numbers (live and draft). Call it whenever you need them — never compute or guess them yourself. In particular: - At the start of a session, to detect a pre-existing draft from unsaved UI edits. - Immediately after `commit_aeo_prompt_assignments`, to read the new live `estimated_answers` — the commit tool does not return them. - Before staging more changes via `update_aeo_prompt_assignments`, to compare against `max_answers`. Returns: - `has_draft`: whether a draft session exists for this brand kit. - `has_changes`: whether the draft has uncommitted edits relative to live (null if no draft). - `draft_id`: the draft's ID (null if no draft). - `live_estimated_answers`: current workspace estimated answers/month based on live assignments. - `draft_estimated_answers`: what the workspace estimated answers/month would be if the draft were committed now (null if no draft). - `max_answers`: the workspace's effective answers limit. - `limit_exceeded`: whether committing the draft now would exceed the limit (false if no draft).

get_aeo_prompt_assignments_status

Get a specific AI answer by ID with full text content. Get a single AI answer with full details. Use this to retrieve the complete answer text (not truncated), citations, and mentions. Use includes parameter to get citations, mentions, and persona details.

get_answer

Get an Answer Evaluation test run and its sample verdicts. Poll the same run until status is completed. Pending and running samples are not results. Keep polling bounded; if it does not complete, report its state and check the same run on the next turn.

get_answer_evaluation_test_run

Fetch a Brand Kit's brand identity (writing_tone, writing_persona) and associated entities (product lines, audiences, content types, regions, writing rules, custom variables, visual/design assets). Call AFTER `list_brand_kits` confirms `brand_management_enabled: true`. # Decision flow 1. Specific entity by ID → `includes=["<type>"]`, `filters=[{field: "<type>.id", operator: "EQ", value: <id>}]`. 2. Entity by name (product_lines, content_types, audiences, regions, custom_variables, visual_examples) → `includes=["<type>"]`, `filters=[{field: "<type>.name", operator: "CONTAINS", value: "<fragment>"}]`. 3. Find text content ("rule about tone", "any mention of Red List") → filter by the text field: `includes=["writing_rules"]`, `filters=[{field: "writing_rules.text", operator: "CONTAINS", value: "tone"}]`. 4. Structural discovery → small `includes` with `fields=["<type>.id","<type>.name"]` only. # Fields and includes Without `fields`, data contains only id, brand_name, brand_url, workspace_name, and status. Request brand_about, writing_persona, and writing_tone explicitly when you need brand context. Explicit `fields` returns exactly those data fields; associations remain opt-in via `includes`. `fields` selects declared fields, not associations. It never adds includes automatically. Example: `includes=["product_lines.competitors"]`, `fields=["product_lines.id","product_lines.name"]` returns those product-line fields plus nested competitors. Do not put `product_lines.competitors` in `fields`. Deeper field paths such as `content_types.writing_rules.id` are not supported; nested includes return the child resource's declared fields. `EQ` and `EQUALS` are interchangeable on fields supporting equality; text equality is case-insensitive. Other operators remain field-specific; check the schema. # Scale (typical kit vs outliers) Most kits are small — these rarely need filtering: - audiences, regions, usage_rules, palettes, content_samples: usually 0-2, rarely >10 - content_types, product_lines: usually 1-3 These have tails you must handle: - writing_rules: usually 3, outliers exceed 200. Never include in full without a filter — filter by text (CONTAINS) or by id. - competitors: usually 10, outliers exceed 250. Include via product_lines.competitors only when needed, and consider a name filter. - custom_variables: outliers exceed 150. Filter by name (CONTAINS) for known variables (e.g. "Red List"), or by value (CONTAINS) for content. - Scoped writing_rules via audience/region/content_type nesting: outliers exceed 200. Filter the parent by id or name first. # Writing rules — global vs scoped Writing rules are EITHER global OR scoped to a single audience/content_type/region (never both). For content targeting a specific audience/region/content_type, fetch BOTH: 1. Global: `includes=["writing_rules"]`, `fields=["writing_rules.id","writing_rules.text"]`. 2. Scoped: `includes=["content_types.writing_rules"]`, `fields=["content_types.id","content_types.name"]`. Rules appear under each content type. The same pattern applies to audiences and regions. Filter the parent first. `content_types.writing_rules` does NOT include global `writing_rules`; selecting `writing_rules.id` or `writing_rules.text` still requires the separate `writing_rules` include. Merge client-side. # Anti-patterns - `includes=["writing_rules","custom_variables","product_lines.competitors", "content_types.writing_rules"]` without filters → blows context on outlier kits. - Including associations without `fields` on a large kit → returns full text (template_outline, rule text, ICP) for every included row, despite the small root defaults. - Forgetting filters on `writing_rules`, `custom_variables`, or `competitors` — those are the three biggest tails. # Versioning `version: "draft"` reads pending edits; defaults to `"active"`. Use active for on-brand output unless the user explicitly asks for draft. `meta.version` identifies the selected reading version. `meta.draft_edited` describes the stored draft edit flag, including when data is active. It stays true after edit-then-revert and does not mean the draft differs from published content. Metadata is independent of `fields`. `unpublished_changes` is no longer a selectable field; exact change detection remains a publish guard.

get_brand_kit

Get a campaign by ID, including pending and accepted recommended campaigns, resource configuration, action grid IDs, and its recommendation record with the current hypothesis and brief when present. Campaigns are Plays that coordinate strategy playbooks, action grids, and related opportunities for improving AEO performance.

get_campaign

Check the status of grid row executions. Returns the overall status and per-column detail for each execution. Use this after run_grid_rows() to poll for completion. Maximum 50 executions per call.

get_grid_row_execution_status

Get AEO insights configuration for a Brand Kit, this includes the relevant information to use any AEO and analytics tools. Returns competitors, personas, prompt count, and other relevant information. Use `list_brand_kits` first to find Brand Kits with `aeo_enabled: true`.

get_insights_settings

Read the full reconstructed text content of a Knowledge Base document end-to-end — the loader-extracted text from every chunk concatenated in `position` order. Use when chunked search results aren't enough: summarizing a whole document, answering questions across an entire report, or reading back a doc before delete-and-recreate. For finding specific passages, prefer `search_knowledge_base`. Returns up to `max_chars` characters starting at `offset` (defaults to 0 and 200000). When the document is larger than the slice, the response includes `next_offset` (the value to pass on the next call to continue reading); when fully read, `next_offset` is `null`. For documents still indexing (`status: pending`) or in error (`status: error`), content may be empty — check `status` first. Content is reconstructed by joining chunks; minor overlap or duplication between adjacent chunks is possible depending on the original loader's chunking strategy. For the original source file, use the existing download path outside MCP.

knowledge_base_get_document

Get the indexing status of a Knowledge Base and its documents. Returns a Knowledge Base–level rollup (status, pending and total document counts) plus a paginated list of per-document statuses. Use this to monitor indexing after writes — only documents with status "ready" are returned by search_knowledge_base. Pass the returned `cursor` back to fetch the next page; pass `document_ids` to filter to specific documents.

knowledge_base_get_status

Get AEO metrics for a specific web page. Page details include citation share, citation rate, unique cited questions count, and Google Search Console metrics (clicks, impressions, position, CTR) with trends.

get_page_details

Get prompts citing a specific web page. Returns AI prompts that cite the page along with citation metrics (citation_rate, mention_rate) and trends. Use includes: ["topic"] to get topic details for each prompt.Prompts are the questions that can be asked about a brand or web page. They are the search queries that are used to get AI answers with citations and mentions.

get_page_prompts

Get the complete configuration for a Playbook. By default, reads the live editable draft (Latest). Pass version_number to read a specific published version. Authentication and score configuration references are retained, and the definition is returned as semantic Markdown. Credentials and score configuration bodies are never returned.

get_playbook

Get details and events for a Playbook session. Returns session metadata (status, playbook, last event type) plus a page of content/terminal events (text, reasoning, tool_call, tool_result, artifact, waiting_input, input_received, completed, completed_with_issues, failed, cancelled). Use after_id for cursor-based pagination to read further events. Note: text and reasoning content is capped at 2000 characters (content_truncated: true indicates more exists).

get_playbook_session

Get AI answers for a specific prompt/question. Prompt answers are the AI answers for a specific question/prompt asked to multiple AI providers and the answers are aggregated. The answers include whether the brand was mentioned and cited in the answer. To get full answer text, citations, and mentions, use the get_answer tool with the answer ID.

get_prompt_answers

Get a specific report by ID with its module configurations. Reports are saved analytics views for a Brand Kit. They contain modules that display different analytics metrics.

get_report