Title & Meta Pixel Optimizer

Title & Meta Pixel Optimizer

AGENT ROLE: Autonomous metadata-optimization agent. Measure each page's title/meta against pixel and keyword rules, detect duplication, and emit the JSON in references/output.schema.json.

OBJECTIVE

Find titles and meta descriptions that truncate in the SERP, bury or omit the primary keyword, or duplicate other pages — and recommend length-safe rewrites, prioritized by search demand when GSC is connected.

INPUTS

• urls (REQUIRED string[]) OR sitemap_url.
• target_keywords (OPTIONAL): map url → primary_keyword.
• title_px_budget (OPTIONAL, default 580), meta_px_budget (OPTIONAL, default 920).
• gsc_site (OPTIONAL): a verified GSC property to prioritize by impressions.

AUTHENTICATION / RUNTIME

• Crawl: keyless HTTPS GET, UA seoskills-title-meta/1.0, honor robots.
• gsc_site prioritization: REQUIRE GOOGLE_APPLICATION_CREDENTIALS/OAuth (scope webmasters.readonly). IF absent THEN skip prioritization and note priority_basis="none".

EXPECTED TOOL CALLS

• Run scripts/title_meta.py --urls a,b,c [--gsc sc-domain:example.com].
• Per URL: GET; extract <title> and <meta name="description">. IF gsc_site set: one searchAnalytics call for page-level impressions.

PROCEDURE (deterministic, per page)

STEP 1 — EXTRACT title + meta description text. STEP 2 — PIXEL WIDTH: estimate rendered width using the per-character width table (proportional font approximation). Flag TITLE_TRUNCATED IF width > title_px_budget; META_TRUNCATED IF > meta_px_budget; TITLE_TOO_SHORT IF < 200px. STEP 3 — PRESENCE: TITLE_MISSING / META_MISSING when absent or empty. STEP 4 — KEYWORD (if provided): KEYWORD_NOT_IN_TITLE; KEYWORD_NOT_FRONT_LOADED IF present but after ~30 pixels of other text. STEP 5 — DUPLICATES: after crawling all pages, group identical (normalized) titles and metas → DUPLICATE_TITLE / DUPLICATE_META with the sibling URLs. STEP 6 — PRIORITIZE: priority = impressions (GSC) else page order; EMIT issues per page with a length-safe rewrite suggestion (trim/rephrase to fit the budget while keeping the keyword front-loaded).

RATE LIMITS & ERROR HANDLING

• Crawl: ≤ 5 concurrent, ≥ 150ms per host, timeout 12s. Per-URL failure → {url, status:"unreachable"}, continue.
• GSC 429 → backoff 2^attempt (max 4); on persistent failure disable prioritization (priority_basis="none"), keep the audit.

MISSING / INSUFFICIENT DATA

• Pixel width is an ESTIMATE (real rendering varies by font/locale) — always return both char_count and estimated_px, and label estimates as such.
• A missing meta description is a finding, not an error (Google may generate one) — severity warning, not critical.
• Never invent a rewrite that drops the primary keyword to fit the budget; if it cannot fit, flag IRREDUCIBLE and return the best trimmed option.

OUTPUT

One JSON object per references/output.schema.json. No prose.

FILES

• scripts/title_meta.py — extraction, pixel-width estimation, keyword + duplicate checks, GSC prioritization.
• references/output.schema.json — output contract.