add_keywords
ChatGPTAdd one or more tracked keywords to an existing project. Returns the number of newly added keywords, the number of duplicates (already-tracked keywords are silently coalesced — not an error), and the canonical keyword IDs. Use this when the user explicitly asks to "add", "track", or "import" keywords. Do NOT call this from generic "tell me about" or "show me" requests — those are read-only. Confirm the project_id with list_projects first if the user said "my project" or named a project ambiguously. Adding to the wrong project is hard to reverse without manual cleanup. Up to 100 keywords per call. Each entry needs at minimum a keyword (search term) and a tracking_url (the URL the user wants ranked for that keyword). For type=maps entries, gmb_place_id must be a real Google Place ID — the server validates it against Google Places before persisting. Resolve unknown places via places_autocomplete first instead of guessing; an invalid id surfaces as a keywords.<i>.gmb validation error and nothing is created. Requires the write:data scope on the caller's API key / OAuth token. Tokens issued without it will see a missing_scope error before any data is touched.
add_keywords
ChatGPTAdd one or more tracked keywords to an existing project. Returns the number of newly added keywords, the number of duplicates (already-tracked keywords are silently coalesced — not an error), and the canonical keyword IDs. Use this when the user explicitly asks to "add", "track", or "import" keywords. Do NOT call this from generic "tell me about" or "show me" requests — those are read-only. Confirm the project_id with list_projects first if the user said "my project" or named a project ambiguously. Adding to the wrong project is hard to reverse without manual cleanup. Up to 100 keywords per call. Each entry needs at minimum a keyword (search term) and a tracking_url (the URL the user wants ranked for that keyword). For type=maps entries, gmb_place_id must be a real Google Place ID — the server validates it against Google Places before persisting. Resolve unknown places via places_autocomplete first instead of guessing; an invalid id surfaces as a keywords.<i>.gmb validation error and nothing is created. Requires the write:data scope on the caller's API key / OAuth token. Tokens issued without it will see a missing_scope error before any data is touched.
add_project
ChatGPTCreate a new keyword-tracking project, or return the existing one if a project with the same name already exists for the user. Use this when the user asks to "create a new project", "add a project", or "set up tracking for ...". Pass parent_project_id (resolved via list_projects) to create a sub-project — pass only the sub-project name in name, the server composes the parent/child relationship. Returns {project_id, name, created} where created: false means a project with that name already existed and was returned as-is (idempotent — safe to re-call). Requires the write:data scope.
add_project
ChatGPTCreate a new keyword-tracking project, or return the existing one if a project with the same name already exists for the user. Use this when the user asks to "create a new project", "add a project", or "set up tracking for ...". Pass parent_project_id (resolved via list_projects) to create a sub-project — pass only the sub-project name in name, the server composes the parent/child relationship. Returns {project_id, name, created} where created: false means a project with that name already existed and was returned as-is (idempotent — safe to re-call). Requires the write:data scope.
aiv_citations
ChatGPTAI Visibility citation analytics for a tracked domain (counts by citing domain / URL / engine / query, competitor citation comparison). Use for "who cites whom" / competitive citation questions; for the composite dashboard use aiv_metrics.
aiv_citations
ChatGPTAI Visibility citation analytics for a tracked domain (counts by citing domain / URL / engine / query, competitor citation comparison). Use for "who cites whom" / competitive citation questions; for the composite dashboard use aiv_metrics.
aiv_get_domain
ChatGPTFetch 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
ChatGPTFetch 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_list_domains
ChatGPTList 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
ChatGPTList 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_search_terms
ChatGPTList 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
ChatGPTList 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_metrics
ChatGPTComposite AI Visibility dashboard (visibility + sentiment + mentions + citations) for a tracked domain. Best for "give me an AI visibility overview" or open-ended brand-monitoring questions. Filter via timeframe (default 30d), engines, topics, search_terms.
aiv_metrics
ChatGPTComposite AI Visibility dashboard (visibility + sentiment + mentions + citations) for a tracked domain. Best for "give me an AI visibility overview" or open-ended brand-monitoring questions. Filter via timeframe (default 30d), engines, topics, search_terms.
aiv_sentiment
ChatGPTAI Visibility sentiment breakdown for a tracked domain (positive / neutral / negative aggregates and per-engine splits). Use when the user asks specifically about sentiment; for the composite dashboard use aiv_metrics.
aiv_sentiment
ChatGPTAI Visibility sentiment breakdown for a tracked domain (positive / neutral / negative aggregates and per-engine splits). Use when the user asks specifically about sentiment; for the composite dashboard use aiv_metrics.
archive_project
ChatGPTArchive a project. All its active keywords are flipped to the archived state, stop being scraped, and stop counting against the user's keyword quota. Use this when the user explicitly asks to "archive", "pause", or "stop tracking" a project. Do NOT call from generic cleanup/triage requests — confirm intent first. Reversible — call restore_project to bring the keywords back to active. Resolve project_id via list_projects if the user named the project ambiguously. Requires the 'write:data' scope.
archive_project
ChatGPTArchive a project. All its active keywords are flipped to the archived state, stop being scraped, and stop counting against the user's keyword quota. Use this when the user explicitly asks to "archive", "pause", or "stop tracking" a project. Do NOT call from generic cleanup/triage requests — confirm intent first. Reversible — call restore_project to bring the keywords back to active. Resolve project_id via list_projects if the user named the project ambiguously. Requires the 'write:data' scope.
attach_tag
ChatGPTAttach 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
ChatGPTAttach 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.
compare_with_competitor
ChatGPTCompare 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
ChatGPTCompare 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.
contact_us
ChatGPTForward 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
ChatGPTForward 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.
create_group
ChatGPTCreate 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
ChatGPTCreate 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_tag
ChatGPTCreate 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
ChatGPTCreate 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.
delete_keywords
ChatGPTSoft-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
ChatGPTSoft-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_project
ChatGPTDelete 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
ChatGPTDelete 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_tag
ChatGPTDelete 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
ChatGPTDelete 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.
detach_tag
ChatGPTRemove 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
ChatGPTRemove 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.
export_keywords
ChatGPTExport 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
ChatGPTExport 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.
get_account_info
ChatGPTThe authenticated user's active SERP and AIV plans (name, status, trial end date), current usage counters (SERP keywords used vs limit, daily additions used/remaining/limit, refresh credits used vs limit, AIV credits used vs limit), and the user's seat info: access_level (master / admin / view / addon), is_master_account, and either addon_seats (for master accounts — total seats invited plus per-access-level breakdown) or allowed_project_names (for non-master seats — the project names the seat may access; empty array = unrestricted). Either subscription side can be null when there's no active subscription of that type. Use when the user asks about plan, quota, role, seat type, who else is on the account, or 'how much have I used' — never guess limits or permissions.
get_account_info
ChatGPTThe authenticated user's active SERP and AIV plans (name, status, trial end date), current usage counters (SERP keywords used vs limit, daily additions used/remaining/limit, refresh credits used vs limit, AIV credits used vs limit), and the user's seat info: access_level (master / admin / view / addon), is_master_account, and either addon_seats (for master accounts — total seats invited plus per-access-level breakdown) or allowed_project_names (for non-master seats — the project names the seat may access; empty array = unrestricted). Either subscription side can be null when there's no active subscription of that type. Use when the user asks about plan, quota, role, seat type, who else is on the account, or 'how much have I used' — never guess limits or permissions.
get_account_sharing_settings
ChatGPTRead 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
ChatGPTRead 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_alerts
ChatGPTAccount 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
ChatGPTAccount 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_keyword
ChatGPTFetch 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
ChatGPTFetch 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_competitors
ChatGPTTop 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
ChatGPTTop 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_history
ChatGPTShow 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
ChatGPTShow 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_metrics
ChatGPTFetch 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
ChatGPTFetch 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_project
ChatGPTFetch 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
ChatGPTFetch 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_sharing_settings
ChatGPTRead 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
ChatGPTRead 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_serp
ChatGPTShow 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
ChatGPTShow 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_top_competitors
ChatGPTTop competitor domains for a project, ranked by appearances in the top positions across the project keywords over a recent window. By default the project's own domains (derived from each active keyword's tracking URL) are excluded. Pass exclude_self_domain=false to include them; the response always reports the detected self-domain set in meta.
get_top_competitors
ChatGPTTop competitor domains for a project, ranked by appearances in the top positions across the project keywords over a recent window. By default the project's own domains (derived from each active keyword's tracking URL) are excluded. Pass exclude_self_domain=false to include them; the response always reports the detected self-domain set in meta.
list_keywords
ChatGPTList 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
ChatGPTList 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_projects
ChatGPTList 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
ChatGPTList 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_tracked_regions
ChatGPTAll 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
ChatGPTAll 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.
move_keywords
ChatGPTMove 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
ChatGPTMove 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.
places_autocomplete
ChatGPTResolve 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
ChatGPTResolve 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_details
ChatGPTLook 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
ChatGPTLook 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.
refresh_individual_keywords
ChatGPTTrigger 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
ChatGPTTrigger 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_keywords_by_project
ChatGPTTrigger 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
ChatGPTTrigger 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.
restore_project
ChatGPTRestore 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
ChatGPTRestore 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.
search_keywords
ChatGPTSearch the authenticated user's keywords across all their active projects. Optionally filter by a case-insensitive keyword text substring; omit query to rely on filter/sort parameters alone. Returns keyword_id, keyword text, project_id, project_name, current rank, and msv. Default sort is msv descending; pass sort_by + sort_direction to change it (e.g. change_7d desc for biggest gainers across the whole account). Filter knobs are a superset of list_keywords: rank range (rank_min/rank_max), keyword_type, country, lang_short, location_contains, ranking_url_contains (where Google currently ranks), tracking_url_contains (the URL the customer asked us to track — distinct from ranking_url), and favorites (search-only — not available in list_keywords). Cross-project scoping: pass project_ids to bound the search to specific projects, project_name_contains to match by project name, or tag_names to match keywords carrying any of the given tags (tags are project-scoped — names are resolved to IDs across all your projects and OR-matched). Use this when the user mentions a keyword by text and you need its keyword_id + project_id for follow-up calls (get_keyword, get_keyword_history), or to answer account-wide questions like "all my page-2 keywords" or "what dropped this week across every project" (no text filter needed for those). Structured payload exposes total_count and total_pages. For "how many?" call with limit: 1 and read total_count. For "show me all", paginate via page: 2, page: 3, etc. when total_pages > 1.
search_keywords
ChatGPTSearch the authenticated user's keywords across all their active projects. Optionally filter by a case-insensitive keyword text substring; omit query to rely on filter/sort parameters alone. Returns keyword_id, keyword text, project_id, project_name, current rank, and msv. Default sort is msv descending; pass sort_by + sort_direction to change it (e.g. change_7d desc for biggest gainers across the whole account). Filter knobs are a superset of list_keywords: rank range (rank_min/rank_max), keyword_type, country, lang_short, location_contains, ranking_url_contains (where Google currently ranks), tracking_url_contains (the URL the customer asked us to track — distinct from ranking_url), and favorites (search-only — not available in list_keywords). Cross-project scoping: pass project_ids to bound the search to specific projects, project_name_contains to match by project name, or tag_names to match keywords carrying any of the given tags (tags are project-scoped — names are resolved to IDs across all your projects and OR-matched). Use this when the user mentions a keyword by text and you need its keyword_id + project_id for follow-up calls (get_keyword, get_keyword_history), or to answer account-wide questions like "all my page-2 keywords" or "what dropped this week across every project" (no text filter needed for those). Structured payload exposes total_count and total_pages. For "how many?" call with limit: 1 and read total_count. For "show me all", paginate via page: 2, page: 3, etc. when total_pages > 1.
search_projects
ChatGPTSearch the authenticated user's projects by case-insensitive substring match. Returns project_id, project_name, tags, and nested subprojects. Use this when the user mentions a project by name and you need its project_id for follow-up queries. Structured payload exposes total_count and total_pages. For "how many?" call with limit: 1 and read total_count. For "show me all", paginate via page: 2, page: 3, etc. when total_pages > 1.
search_projects
ChatGPTSearch the authenticated user's projects by case-insensitive substring match. Returns project_id, project_name, tags, and nested subprojects. Use this when the user mentions a project by name and you need its project_id for follow-up queries. Structured payload exposes total_count and total_pages. For "how many?" call with limit: 1 and read total_count. For "show me all", paginate via page: 2, page: 3, etc. when total_pages > 1.
search_tags
ChatGPTSearch tags by case-insensitive substring match within a single project. Returns tag_id and tag_name. Use this when a user references a tag by name and you need its tag_id for a follow-up keyword query. Requires a project_id; you can discover one via list_projects or search_projects. Structured payload exposes total_count and total_pages. For "how many?" call with limit: 1 and read total_count. For "show me all", paginate via page: 2, page: 3, etc. when total_pages > 1.
search_tags
ChatGPTSearch tags by case-insensitive substring match within a single project. Returns tag_id and tag_name. Use this when a user references a tag by name and you need its tag_id for a follow-up keyword query. Requires a project_id; you can discover one via list_projects or search_projects. Structured payload exposes total_count and total_pages. For "how many?" call with limit: 1 and read total_count. For "show me all", paginate via page: 2, page: 3, etc. when total_pages > 1.
serp_account_performance
ChatGPTPaginated per-project performance rollup (current vs baseline rank-bucket counts) for the authenticated user. Use for cross-project 'how is each of my projects doing?' answers. Sort data[] by change ascending for 'which projects are most at risk this week'; descending for 'best performing projects'. Pass with_charts=true to include a 30-day top-positions sparkline series per project.
serp_account_performance
ChatGPTPaginated per-project performance rollup (current vs baseline rank-bucket counts) for the authenticated user. Use for cross-project 'how is each of my projects doing?' answers. Sort data[] by change ascending for 'which projects are most at risk this week'; descending for 'best performing projects'. Pass with_charts=true to include a 30-day top-positions sparkline series per project.
serp_account_summary
ChatGPTCross-project keyword totals for the authenticated user — total keywords tracked, keywords up, and bucket distribution (Top 3 / Top 10 / etc.) with comparison to a baseline date. When comparison_date is omitted the baseline is all-time (each keyword vs its first scrape); the response renders that explicitly so callers do not need to guess.
serp_account_summary
ChatGPTCross-project keyword totals for the authenticated user — total keywords tracked, keywords up, and bucket distribution (Top 3 / Top 10 / etc.) with comparison to a baseline date. When comparison_date is omitted the baseline is all-time (each keyword vs its first scrape); the response renders that explicitly so callers do not need to guess.
serp_account_top_positions
ChatGPTBucket counts (current / previous / start-of-period) for every active project the authenticated user owns. Use for cross-project comparison of keyword bucket movements.
serp_account_top_positions
ChatGPTBucket counts (current / previous / start-of-period) for every active project the authenticated user owns. Use for cross-project comparison of keyword bucket movements.
serp_anomalies
ChatGPTDetect 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
ChatGPTDetect 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_concentration
ChatGPTShow 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
ChatGPTShow 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_emerging_pages
ChatGPTFind 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
ChatGPTFind 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_estimated_traffic
ChatGPTDaily 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
ChatGPTDaily 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_features
ChatGPTPer-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
ChatGPTPer-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_movers_window
ChatGPTFind keywords that crossed into/out of a top-N threshold, showed consistent up/down trends, recovered, or stayed stagnant over a 7-90 day window. Use for "newly entered top 10", "fell out of top 100", "consistent gains", "steady drops", "recovered recently", and "stagnant 60d". For simple biggest gainers/losers, prefer list_keywords sorted by change_7d/change_30d.
serp_movers_window
ChatGPTFind keywords that crossed into/out of a top-N threshold, showed consistent up/down trends, recovered, or stayed stagnant over a 7-90 day window. Use for "newly entered top 10", "fell out of top 100", "consistent gains", "steady drops", "recovered recently", and "stagnant 60d". For simple biggest gainers/losers, prefer list_keywords sorted by change_7d/change_30d.
serp_project_performance
ChatGPTProject-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
ChatGPTProject-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_ranking_distribution_trend
ChatGPTDaily 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
ChatGPTDaily 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_urls
ChatGPTBest-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
ChatGPTBest-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_search_intents
ChatGPTKeyword counts and estimated traffic per search-intent bucket (commercial / informational / navigational / transactional) for a project.
serp_search_intents
ChatGPTKeyword counts and estimated traffic per search-intent bucket (commercial / informational / navigational / transactional) for a project.
serp_share_of_voice
ChatGPTDaily share of voice (estimated click share) for the top-10 competitor domains in a project. Window defaults to the last 30 days. Filter by tag_id to scope to a tag. Use for "how do I stack up against competitors over time?" questions; use serp_visibility for the account-only score, serp_estimated_traffic for absolute clicks, or serp_ranking_distribution_trend for rank-bucket composition.
serp_share_of_voice
ChatGPTDaily share of voice (estimated click share) for the top-10 competitor domains in a project. Window defaults to the last 30 days. Filter by tag_id to scope to a tag. Use for "how do I stack up against competitors over time?" questions; use serp_visibility for the account-only score, serp_estimated_traffic for absolute clicks, or serp_ranking_distribution_trend for rank-bucket composition.
serp_top_pages
ChatGPTTop URLs in a project with current vs comparison-date deltas (avg rank, estimated traffic, visibility). Use when the user asks for best-performing pages with a baseline period; use serp_ranking_urls for a snapshot only.
serp_top_pages
ChatGPTTop URLs in a project with current vs comparison-date deltas (avg rank, estimated traffic, visibility). Use when the user asks for best-performing pages with a baseline period; use serp_ranking_urls for a snapshot only.
serp_visibility
ChatGPTDaily visibility-score time series for a project (window defaults to last 30 days). Filter by tag_id to scope to a tag. Use for "is my SEO momentum up or down?" trend questions; use serp_estimated_traffic for click-volume trend, serp_share_of_voice for competitor share trend, or serp_ranking_distribution_trend for rank-bucket composition trend.
serp_visibility
ChatGPTDaily visibility-score time series for a project (window defaults to last 30 days). Filter by tag_id to scope to a tag. Use for "is my SEO momentum up or down?" trend questions; use serp_estimated_traffic for click-volume trend, serp_share_of_voice for competitor share trend, or serp_ranking_distribution_trend for rank-bucket composition trend.
serp_visibility_drivers
ChatGPTExplain what drove visibility or estimated-traffic change since a baseline date, grouped by keyword or page and sorted by absolute delta. Use for "why did visibility drop?", "what changed since date?", and "pages that lost visibility this week".
serp_visibility_drivers
ChatGPTExplain what drove visibility or estimated-traffic change since a baseline date, grouped by keyword or page and sorted by absolute delta. Use for "why did visibility drop?", "what changed since date?", and "pages that lost visibility this week".
submit_feedback
ChatGPTSubmit a piece of feedback when the assistant could not answer the user's question, returned data that did not match what they asked for, or the user volunteered feedback on their own. This is a telemetry write — it does not modify any of the user's tracked keywords, projects, or other business data. Call this tool when (a) you cannot find a tool that fits the user's question after considering the catalog, (b) a tool returned data that does not match what the user asked for in a way you can articulate, or (c) the user proactively shares feedback (a suggestion, complaint, or compliment about a tool, the assistant, or the product). After a long, successful session it is also fine to invite the user once — at most — to share quick feedback; do not nag, and do not invoke this tool unless the user actually replies with feedback. Do NOT call it for routine refusals, validation errors, empty result sets, or rate-limit responses. Call once per distinct user intent. Capped at 20 submissions per account per 24 hours. If the cap is hit, this tool returns feedback_rate_limited; the LLM should NOT retry, just acknowledge the cap to the user. On success, surface the returned acknowledgment text verbatim to the user — including the reference id.
submit_feedback
ChatGPTSubmit a piece of feedback when the assistant could not answer the user's question, returned data that did not match what they asked for, or the user volunteered feedback on their own. This is a telemetry write — it does not modify any of the user's tracked keywords, projects, or other business data. Call this tool when (a) you cannot find a tool that fits the user's question after considering the catalog, (b) a tool returned data that does not match what the user asked for in a way you can articulate, or (c) the user proactively shares feedback (a suggestion, complaint, or compliment about a tool, the assistant, or the product). After a long, successful session it is also fine to invite the user once — at most — to share quick feedback; do not nag, and do not invoke this tool unless the user actually replies with feedback. Do NOT call it for routine refusals, validation errors, empty result sets, or rate-limit responses. Call once per distinct user intent. Capped at 20 submissions per account per 24 hours. If the cap is hit, this tool returns feedback_rate_limited; the LLM should NOT retry, just acknowledge the cap to the user. On success, surface the returned acknowledgment text verbatim to the user — including the reference id.
suggest_competitor_keywords
ChatGPTDiscover keyword ideas based on what a competitor domain ranks for. Each idea includes monthly search volume (msv), cost-per-click (cpc), and competition score. Use this when the user asks "what keywords does competitor.com rank for", "show me competitor.com's keywords", or "what should I track to compete with competitor.com". Pass a registrable domain (e.g. "ahrefs.com", not "https://ahrefs.com/blog"). The upstream provider rejects URLs that aren't valid domains with validation_failed. Returns up to 100 ideas by default (sorted by descending MSV) — the upstream pool is up to ~700; raise limit to widen. On slow upstreams the tool may return pending with a job_id — re-call with the same arguments to retry.
suggest_competitor_keywords
ChatGPTDiscover keyword ideas based on what a competitor domain ranks for. Each idea includes monthly search volume (msv), cost-per-click (cpc), and competition score. Use this when the user asks "what keywords does competitor.com rank for", "show me competitor.com's keywords", or "what should I track to compete with competitor.com". Pass a registrable domain (e.g. "ahrefs.com", not "https://ahrefs.com/blog"). The upstream provider rejects URLs that aren't valid domains with validation_failed. Returns up to 100 ideas by default (sorted by descending MSV) — the upstream pool is up to ~700; raise limit to widen. On slow upstreams the tool may return pending with a job_id — re-call with the same arguments to retry.
suggest_missing_keywords
ChatGPTDiscover keywords the project's domain already gets impressions for in Google Search Console but isn't tracking yet — high-value, often-overlooked candidates the LLM would never invent. Use this when the user asks "what keywords am I missing", "what should I add to this project", "find untapped keywords from GSC", or wants to expand tracking with terms they're already ranking for. Requires the user to have connected Google Search Console and linked the project to a GSC site. When either is missing the tool returns a friendly CTA pointing to the integrations page — it does NOT error out. Returns up to 100 ideas by default (sorted as the upstream returns them). Raise limit (max 100) only when the user explicitly needs more.
suggest_missing_keywords
ChatGPTDiscover keywords the project's domain already gets impressions for in Google Search Console but isn't tracking yet — high-value, often-overlooked candidates the LLM would never invent. Use this when the user asks "what keywords am I missing", "what should I add to this project", "find untapped keywords from GSC", or wants to expand tracking with terms they're already ranking for. Requires the user to have connected Google Search Console and linked the project to a GSC site. When either is missing the tool returns a friendly CTA pointing to the integrations page — it does NOT error out. Returns up to 100 ideas by default (sorted as the upstream returns them). Raise limit (max 100) only when the user explicitly needs more.
suggest_related_keywords
ChatGPTDiscover keyword ideas semantically related to a seed keyword (e.g. "rank tracker" → "seo software", "keyword tracking tool", ...). Each idea includes monthly search volume (msv), cost-per-click (cpc), and competition score so the LLM can rank suggestions by opportunity. Use this when the user asks to "find more keywords like X", "expand my keyword list", "what should I track next", or wants seed-driven keyword research. Do NOT invent keywords yourself. Always call this tool when the user asks for keyword ideas — the upstream provider knows actual search volumes; the LLM does not. Returns up to 100 ideas by default (sorted by descending MSV) — the upstream pool is up to ~700; raise limit to widen. On slow upstreams the tool may return pending with a job_id — re-call with the same arguments to retry.
suggest_related_keywords
ChatGPTDiscover keyword ideas semantically related to a seed keyword (e.g. "rank tracker" → "seo software", "keyword tracking tool", ...). Each idea includes monthly search volume (msv), cost-per-click (cpc), and competition score so the LLM can rank suggestions by opportunity. Use this when the user asks to "find more keywords like X", "expand my keyword list", "what should I track next", or wants seed-driven keyword research. Do NOT invent keywords yourself. Always call this tool when the user asks for keyword ideas — the upstream provider knows actual search volumes; the LLM does not. Returns up to 100 ideas by default (sorted by descending MSV) — the upstream pool is up to ~700; raise limit to widen. On slow upstreams the tool may return pending with a job_id — re-call with the same arguments to retry.
update_account_sharing_settings
ChatGPTUpdate the account-wide share-link branding and visibility settings. Account-level changes affect every project share link in the account that does not have its own per-project branding override. Confirm with the user before calling this if they meant a single project — the per-project surface is update_project_sharing_settings. Every key is optional. Omitted keys leave the underlying value unchanged. Passing null on a nullable string clears the value. Field guide: - branding.company_name, branding.company_url, branding.company_logo_url, branding.company_description: account-wide branding shown on share pages. Pass null to clear. - visibility.hide_overview: hide the "Overview & Top Pages" tab on share pages. - visibility.hide_verified: hide the "Verified by Keyword.com" badge. - visibility.hide_share_options: hide the share/copy-link controls on share pages. - domain.use_whitelabel: serve share links from the Whitelabel domain (seranktracker.com) instead of the default. Toggling this flag alone does not provision a custom subdomain — that is handled out of band. - domain.display_company_info: show the Company Information block (name + description) on share pages. Requires the write:data scope on the caller's API key / OAuth token. Tokens issued without it will see a missing_scope error before any data is touched.
update_account_sharing_settings
ChatGPTUpdate the account-wide share-link branding and visibility settings. Account-level changes affect every project share link in the account that does not have its own per-project branding override. Confirm with the user before calling this if they meant a single project — the per-project surface is update_project_sharing_settings. Every key is optional. Omitted keys leave the underlying value unchanged. Passing null on a nullable string clears the value. Field guide: - branding.company_name, branding.company_url, branding.company_logo_url, branding.company_description: account-wide branding shown on share pages. Pass null to clear. - visibility.hide_overview: hide the "Overview & Top Pages" tab on share pages. - visibility.hide_verified: hide the "Verified by Keyword.com" badge. - visibility.hide_share_options: hide the share/copy-link controls on share pages. - domain.use_whitelabel: serve share links from the Whitelabel domain (seranktracker.com) instead of the default. Toggling this flag alone does not provision a custom subdomain — that is handled out of band. - domain.display_company_info: show the Company Information block (name + description) on share pages. Requires the write:data scope on the caller's API key / OAuth token. Tokens issued without it will see a missing_scope error before any data is touched.
update_alert_settings
ChatGPTUpdate the user's account-wide alert preferences — recipient emails, email frequency, minimum rank-change threshold, and whether OTR (out-of-top-range) movements should be excluded. Use this when the user explicitly asks to "change my alert threshold", "set alert emails", "lower the alert sensitivity", etc. All four fields are optional but at least one must be supplied. Alert settings are account-level only — per-project thresholds are not exposed. Requires the 'write:data' scope.
update_alert_settings
ChatGPTUpdate the user's account-wide alert preferences — recipient emails, email frequency, minimum rank-change threshold, and whether OTR (out-of-top-range) movements should be excluded. Use this when the user explicitly asks to "change my alert threshold", "set alert emails", "lower the alert sensitivity", etc. All four fields are optional but at least one must be supplied. Alert settings are account-level only — per-project thresholds are not exposed. Requires the 'write:data' scope.
update_keywords
ChatGPTBulk-update tracked keywords. Applies a single attribute set across the selected keyword ids — pass keyword_ids and an updates object holding the fields to change. Use this when the user explicitly asks to "update", "change", "fix", or "set" a field on one or more keywords (URL, region, language, tracking type, favored, share-of-voice, tags, etc.). Duplicates: if a change would collide with an existing keyword in the same project (same kw + url + region + language + type + location/gmb), that row is skipped and counted in duplicate_count. The rest still apply. Tags: pass updates.tags.attach (array of names — missing tags are created on the fly) and/or updates.tags.detach (array of existing tag ids). Tag operations require all keyword_ids to belong to a single project; mixed-project payloads come back validation_failed. Foreign keyword ids are silently dropped. Up to 1000 ids per call. Requires the 'write:data' scope.
update_keywords
ChatGPTBulk-update tracked keywords. Applies a single attribute set across the selected keyword ids — pass keyword_ids and an updates object holding the fields to change. Use this when the user explicitly asks to "update", "change", "fix", or "set" a field on one or more keywords (URL, region, language, tracking type, favored, share-of-voice, tags, etc.). Duplicates: if a change would collide with an existing keyword in the same project (same kw + url + region + language + type + location/gmb), that row is skipped and counted in duplicate_count. The rest still apply. Tags: pass updates.tags.attach (array of names — missing tags are created on the fly) and/or updates.tags.detach (array of existing tag ids). Tag operations require all keyword_ids to belong to a single project; mixed-project payloads come back validation_failed. Foreign keyword ids are silently dropped. Up to 1000 ids per call. Requires the 'write:data' scope.
update_project_sharing_settings
ChatGPTUpdate the per-project share-link settings. All keys are optional; omitted keys leave the underlying value unchanged. Field guide: - is_active: master toggle for the share link. false disables the share without rotating the URL. - password: three-state — omit leaves unchanged, null clears (publicly accessible), non-empty string sets. The raw password never appears in any response. - visibility.hide_overview: hide the Overview & Top Pages tab on this project's share page (overrides the account-wide setting). - branding.override_account_branding: behavior flag, not stored state. false nulls all per-project branding columns and reverts the project to account-wide branding — any branding.company_* keys in the same request are discarded. true (or absent) accepts per-project branding values normally; the computed flag flips to true whenever any column is non-null. - branding.company_name, branding.company_link, branding.company_logo, branding.company_description: per-project branding values. Pass null on individual keys to clear them. Requires the write:data scope on the caller's API key / OAuth token. Tokens issued without it will see a missing_scope error before any data is touched.
update_project_sharing_settings
ChatGPTUpdate the per-project share-link settings. All keys are optional; omitted keys leave the underlying value unchanged. Field guide: - is_active: master toggle for the share link. false disables the share without rotating the URL. - password: three-state — omit leaves unchanged, null clears (publicly accessible), non-empty string sets. The raw password never appears in any response. - visibility.hide_overview: hide the Overview & Top Pages tab on this project's share page (overrides the account-wide setting). - branding.override_account_branding: behavior flag, not stored state. false nulls all per-project branding columns and reverts the project to account-wide branding — any branding.company_* keys in the same request are discarded. true (or absent) accepts per-project branding values normally; the computed flag flips to true whenever any column is non-null. - branding.company_name, branding.company_link, branding.company_logo, branding.company_description: per-project branding values. Pass null on individual keys to clear them. Requires the write:data scope on the caller's API key / OAuth token. Tokens issued without it will see a missing_scope error before any data is touched.
