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 scheduled report. The report stops sending and disappears from `list_scheduled_reports`. Destructive. Only call when the user explicitly asks to "delete" or "remove" a report. To stop a report without losing it, call `set_scheduled_report_status` with `status: paused` instead. Find `report_id` with `list_scheduled_reports` and confirm the report (name, recipients, projects) with the user first. Requires the 'write:data' scope.

delete_scheduled_report

Revoke one share link of a project. Anyone with the link loses access at once. Take the `link_id` from `list_share_links`. Destructive and not reversible for a tag-scoped link: a new link gets a new hash. Confirm with the user first. To stop sharing the whole project, prefer `update_project_sharing_settings` with `is_active: false`, which can restore the same link later. Any user who can edit the project may call this. Requires the 'write:data' scope.

delete_share_link

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 an export id and status; the export runs in the background on a dedicated queue and you poll its progress, then fetch the download endpoint (which streams the CSV back as an attachment) once it is complete. 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 queueing 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, the visibility toggles, the Overview and Keywords chart selections, the keyword-table columns, and the 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`. Visibility, charts and columns are the effective values: the project override if it has one, else the account default. `whitelabel.entitled` says whether the account has the White-label add-on, which a password needs. `shared_tabs` lists the tabs visitors really see. Read `notes`: it says when a chart list or a hide flag is not what visitors see. Tag-scoped share links are listed by `list_share_links`.

get_project_sharing_settings

Show the delivery history of one scheduled report: when each dispatch went out, to whom, for which projects, and whether it was sent, failed or is still pending, with the failure reason when there is one. Use this for "did the report for client X go out", "why did the report fail" and "when was the last report sent". Find `report_id` with `list_scheduled_reports`. The list covers the most recent dispatches, newest first.

get_scheduled_report_history

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

Invite people to the Keyword.com account by email. Each address gets an email with an accept link that works until the `expires_at` date. Confirm the exact list of emails, the role and the project access with the user before you call this. Do not guess addresses. Roles: `admin` manages the team, billing and white-label settings and always sees every project; `member` reads and writes projects, keywords and tags; `viewer` reads projects only. Project access: `restrictions_mode: restricted` limits the invitee to `project_ids` (at least one id is required); omit it, or pass `all`, for access to every project. Inviting an email that already has a pending invite sends that invite again with a new link; the old link stops working. An email that already owns a Keyword.com account cannot be invited. Owner or admin only: other roles get an access error. Requires the 'write:data' scope.

invite_team_members

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 the invites sent from the Keyword.com account, newest first: email, role, project access, status (pending / accepted / expired / revoked), sent and expiry dates, and how many times the invite was sent again. Pass `status` to show one status only, for example the pending invites. Owner or admin only: other roles get an access error.

list_invites

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

List the scheduled email reports of the account: id, name, format (PDF, CSV or TEXT), schedule, next run, status (active or paused), delivery health, last sent date, recipients and projects. Use this to answer "which reports go out", "when is the next report", "who gets the report for project X", and before `update_scheduled_report`, `set_scheduled_report_status`, `send_scheduled_report` or `delete_scheduled_report` to find the `report_id`. A `delivery_block` on a report means mail to one of its recipients bounced or was marked as spam; the report stops sending until the recipient is corrected with `update_scheduled_report`. Reports belong to the account, so a team member sees the owner's reports. For "how many reports" read `total_count`.

list_scheduled_reports

List the share links of one project: the whole-project link (no tag filter) and every tag-scoped link, which shows only the keywords with those tags. Each link has an `id` (for `delete_share_link`) and a `hash`. The public page is `/share/{hash}` on the Keyword.com app origin, the same host as `share_url` in `get_project_sharing_settings`. Use `search_tags` to turn tag ids into names.

list_share_links

List the team members of the Keyword.com account: email, role (admin / member / viewer), project access (all projects, or restricted to the listed project ids), sign-in provider, last activity and join date. The account owner is not a member row and is not in this list. Pending invites are a separate list: `list_invites`. Use this before `update_team_member` or `remove_team_member` to resolve a person to a `member_id`. Owner or admin only: other roles get an access error.

list_team_members

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