Keyword.com

Attach one or more tags to one or more keywords inside a single project. Pass `keyword_ids` plus at least one of `tag_ids` (existing tag ids), `tag_names` (strings), or both — `tag_names` create missing tags on the fly. Use this when the user explicitly asks to "tag", "label", or "categorize" keywords. For removing tags from keywords, use `detach_tag`. Foreign keyword ids (not in this project) and foreign tag ids are silently skipped — `attached_count` reflects only the rows that landed. Up to 1000 keyword_ids and 100 tag_ids/tag_names per call. Requires the 'write:data' scope.

attach_tag

Compare your ranking against up to 10 competitor domains for ONE keyword over a window. The rendered table is a per-competitor summary (current/best/worst/avg/gap_vs_you); the full per-day timeline (your rank vs each competitor side by side) is in the structured payload at `timeline[]`. Pass `competitor_domains` to compare against specific domains, or OMIT it to let the tool auto-pick the top `top_n` competitor domains from the most recent SERP scrape (your own domain is excluded automatically). Prefer the omit-and-autopick path for "who am I competing with on this keyword" questions so you can skip a separate `get_serp` round-trip. Use this when the user asks "how do I compare to competitor.com on this keyword", "show me head-to-head ranking vs example.com", or wants a focused you-vs-them view. For a project-wide competitor sweep, use `get_top_competitors`. For competitor rank history alone (no your-rank merge), use `get_keyword_competitors`. Default window is 30 days; max 366.

compare_with_competitor

Forward a contact-us message to the Keyword.com team — the same surface as the in-app 'Contact us' / 'Custom plan' dialog in Billing. Use when the user asks to talk to sales, request custom pricing, ask about AIV credit bundles, or otherwise wants a human to follow up. Do NOT use it as a generic chat / feedback channel; for 'the assistant could not answer' situations use `submit_feedback` instead. On success the team gets a ticket via the existing n8n workflow and the tool returns a short acknowledgment. The Laravel endpoint always returns 200 once the body validates, so a successful tool call means 'we forwarded it', not 'a human has read it yet'. Required fields: `name`, `help_topic`. `email` is optional when it can be resolved from the authenticated user and must be provided otherwise. Pick `help_topic` from the enum — the human-readable label is filled in automatically.

contact_us

Create a sub-project (a "group") under an existing parent project. Idempotent: returns the existing group if one with the same name already lives under that parent. Use this when the user explicitly asks to "create a group", "add a sub-project", or "split out a section of project X". For top-level projects use `add_project`. Returns `{project_id, parent_project_id, name, category, created}`. `created: false` means the group already existed and was returned as-is. Requires the 'write:data' scope.

create_group

Create a tag within a project. Idempotent: returns the existing tag if one with the same name already lives in that project. Use this when the user explicitly asks to "create a tag" or "add a tag" inside a project. For attaching an existing tag to keywords, use `attach_tag`. Returns `{tag_id, name, project_id, created}`. `created: false` means the tag already existed and was returned as-is. Requires the 'write:data' scope.

create_tag

Show the daily SERP for one keyword over a window. Returns one row per scraped day with the keyword rank and the organic listings (URL + title) ordered by rank. Use `days` for a lookback window or `start_date`+`end_date` for a specific range (e.g. set both to the same date to get a single day). The endpoint applies the user plan-tier history limit; the returned start_date may be later than requested if the plan caps history. By default each day shows the top 10 listings — pass `result_limit` (max 100) to fetch more, e.g. when investigating the full SERP for a single date.

get_serp

Soft-delete one or more tracked keywords. Pass an array of `keyword_ids` (1..1000 per call). Destructive. Only call when the user explicitly asks to "delete" or "remove" keywords. NEVER from generic cleanup / triage requests — ask the user to confirm first. If the user wants to pause tracking without losing data, archive the parent project instead via `archive_project`. Foreign keyword ids (not belonging to the authenticated user) are silently skipped — `deleted_count` reflects only the user's own rows. Requires the 'write:data' scope.

delete_keywords

Delete a project and all its keywords. Destructive — recovery requires customer support. Only call this when the user explicitly asks to "delete", "remove", or "permanently get rid of" a project. NEVER from generic cleanup, triage, or "I don't need this anymore" requests — ask the user to confirm first. If the user wants to pause tracking without losing data, use `archive_project` instead — it's reversible via `restore_project`. Requires the 'write:data' scope.

delete_project

