> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SEO Delivery Tools
> The agent's SEO delivery surface: the live rank tracker with local pack and AI-engine tracking, page intelligence (Core Web Vitals, entity, citations, CRO), the weekly analysis suite, full Search Console scope, and the Tag Manager publish flow
These are the tools the AI agent uses to deliver recurring SEO work — tracking real rankings, auditing pages, mining Search Console, and shipping tracking tags. They pair with the [Standing Playbooks](/marketing/standing-playbooks) that run them on a schedule and the [client report](/marketing/client-reporting) that presents the results.
## Live rank tracker
`seo_track_keyword` starts tracking a keyword's position for a target domain. It creates the tracked row the daily ranking worker checks **and queues the first check immediately** — rank data arrives within minutes, not tomorrow.
* Required: `keyword` and `target_domain`.
* `search_engine`: `google` (default), `bing`, or the AI engines — `ai_overview`, `chatgpt`, `perplexity`, `claude`, `gemini` — which track citation mentions rather than blue-link positions.
* `ranking_type: "local"` with `business_name` tracks the **local pack** position; set `location_name` to the city that matters (for example "Dallas, TX").
* Optional: `target_url` (the page you expect to rank), `device_type` (desktop default), `tracking_frequency` (daily default, or weekly), `target_rank` (a goal like top 3), `tags`, and `location_code` / `language_code`.
* Keywords tracking the same domain group together automatically; pass `goal_id` only to subdivide tracking within a domain.
`seo_tracked_keywords_list` shows what's being tracked and `seo_tracked_keyword_delete` stops a keyword.
**Reading results — `seo_rankings_list`** has two views:
| View | Returns |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `view: "keywords"` (default) | Every tracked keyword with `current_rank` / `previous_rank` / `best_rank` / `worst_rank`, `local_pack_position`, device, location, check frequency, and last-checked time. Filter by `domain`, `keyword` (contains), `search_engine`, `ranking_type`, `device`, and `min_position` / `max_position` |
| `view: "history"` | The per-check time series for one keyword — check date, rank position, local pack position, search volume, and SERP features. Pass `ranking_id` (from the keywords view) or `keyword` + `domain`, with `from_date` / `to_date` |
## Page intelligence
| Tool | What it does |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seo_core_web_vitals` | Field and lab in one call: Chrome UX Report real-user p75 LCP/INP/CLS (the numbers Google actually ranks on) plus a Lighthouse run with scores and the top improvement opportunities. Works on any URL, including competitors. If field data 404s for a thin-traffic URL, retry with `origin` for site-level data; `include: "field"` skips the slow Lighthouse run |
| `seo_entity_check` | Does this brand, person, or topic resolve to a Google Knowledge Graph entity? Returns the entity id, canonical name, types, and a strength score to compare against competitors. A brand with no entity is a string, not a citable source — that absence is itself an audit finding |
| `seo_cro_audit` | A heuristic conversion audit of one landing page, scored 0-100 across five sections: speed, clarity, friction, trust, and call-to-action. Every finding names the issue, why it costs conversions, and the fix, plus a quick-wins shortlist. Audit only — nothing is persisted and it works on any public URL |
| `seo_citations_audit` | A citation audit for a Google Business Profile connection: diffs every public listing attributable to the business against the canonical name/address/phone/website, checks a fixed major-directory list, and reports found / consistent / inconsistent / missing. Spends one search-credit per run with a 24-hour cooldown. Audit only — it never writes to any directory |
| `seo_citations_get` | Reads the stored citation snapshot for free — no credit spend. Omit the connection id to get a row per connected profile |
## The analysis suite (and where its data comes from)
Five analysis reads are computed by a weekly analysis pass (Sundays), not on demand. Each is empty — with a note saying so — until its data source is connected and the first weekly run completes. The honest data-source notes matter:
| Tool | What it finds | Data source |
| ------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seo_content_decay` | Pages with declining organic traffic — refresh candidates | The archived Search Console query/page history: the last 28 archived days vs the prior 28. Needs Search Console connected |
| `seo_cannibalization` | Queries where two or more of your pages compete | Same Search Console archive — queries where multiple pages each drew meaningful impressions |
| `seo_internal_links` | The internal-link graph per page: orphans, inbound/outbound counts, click depth | A static scan of the published project's code — Hiveku-hosted published projects only. Dynamic or CMS-driven links are invisible, and external sites are never analyzed. Never read empty as "no issues" |
| `seo_eeat_scores` | E-E-A-T scores for the account's top Search Console pages (up to 10, re-scored monthly) | Pages fetched live and AI-scored, with a static-signal fallback — check each score's `method` field for scoring depth. Competitor scores are not computed |
| `seo_ranking_predictions` | 30-day ranking forecasts per tracked keyword | Linear trend extrapolation over rank-check history — not machine learning. Needs 5+ checks spanning 21+ days; the confidence score is the trend fit |
## Search Console: the full scope
The `seo_gsc_*` family covers everything Google's Search Console API exposes:
* **Discovery**: `seo_gsc_list_sites` (verified properties).
* **Reports**: `seo_gsc_search_queries` and `seo_gsc_top_pages` for the quick reads; `seo_gsc_search_analytics` is the canonical query — any combination of `date` / `query` / `page` / `country` / `device` / `searchAppearance` dimensions with filters (equals, contains, regex), up to 25,000 rows per call; `seo_gsc_time_series` for daily trends ("did my change help?" — overlay the deploy date); `seo_gsc_period_comparison` joins two periods and returns winners, losers, and rank climbers/droppers.
* **Indexing**: `seo_gsc_inspect_url` runs URL Inspection (indexability, mobile usability, rich results — note Google's public API only inspects the indexed snapshot; there is no live-test equivalent). `seo_gsc_index_coverage` is the best-available substitute for the Index Coverage report — Google exposes no bulk endpoint, so it fans out URL Inspection over a list you supply (up to 50 URLs per call) and buckets the results by coverage state.
* **Sitemaps**: `seo_gsc_list_sitemaps` and `seo_gsc_get_sitemap` (per-sitemap errors and warnings — the read to run when submitted exceeds indexed), `seo_gsc_submit_sitemap` (idempotent; run after a deploy that added indexable URLs), and `seo_gsc_delete_sitemap` (for structure migrations).
**Sitemap writes need the write scope.** Search Console connections authorized before late August 2026 were granted read-only access, which cannot submit or delete sitemaps. If `seo_gsc_submit_sitemap` or `seo_gsc_delete_sitemap` fails with a permissions error, reconnect the Search Console connection — the reconnect grants the updated write scope. Reads are unaffected.
## Google Tag Manager: tag, version, publish
GTM rides the same Google authorization as your Google Analytics connection — one connection covers both. The flow exists to close a specific failure mode: a container whose conversion tags were created but never published records nothing, however complete it looks in GTM.
Without `container_path`, it lists the GTM accounts and containers the connection can see. With one, it returns the publish preview: the default workspace's pending changes, the draft-vs-live tag split (draft-only tags are not serving), the currently live version, and a loud warning when the container has never been published.
Creates a workspace draft only — nothing serves yet, so there's no confirm gate. `tag_type` is `ga4_event` (needs `measurement_id` + `event_name`) or `ads_conversion` (needs `conversion_id` + `conversion_label` from the Ads conversion action's tag setup). Fire it from existing triggers (`firing_trigger_ids`) or create one: `create_trigger: "all_pages"`, or `"page_path"` with `trigger_page_path` — the page-path trigger defaults to both a pageview and a history-change trigger, because on a modern site either one alone has a silent blind spot.
Snapshots the workspace into a container version. Still not live. Creating a version consumes the workspace (GTM opens a fresh one), and the call fails loudly on GTM sync problems instead of returning a version that doesn't exist.
The step that changes the client's live site: every tag in the version starts serving to real visitors immediately. It's confirm-gated — the first call returns a preview (the version's tags, what's currently live, and any workspace changes that are *not* in this version) with `requires_confirm: true`; repeat the identical call with `confirm: true` to publish.
Version creation and publishing require the Tag Manager publish scopes, requested on new connections since late August 2026. A Google Analytics connection authorized before then returns a reconnect error naming the fix — reconnect Google Analytics and retry.
## Related pages
* [PPC Depth Tools](/marketing/ppc-depth-tools) — the conversion actions whose tags this flow installs
* [Client Reporting & Approvals](/marketing/client-reporting) — rankings and search-term wins land in the client report; audit findings become implementable tasks
* [Standing Playbooks](/marketing/standing-playbooks) — the weekly Core Web Vitals watch, rank-drop response, and content-decay refresh loops
* [Track Your Rankings](/how-tos/track-rankings) and [Run an SEO Audit](/how-tos/seo-audit) — the dashboard-side how-tos