> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.writesonic.com/llms.txt > Use this file to discover all available pages before exploring further. # Tools Reference > Complete reference for all 87 tools available in the Writesonic MCP server. All tools require a `project_id`. Always call `get_all_projects` first to get your project ID. Most tools are **read-only** — the [Management Tools](#management-tools) section lists the tools that create, update, or delete data. ## Common Parameters Most tools share these optional parameters: | Parameter | Type | Description | | ------------ | ------ | --------------------------------------------------------------------- | | `project_id` | string | **Required.** Your project ID from `get_all_projects` | | `filters` | object | Narrow results by topic, market, model, etc. | | `order_by` | array | Sort results, e.g. `[{"field": "visibility_score", "order": "desc"}]` | | `pagination` | object | Limit results, e.g. `{"limit": 10, "offset": 0}` | | `metrics` | array | Request additional computed fields in the response | *** ## Data Fetching Tools These tools return lists of individual records. ### get\_all\_projects List all projects accessible to the authenticated user. **Call this first** — every other tool requires the `project_id` returned here. ### get\_all\_prompts Fetch all tracked search queries (prompts) with visibility scores, mention counts, and performance indicators. Use this to discover which queries are being monitored. ### get\_all\_topics Fetch topic categories that group related prompts. Use topic IDs for filtering in other tools. ### get\_all\_tags Fetch custom tag labels applied to prompts. Use tag IDs for filtering in other tools. ### get\_all\_citations Fetch individual citation URLs where the brand was referenced in AI responses. For aggregated counts, use `query_citation_report` instead. ### get\_all\_websites Fetch all tracked websites (your brand + competitors). Use this for competitive benchmarking and to get website IDs for filtering. ### get\_all\_keywords Fetch keywords found in AI responses related to the brand. Useful for content strategy and understanding brand perception. ### get\_all\_models Fetch all tracked AI platforms (ChatGPT, Perplexity, Claude, Gemini, etc.) with per-platform metrics. ### get\_all\_markets Fetch all geographic markets being tracked. Use market IDs for filtering in report queries. ### get\_all\_domains Fetch citing domains aggregated by domain. Unlike `get_all_citations` which returns individual URLs, this provides a higher-level view. *** ## Report Query Tools These tools return aggregated metrics grouped by dimensions you specify. ### Common Report Parameters | Parameter | Type | Description | | --------------------------- | ------ | -------------------------------------------------------------------------------------- | | `project_id` | string | **Required.** | | `dimensions` | array | **Required.** Group by: `topic`, `market`, `model`, `prompt`, `tag`, `date`, `website` | | `date_aggregation_interval` | string | `day`, `week`, or `month` — only applies when `date` is in dimensions | | `website_type` | string | `SELF` (your brand only) or `SELF+COMPETITORS` (all tracked websites) | | `filters` | object | Narrow by topic, market, model, etc. | | `order_by` | array | Sort results | | `pagination` | object | Limit results | ### query\_performance\_report Aggregated performance metrics: **share of voice**, **citation share**, **visibility score**, and **mention counts**. This is the main analytics tool for understanding brand performance. **Example dimension combinations:** * `["date"]` with `month` interval — monthly visibility trend * `["model"]` with `website_type: "SELF"` — per-platform brand performance * `["topic", "date"]` — topic performance over time * `["website", "market"]` — compare brand vs competitors by region ### query\_citation\_report Aggregated citation metrics: **citation counts**, **unique pages**, and **unique domains** grouped by dimensions. **Example dimension combinations:** * `["model"]` with `website_type: "SELF"` — citations by AI platform * `["date"]` with `month` interval — citation trend over time * `["model", "domain"]` — top citing domains per AI model ### query\_sentiment\_report Sentiment analysis metrics: **keyword occurrences** and **positive sentiment scores**. **Example dimension combinations:** * `["model"]` with `website_type: "SELF"` — sentiment by AI platform * `["date"]` with `month` interval — sentiment trend * `["topic"]` — sentiment breakdown by topic *** ## Project Overview Tools High-level dashboards and trends for a whole project. ### get\_kpi\_summary KPI summary card for a project — total visibility, mention count, citations, and sentiment breakdown, plus deltas vs. the previous period. Use this as a single-call dashboard view. ### get\_project\_visibility\_trends Project-wide visibility trends over time, aggregated across all tracked prompts. Requires `graph_type` (`visibility` or `citation_share`); supports `aggregate_level` (`daily`, `weekly`, `monthly`). *** ## Prompt Analytics Tools Leaderboards, rankings, and deep-dive analytics for individual tracked prompts. ### get\_all\_prompts\_with\_metrics Flat list of every tracked prompt with rolled-up metrics — visibility, mention count, citations, last-run date. ### get\_prompts\_leaderboard Ranked leaderboard of tracked prompts, by visibility score by default. Returns prompt text, visibility score, mention count, and search volume. ### get\_prompts\_not\_mentioning\_you High-volume tracked prompts where your brand is **not** appearing in AI answers — the gaps to close. Includes the competitors who do appear. ### get\_top\_prompts\_by\_volume Highest-search-volume tracked prompts in a project. Use this to prioritize the prompts real users ask most. ### get\_top\_prompts\_driving\_visibility Prompts where your brand appears most often in AI answers — the prompts contributing most to your overall AI visibility. ### get\_prompt\_info Static metadata for a single tracked prompt: text, topic, tags, intent, monthly search volume, branded flag, markets, and platforms. The `prompts` filter must resolve to exactly one prompt. ### get\_prompt\_answers The AI-generated answers for a single tracked prompt, grouped and ranked across runs, with platform, mentioned brands, and citations. ### get\_prompt\_citations Pages that AI platforms cite when answering a single tracked prompt — the source URLs the AI grounded its answer in. ### get\_prompt\_snippets Short text excerpts from AI answers for a prompt, focused on the surrounding context where brand mentions occur, with sentiment polarity. ### get\_prompt\_trends Time-series of visibility and mention metrics for one or more tracked prompts. Supports `aggregate_level` (`daily`, `weekly`, `monthly`) and event overlays. ### get\_prompt\_sentiment\_trends Time-series of sentiment polarity (positive / neutral / negative) for AI mentions of brands inside a single tracked prompt. ### get\_prompt\_search\_queries Related search queries surfaced for a tracked prompt — the broader query fan-out the AI considered when generating its answer. ### get\_prompt\_result\_details Full detail snapshot of a single AI-platform run for one prompt: the raw response text, extracted citations, brand mentions, and run metadata. ### get\_prompt\_result\_compare Compare a single prompt result against its baseline (typically the prior run), with citation deltas and mention diffs. ### get\_prompt\_results\_compare Diff two specific AI response runs for the same prompt by `current_result_id` and `previous_result_id` — side-by-side text, citation, and mention changes. *** ## AI Answer Tools Browse and analyze the raw AI answers collected across your project. ### get\_all\_ai\_answers All AI answers across every tracked prompt that mention your brand or competitors. Useful for bulk export or browsing every mention. ### get\_ai\_answer\_counts Aggregate counts of AI answers across the project — total mentions with per-platform and per-mention-type breakdowns. ### get\_ai\_answer\_changes Period-over-period change report: which AI answers appeared or disappeared between two date ranges. Use to detect emerging mentions or sudden loss of visibility. Requires a `period_filter` date-range comparison. *** ## Citation Analytics Tools Citation analytics scoped to your whole domain or to a single page. Webpage-scoped tools require a `cited_page_url` filter. ### get\_domain\_citation\_trends Time-series of how often AI platforms cite your domain across all tracked prompts. Supports `aggregate_level` (`daily`, `weekly`, `monthly`). ### get\_domain\_citation\_platforms Which AI platforms cite your domain most, with citation counts and share per platform. ### get\_domain\_citation\_prompts Which tracked prompts produce the most AI citations to your domain. ### get\_domain\_citation\_topics Topic categories where your domain gets cited most — which themes drive your AI visibility. ### get\_domain\_citation\_answers Sample AI answers that cite your domain, for spot-checking the context AI presents alongside your citations. ### get\_domain\_pages\_cited Your domain's most-cited pages, ranked by how often AI platforms cite each page. ### get\_industry\_cited\_pages Pages AI platforms cite in your industry — including competitors and third-party domains. Shows the overall citation landscape, not just your own pages. ### get\_webpage\_citation\_trends Time-series of how often AI platforms cite a single specific page. Supports `aggregate_level` (`daily`, `weekly`, `monthly`). ### get\_webpage\_citation\_platforms Which AI platforms cite a specific page most often. ### get\_webpage\_citation\_prompts Which tracked prompts drive AI citations to a specific page. ### get\_webpage\_citation\_topics Topic categories driving AI citations to a specific page. ### get\_webpage\_citation\_answers Sample AI answers that cite a specific page. *** ## Action Center Tools Actionable recommendations: gaps to close, content to create, pages to fix. ### get\_actionables\_dashboard One-call summary of all actionable recommendations — broken pages, brand gaps, new-content opportunities, and content-optimization suggestions, with counts and estimated impact per category. ### get\_brand\_gap\_summary Summary of brand-gap opportunities — AI answers where your competitors are mentioned but you are not, grouped by the third-party site where the mention originated. ### get\_all\_brand\_gap\_opportunities Paginated list of brand-gap opportunities. Each entry is a third-party page cited by AI where competitors appear but you don't — a place where outreach or content placement could win the citation. ### get\_brand\_gap\_impact Estimated visibility impact if you claim each third-party brand-gap mention — what closing the gap is worth. ### get\_brand\_gap\_responses Sample AI responses that cite third-party sites in your brand-gap set, so you can see exactly what AI says alongside the competitor citation. ### get\_brand\_gap\_existing\_mentions AI answers that mention your brand via a third-party site citation — wins to reinforce rather than gaps to close. ### get\_all\_new\_content\_opportunities Topics and queries where you should create new content to capture AI visibility — areas where AI is answering but you have no page to be cited. ### get\_new\_content\_impact Estimated visibility gains if each new-content opportunity is published. Use to prioritize which content brief to ship first. ### get\_new\_content\_sample\_answers Sample AI answers from queries that a specific new-content opportunity would address. Requires `content_id`. ### get\_all\_optimization\_opportunities Existing pages on your domain that need optimization — pages AI cites where fixing structural issues would likely lift citation rate or sentiment. ### get\_optimization\_fixes Concrete AI-suggested fixes for the issues detected on an optimization page — rewrites, structural changes, and missing-section recommendations. Requires `editor_history_id`. ### get\_optimization\_page\_answers Sample AI answers that cite a specific page flagged for optimization. Requires `optimization_page_id`. ### get\_all\_broken\_pages Broken pages on your domain that AI platforms are citing — pages returning 4xx/5xx or unreachable. Highest-priority fixes, since AI is sending visitors to dead URLs. ### get\_broken\_pages\_impact Before/after metrics for broken-page fixes — the citation and visibility lift from pages already marked resolved. *** ## Prompt Explorer Tools Investigate prompts that aren't yet tracked in your project. ### get\_prompt\_explorer\_overview Investigate a single prompt: returns the AI platform's response text, the prompt's monthly search-volume estimate, and related prompts. Requires `prompt`; optional `platforms` (default `["chatgpt"]`; supports `perplexity`, `google_ai_overview`, `gemini`, `copilot`). Consumes one Prompt Explorer credit per investigation. ### get\_prompt\_explorer\_search\_history List previously-investigated prompts with pagination. Pass an entry's `history_id` to `get_prompt_explorer_overview` to re-fetch prior results without spending a new credit. *** ## Portfolio Tools Portfolios group tracked pages (URLs) for cross-page analytics. ### get\_all\_portfolios List every portfolio configured for the project. Use this to discover `portfolio_id` values needed by the other portfolio tools. ### get\_portfolio\_info Get the metadata for a single portfolio (id, name, site id). Requires `portfolio_id`. ### create\_portfolio Create a new portfolio. Requires `portfolio_name`. **Write operation.** ### edit\_portfolio Edit a portfolio's properties — rename plus add/remove pages in one call. Requires `portfolio_id`. **Write operation.** ### rename\_portfolio Rename an existing portfolio. Requires `portfolio_id` and `portfolio_name`. **Write operation.** ### add\_pages\_to\_portfolio Add one or more tracked pages (URLs) to an existing portfolio, with per-URL add status. **Write operation.** ### remove\_pages\_from\_portfolio Detach one or more tracked pages from a portfolio. The pages remain tracked at the site level. **Write operation.** ### delete\_portfolio Delete an entire portfolio. Optionally also stop tracking its pages via `should_stop_tracking` (default `false`). **Write operation.** *** ## Brand Radar Tools Brand Radar reports run asynchronous competitor scans across your configured prompts and target domains. ### list\_brand\_radar\_reports List the Brand Radar reports for a project. Use this to discover `report_id` values for the other Brand Radar tools. ### get\_brand\_radar\_report\_filters The filter values available for a specific Brand Radar report — the citing domains, citing pages, and queries that appear in the report's data. Requires `report_id`. ### create\_brand\_radar\_report Kick off a new Brand Radar report run. Reports run asynchronously — poll the read tools to track status. **Write operation.** ### delete\_brand\_radar\_report Soft-delete a single Brand Radar report by `report_id`. **Write operation.** ### bulk\_delete\_brand\_radar\_reports Soft-delete multiple Brand Radar reports in a single call via `report_ids`. **Write operation.** *** ## Management Tools These tools **create, update, or delete** project configuration. Use with care. ### create\_prompt Add a new prompt (tracked AI query) to the project. Requires `name`, `market_id`, and `topic_id`. The prompt runs daily across the configured AI platforms. ### update\_prompt Edit a tracked prompt — change its text, topic, market, tags, or intent. Requires `query_id`. Omitted fields are left unchanged. ### bulk\_delete\_prompts Delete one or more prompts from the project in a single call via `prompt_ids`. ### create\_topic Create a new topic. Topics are categories used to group prompts for slicing reports. Requires `name`. ### update\_topic Rename an existing topic. Requires `topic_id` and `name`. ### delete\_topic Delete a topic from the project. Optionally scope the deletion to a single market via `market_id`. ### create\_tag Create a new tag. Tags are user-defined labels used to group prompts and competitors. Requires `name`. ### update\_tag Rename a tag, change its color, or both. Requires `tag_id` plus at least one of `new_name` or `color`. ### delete\_tag Delete a tag and all its prompt and competitor associations. Requires `tag_id`. ### add\_competitors Add one or more competitor websites to the project so they appear in side-by-side reports. Requires `competitor_market_pairs`. ### bulk\_remove\_competitors Remove one or more tracked competitor websites from the project in a single call. Requires `competitor_market_pairs`. *** ## Planner Tools Meta tools that help orchestrate multi-step queries. ### tools\_info Returns a step-by-step execution plan for a natural-language question — the recommended tool sequence with dimensions, measures, and filters pre-filled. Use this before making tool calls when the right tool isn't obvious or the question needs multiple tools. Requires `question`. ### execute\_plan Run a multi-step plan as one TypeScript program server-side instead of round-tripping on every intermediate result. Provides `tool(name, args)` and `output(value)` in an async sandbox with a 30-second timeout. Use only when a plan needs 3+ chained tool calls with loops, joins, or aggregation — for 1–2 calls, call tools directly. Requires `code`.