Delete a tag from a project. Detaches the tag from every keyword that carried it; does not delete the keywords themselves. Destructive. Only call when the user explicitly asks to "delete" or "remove" a tag. NEVER from generic cleanup / triage requests — ask the user to confirm first. Returns `{tag_id, project_id, deleted}`. Requires the 'write:data' scope.

delete_tag

Remove one or more tags from one or more keywords inside a single project. Detach only — the tag itself stays in the project. Use this when the user explicitly asks to "untag", "remove a tag from", or "clear a tag" on keywords. For deleting the tag entirely, use `delete_tag`. Foreign keyword ids (not in this project) and foreign tag ids are silently skipped — `detached_count` reflects only the pivot rows that actually went away. Up to 1000 keyword_ids and 100 tag_ids per call. Requires the 'write:data' scope.

detach_tag

Find ranking pages whose first observed ranking appearance was in the last 7-90 days. Use for "are new pages starting to rank?" and "any new ranking clusters forming?".

serp_emerging_pages

Daily estimated-traffic time series for a project (window defaults to last 30 days). Filter by `tag_id` to scope to a tag. Use for "how many clicks am I getting / trending?" questions; use `serp_visibility` for a CTR-weighted score, `serp_share_of_voice` for competitor share, or `serp_ranking_distribution_trend` for rank-bucket counts.

serp_estimated_traffic

Export keywords to a downloadable CSV file. Returns a status URL the user opens in a browser; the page shows progress while the export runs in the background and starts the download automatically when the file is ready. Use this when the user explicitly asks to "download", "export", "give me a CSV", or wants the full set of keywords beyond what list_keywords paginates. For "how many?" or "show me the top N" questions, use `list_keywords` / `search_keywords` instead — those return rows directly and do not generate a downloadable file. Filters mirror `list_keywords` (rank range, tag, keyword_type, dates). Omit `project_id` for an account-wide export across all the user's projects. Set `dry_run: true` to preview `row_count` and `byte_size_estimate` without enqueueing a job — useful before committing to a heavy export. Hard cap is 100,000 rows; above that the tool returns a `narrow your filter` message rather than producing the file. Requires the `write:exports` scope. Tokens issued without it will see a `missing_scope` error before any data is touched.

export_keywords

Fetch a single AI Visibility domain by id. Use this to confirm a domain exists for the user before calling aiv_list_search_terms or aiv_metrics.

aiv_get_domain

Read the account-wide share-link branding and visibility settings. These apply to **every** project share link in the account by default; per-project overrides live on `get_project_sharing_settings`. Use this when the user asks "what are my account share settings", "what branding do my share links use", or before calling `update_account_sharing_settings` so you can confirm the diff with the user.

get_account_sharing_settings

Account ranking alerts — what crossed the user's anomaly thresholds recently. Returns a paginated alert list plus a per-project summary block. Filters: `project_id` (limit to one project), `view_type` (`positive` gains or `negative` losses), `keyword` (free-text substring), `page`/`per_page` (default 25, max 500). Use when the user asks "any alerts?", "what dropped this week", "any unusual movement in project X", or wants to triage recent anomalies. For movers without the threshold filter, use `serp_movers_window`; for anomaly detection without the alert envelope, use `serp_anomalies`. Read-only: viewing alerts here never clears the unread badge in the app. Acknowledging / marking alerts read stays a manual action in the Keyword.com UI.

get_alerts

Fetch a single keyword's current record — rank, MSV, CPC, recent change_*, lifecycle flags, GSC metrics. Scoped to the project that owns the keyword.

get_keyword

Fetch full details for a single project, including keyword count, archived keyword count, tags, branding metadata, and nested subprojects. Use this when the user names or has just identified one project ("show me Project X", "what's in this project?") — `list_projects` is the right tool for browsing many. Returns `status` (active|archived|deleted), domain, currency_code, company_* branding fields, and the full `subprojects[]` array. Resolve `project_id` via `list_projects` or `search_projects` first if the user named the project ambiguously. Requires the 'read:data' scope.

get_project

Read the per-project share-link settings: share URL, password-protection state, hide-overview toggle, and per-project branding override (if any). Use this to answer "what does my share link for project X look like" or before editing settings so you can confirm the diff with the user. `is_password_protected` indicates whether a password is set; the raw password is never returned by this tool. `override_account_branding` is computed from whether any per-project branding columns are non-null — when false, the project inherits the account-wide branding from `get_account_sharing_settings`.

get_project_sharing_settings

Resolve a free-text place name (a business, a city, a country) to concrete Google Place IDs (the `ChIJ…` strings Maps-type keywords need). Call this BEFORE `add_keywords` whenever the user wants to track a Maps keyword and describes the place by name rather than supplying a raw Place ID — Maps keywords rank by `gmb_place_id`, and the LLM cannot invent one. Returns up to ~5 suggestions per query. Pick the one the user meant and pass its `place_id` to `add_keywords` as `gmb_place_id`. If `meta.connected` is false the Places worker is not configured in this environment — fall back to asking the user to enter the Place ID directly.

places_autocomplete

Look up canonical details for a Google Place ID (`ChIJ…`) and confirm it resolves. Use sparingly — `places_autocomplete` already returns enough detail to pick the right Place ID, and `add_keywords` validates the ID server-side. Reach for this only when the user pastes a raw Place ID and you want to confirm what place it points to before tracking, or to surface its formatted address / coordinates. Returns `meta.resolved: false` (and HTTP 404) when the upstream cannot resolve the Place ID — treat that as a typed 'invalid place id' signal, not a transient error.

places_details

Top competing domains for ONE keyword over a recent window, with rank history. Use when the user asks who's competing on a specific keyword, what competitor domains appear in that keyword's SERP, or wants to compare specific competitor domains. For a project-wide competitor view, use `get_top_competitors` instead.

get_keyword_competitors

Fetch multi-timeframe rank-bucket movement for a single keyword — Top 3 / Top 10 / Top 20 / Top 100 current vs comparison position across daily / weekly / monthly / semester / yearly / life timeframes. Use when the user asks for movement metrics or a 'how is this keyword doing over time' snapshot for ONE keyword. Project-wide variant is `serp_project_performance`.

get_keyword_metrics

Show a single keyword's rank history over the last N days (defaults to 90). Returns one row per rank_date. Use this for multi-day trend / "how did this keyword move over time" questions; use `get_keyword` for the current snapshot only.

get_keyword_history

List the authenticated user's tracked AI Visibility (AIV) domains. AIV monitors how brands appear across LLM/AI engines (ChatGPT, Perplexity, Gemini, AI Overviews, etc.) — distinct from SERP rankings. Returns domain_id, domain. Use the domain_id with aiv_get_domain, aiv_list_search_terms, or aiv_metrics. Structured payload exposes `total_count` — the user's total tracked AIV domain count (filtered by `search` if provided), regardless of the page cap. Supports `output_format=csv`: RFC 4180 stream with header `domain_id,domain`.

aiv_list_domains

List the search terms (LLM prompts) the AI Visibility provider tracks for a given domain. Use this to discover which prompts feed into aiv_metrics / aiv_sentiment / aiv_citations for a domain. Provider-shaped payload: structured payload exposes `count` (terms returned) but the upstream does not return a confident total — render fragment is best-effort. Supports `output_format=csv`: RFC 4180 stream with header `search_term,topic,engine` (the same surface columns rendered in Markdown — the full provider payload remains in `structured.raw`).

aiv_list_search_terms

List keywords in a project for biggest movers, page-2 opportunities, device splits, URL slices, and historical "what changed since X" baselines. Default order is monthly search volume descending. Pass `rank_min=11&rank_max=20` for page-2 keywords, `keyword_type` for desktop/mobile/maps splits, `ranking_url_contains` for URL-folder slices, or `report_date` to list keyword state on a historical date. Use `sort_by=change_7d` with `sort_direction=desc` for biggest gainers this week (rank improved, positive change). Use `sort_by=change_7d` with `sort_direction=asc` for biggest losers this week (rank dropped, negative change). The -32768 "no previous data" sentinel is filtered out by the API. Structured payload exposes `total_count` and `total_pages`. For "how many?" questions, call with `limit: 1` and read `total_count`. For "show me all", call once then paginate via `page: 2`, `page: 3`, etc. when `total_pages > 1`.

list_keywords

List the authenticated user's projects with keyword counts, tags, and nested subprojects. Returns project_id, project_name, tags, keyword_count, and subprojects with the same fields. Use this to discover project_ids before calling project-scoped tools like search_tags, list_keywords, or serp_share_of_voice. Structured payload exposes `total_count` and `total_pages` — use `page` to paginate through accounts with more than `limit` projects. If `structured.total_pages > 1`, call again with `page=2`, `page=3`, etc. to retrieve all projects. Supports `output_format=csv`: parents and subprojects are flattened into one RFC 4180 stream with a `kind` (project|subproject) and `parent_project_id` discriminator.

list_projects

All search regions / languages / device types currently tracked across the user's account, with a count of keywords per `(region, language, type)` triple. Use when the user asks 'what regions am I tracking', 'what locales do I cover', or wants an inventory of search-engine surfaces in use. Account-wide; for a per-project version, this tool isn't the right surface — fall back to listing keywords filtered by the project.

list_tracked_regions

Move one or more tracked keywords to a different project. Pass `keyword_ids` (1..1000) and `target_project_id`. Use this when the user explicitly asks to "move", "reassign", or "transfer" keywords between projects. Tags on moved keywords are cloned by name into the destination project — same-name tags merge silently. Source tags are not deleted. Duplicates: if a keyword whose (kw, url, region, language, type, location, gmb) tuple already exists in the destination, that row is skipped and counted in `duplicate_count`. The rest still move. Foreign keyword ids are silently dropped. Up to 1000 ids per call. Requires the 'write:data' scope.

move_keywords

Project-level keyword bucket comparison (Top 3 / Top 10 / Top 20 / Top 100) with current vs baseline counts and percentage change. Use for snapshot 'how is my project performing right now vs N days ago?'. For daily time series of the same buckets, use `serp_ranking_distribution_trend`.

serp_project_performance

Best-performing URLs in a project as a current snapshot. Returns avg rank, total keywords, total search volume, and avg CPC per URL. Use `serp_top_pages` instead when the user wants a comparison vs a baseline date.

serp_ranking_urls

Detect unusual keyword rank movement across the lookback window (1-7 days). For each keyword, returns its biggest daily-change spike whose absolute value exceeds the project anomaly threshold (max(10, mean+2σ) of typical daily movement). Use for "did anything weird happen today?", "any unusual drops in the last week?", and "keywords with abnormal swings".

serp_anomalies

Daily ranking-bucket distribution (Top 3 / Top 10 / Top 20 / Top 100 etc.) for a project. Window defaults to last 30 days. Use for "how is the shape of my rankings changing over time?" questions. For a current snapshot vs a single baseline date, use `serp_project_performance` instead. Use `serp_visibility` for a single weighted score trend, `serp_estimated_traffic` for click-volume trend, or `serp_share_of_voice` for competitor share trend.

serp_ranking_distribution_trend

Trigger an on-demand SERP refresh for specific tracked keywords by id. Consumes refresh credits from the user's plan. Mobile keywords may be temporarily excluded by the backend — surfaced in the response as `excluded_mobile_keywords`. Up to 1000 keyword ids per call. Requires the `write:data` scope. For refreshing every keyword in a project, use `refresh_keywords_by_project`.

refresh_individual_keywords

Trigger an on-demand SERP refresh for ALL tracked keywords in one or more projects. Consumes refresh credits from the user's plan. Mobile keywords may be temporarily excluded — surfaced as `excluded_mobile_keywords`. Up to 50 project ids per call. Optionally exclude specific keyword ids from the refresh. Requires the `write:data` scope. For refreshing specific keywords by id, use `refresh_individual_keywords`.

refresh_keywords_by_project

Restore a previously archived project. Its archived keywords are moved back to active, resume scraping, and start counting against the keyword quota again. Only works for archived projects. Returns `project_not_archived` if the project is already active. Soft-deleted projects can only be recovered through customer support — `delete_project` is the destructive surface. Use this when the user explicitly asks to "restore", "unarchive", or "resume tracking" a project. Requires the 'write:data' scope.

restore_project

Show what percentage of project visibility or estimated traffic comes from the top-N keywords, plus the contributing keyword list. Use for "are we dependent on a small set?" and "what % of visibility comes from top 10 keywords?".

serp_concentration

Per-feature counts in a project (current featured, previous featured, total SERP-feature appearances). Useful for "how many of my keywords are picking up Featured Snippets / People Also Ask / Knowledge Panels?" intents. Use `comparison_date` for current-vs-baseline counts. Use `start_date` + `end_date` (max 90 days, mutually exclusive with `comparison_date`) for window questions like "did AI Overviews appear or disappear over the last 30 days?".

serp_features

Keyword counts and estimated traffic per search-intent bucket (commercial / informational / navigational / transactional) for a project.

serp_search_intents