iGods GEO Visibility Tool (GVT)

Run a GEO visibility test on a URL. Analyzes 7 categories: JavaScript dependencies (js), no-JS rendering (nojs), semantic HTML5, heading structure, schema.org markup, social tags, and accessibility. This is an async operation — it returns a tid immediately. Pass that tid to gvt_get_test_results to retrieve scores and issues once the test completes (poll until status is not "pending" or "running").

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to analyze"
    },
    "waitForJs": {
      "type": "boolean",
      "description": "Wait for JavaScript rendering before analysis. Set to false to skip JS rendering (faster, but may miss dynamically injected content).",
      "default": true
    }
  },
  "required": [
    "url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "8-character test ID to poll with"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending"
      ],
      "description": "Always pending at queue time"
    },
    "message": {
      "type": "string",
      "description": "Human-readable acknowledgement with polling guidance"
    },
    "next": {
      "type": "object",
      "description": "The suggested next call",
      "properties": {
        "tool": {
          "type": "string",
          "enum": [
            "gvt_get_test_results"
          ],
          "description": "The tool to call next"
        },
        "arguments": {
          "type": "object",
          "properties": {
            "tid": {
              "type": "string",
              "description": "The tid to poll with"
            }
          },
          "description": "Arguments for the next call"
        }
      }
    }
  },
  "description": "Async acknowledgement. Poll gvt_get_test_results with the returned tid until status is not pending or running."
}

Get results for a visibility test by tid: overall scores, findingSentence, shareableTid, and per-category resultData. The tid is an opaque 8-character HashID — copy it verbatim from gvt_run_visibility_test, gvt_list_tests, or gvt_get_batch_status; partial or reformatted values will not match, and results are scoped to the caller's own tests. If status is "pending" or "running", wait and retry. findingSentence is a pre-generated natural-language verdict; use it as the primary summary. shareableTid is non-null when the result is public and linkable. detail selects the payload shape: "summary" (recommended for reporting workflows) returns analysisSummary plus the top issues per category without the semantic tree, per-element markup, or the nojs_rendered duplicate pass; "full" (the default) returns complete per-category resultData for all 7 analysis types (heading, semantic, accessibility, schema, javascript, nojs, social). For compact per-page scores across a whole completed batch, prefer gvt_get_batch_summary instead of one call per tid.

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "Opaque 8-character hash ID returned by gvt_run_visibility_test or gvt_list_tests. Not an integer."
    },
    "detail": {
      "type": "string",
      "enum": [
        "summary",
        "full"
      ],
      "default": "full",
      "description": "Payload shape. summary: analysisSummary plus the top issues per category (deduplicated by type, capped at 10, sorted by severity then weight) — no semantic tree, per-element markup, or nojs_rendered pass. full: complete resultData for all analysis types (previous behavior, the default)."
    }
  },
  "required": [
    "tid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "The test ID that was polled"
    },
    "detail": {
      "type": "string",
      "enum": [
        "summary"
      ],
      "description": "Present with value \"summary\" when detail=summary was requested; omitted from full responses so existing callers see no change"
    },
    "shareableTid": {
      "type": [
        "string",
        "null"
      ],
      "description": "Non-null when the result is publicly shareable. Public share identifier for this session. Equal to tid when the session is shareable; null when the session is private. Presence of a value is the indicator that share links may be generated."
    },
    "testType": {
      "type": "string",
      "enum": [
        "url",
        "html_paste"
      ],
      "description": "Type of test performed (e.g., URL or direct HTML paste)"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed"
      ],
      "description": "Pending and running mean poll again; completed means full results are present"
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The URL that was analyzed"
    },
    "findingSentence": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pre-generated natural language verdict; use as the primary summary"
    },
    "analysisSummary": {
      "type": "object",
      "description": "Aggregate scores for one test session",
      "properties": {
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 instant of the analysis"
        },
        "totalIssues": {
          "type": "integer",
          "description": "Total open issues across all categories"
        },
        "overallScore": {
          "type": "number",
          "description": "Overall GEO visibility score (0-100)"
        },
        "categoryScores": {
          "type": "object",
          "properties": {
            "semantic": {
              "type": "number",
              "description": "Semantic HTML5 score (0-100)"
            },
            "accessibility": {
              "type": "number",
              "description": "Accessibility score (0-100)"
            },
            "schema": {
              "type": "number",
              "description": "schema.org markup score (0-100)"
            },
            "nojs": {
              "type": "number",
              "description": "No-JS rendering score (0-100)"
            },
            "javascript": {
              "type": "number",
              "description": "JavaScript dependency score (0-100)"
            },
            "headings": {
              "type": "number",
              "description": "Heading structure score (0-100)"
            },
            "social": {
              "type": "number",
              "description": "Social tags score (0-100)"
            }
          },
          "description": "Score per analysis category (0-100)"
        },
        "categoryIssueCounts": {
          "type": "object",
          "properties": {
            "semantic": {
              "type": "integer",
              "description": "Number of open semantic HTML5 issues"
            },
            "accessibility": {
              "type": "integer",
              "description": "Number of open accessibility issues"
            },
            "schema": {
              "type": "integer",
              "description": "Number of open schema.org markup issues"
            },
            "nojs": {
              "type": "integer",
              "description": "Number of open No-JS rendering issues"
            },
            "javascript": {
              "type": "integer",
              "description": "Number of open JavaScript dependency issues"
            },
            "headings": {
              "type": "integer",
              "description": "Number of open heading structure issues"
            },
            "social": {
              "type": "integer",
              "description": "Number of open social tag issues"
            }
          },
          "description": "Open issue count per analysis category"
        },
        "jsDependencySource": {
          "type": "string",
          "enum": [
            "measured",
            "estimated",
            "unavailable"
          ],
          "description": "How the JS dependency score was derived"
        }
      }
    },
    "results": {
      "type": "array",
      "description": "Per-category result records. detail=full: each carries analysisType and complete resultData (semantic tree, per-element issues); issues carry fixId for gvt_get_fix. detail=summary: each carries analysisType, score, and the top issues deduplicated by type (capped at 10 per category); the nojs_rendered duplicate pass is omitted — analysisSummary.categoryIssueCounts keeps the true totals.",
      "items": {
        "type": "object",
        "properties": {
          "analysisType": {
            "type": "string",
            "enum": [
              "heading",
              "semantic",
              "accessibility",
              "schema",
              "javascript",
              "nojs",
              "social"
            ],
            "description": "Which analysis category this record holds"
          },
          "score": {
            "type": "number",
            "description": "Category score (0-100), present in summary mode when the category reports one"
          },
          "issues": {
            "type": "array",
            "description": "Issue records; in summary mode each carries type, severity, impact, weight, element, description, and fixId (remediation comes from gvt_get_fix, not the payload)"
          }
        }
      }
    },
    "createdAt": {
      "type": "string",
      "description": "ISO 8601 instant of test creation"
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO 8601 instant of the last update to this test session"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 instant when this test session and its results will expire and be deleted"
    },
    "isPublic": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether this test result is publicly accessible"
    }
  },
  "description": "Results for one test. While status is pending or running, results are incomplete — wait and retry. detail=summary returns the compact shape; detail=full (the default) returns complete per-category resultData."
}

List visibility tests for the authenticated user, newest first. Supports filtering by domain (optionally including subdomains), by URL (exact or contains match), by creation date range, by status, and by test type. This is the tid and history discovery surface: use it to find the exact recorded URL string and tids that gvt_get_baseline, gvt_get_latest, and gvt_get_test_results require, and use gvt_get_score_trend instead when you only need baseline-vs-latest deltas — it skips the paging entirely.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 10, max 100)",
      "default": 10
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of records to skip before returning results (not a page number). Use offset=0 for the first page, offset=limit for the second page, etc.",
      "default": 0
    },
    "domain": {
      "type": "string",
      "description": "Domain to filter tests by, e.g. example.com. Subdomains are included unless includeSubdomains is false."
    },
    "includeSubdomains": {
      "type": "boolean",
      "default": true,
      "description": "If true (the default), includes tests for subdomains of the given domain. Set false to match the exact domain only."
    },
    "url": {
      "type": "string",
      "description": "URL to filter tests by; matched per urlMode (contains by default)."
    },
    "urlMode": {
      "type": "string",
      "enum": [
        "exact",
        "contains"
      ],
      "default": "contains",
      "description": "How the url filter matches: \"exact\" for full-URL equality, \"contains\" for substring match."
    },
    "createdFrom": {
      "type": "string",
      "description": "Inclusive creation-date lower bound. YYYY-MM-DD (UTC midnight) or full ISO 8601 instant."
    },
    "createdTo": {
      "type": "string",
      "description": "Exclusive creation-date upper bound. YYYY-MM-DD (UTC midnight) or full ISO 8601 instant."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed"
      ],
      "description": "Test status to filter by: pending, processing, completed, or failed."
    },
    "testType": {
      "type": "string",
      "enum": [
        "url",
        "html",
        "html_paste"
      ],
      "description": "Test type to filter by: url, html, or html_paste."
    },
    "sortDirection": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Sort direction by creation date: desc (newest first, default) or asc (oldest first)."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "tests": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Test session summaries (tid, url, status, analysisSummary, createdAt)"
      },
      "description": "The matching test sessions on this page"
    },
    "total": {
      "type": "integer",
      "description": "Total matching tests before pagination"
    },
    "limit": {
      "type": "integer",
      "description": "Page size actually applied"
    },
    "offset": {
      "type": "integer",
      "description": "Row offset applied to this page"
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when more pages exist"
    },
    "nextOffset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Offset for the next page, null on the last page"
    },
    "domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "The domain filter actually applied, if any"
    },
    "includeSubdomains": {
      "type": "boolean",
      "description": "Whether subdomains were included in the domain filter"
    },
    "createdFrom": {
      "type": [
        "string",
        "null"
      ],
      "description": "Effective lower creation-date bound, if any"
    },
    "createdTo": {
      "type": [
        "string",
        "null"
      ],
      "description": "Effective upper creation-date bound, if any"
    },
    "ttlMs": {
      "type": "integer",
      "description": "Suggested client cache lifetime in milliseconds"
    }
  },
  "description": "Filtered, paginated test history, newest first"
}

Get the oldest baseline test snapshot for a single URL, including expired tests. For pre-computed baseline-vs-latest deltas without fetching full snapshots, use gvt_get_score_trend instead; for baselines across many URLs in one call, use gvt_list_baselines. Use with gvt_get_latest to compare baseline vs current when you need the full snapshot detail on both ends. The url must be passed exactly as the test was run — matching is exact string equality (scheme, host, path, trailing slash), not nearest-match. When unsure of the recorded form, discover it with gvt_list_tests first.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to look up (must match the URL used when the test was run)."
    }
  },
  "required": [
    "url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "Test ID of the snapshot"
    },
    "url": {
      "type": "string",
      "description": "The URL this snapshot analyzed"
    },
    "status": {
      "type": "string",
      "description": "Snapshot status (completed, failed, etc.)"
    },
    "findingSentence": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pre-generated natural language verdict for this snapshot"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO 8601 instant this snapshot was created"
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO 8601 instant this snapshot was last updated"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 instant this snapshot will expire"
    },
    "testType": {
      "type": "string",
      "enum": [
        "url",
        "html_paste"
      ],
      "description": "The type of the test run"
    },
    "isPublic": {
      "type": "boolean",
      "description": "Whether this test is publicly visible"
    },
    "shareableTid": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public share ID, non-null when shareable"
    },
    "analysisSummary": {
      "type": "object",
      "description": "Aggregate scores for this test",
      "properties": {
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 instant of the analysis"
        },
        "totalIssues": {
          "type": "integer",
          "description": "Total open issues across all categories"
        },
        "overallScore": {
          "type": "number",
          "description": "Overall GEO visibility score (0-100)"
        },
        "categoryScores": {
          "type": "object",
          "properties": {
            "semantic": {
              "type": "number",
              "description": "Semantic HTML5 score (0-100)"
            },
            "accessibility": {
              "type": "number",
              "description": "Accessibility score (0-100)"
            },
            "schema": {
              "type": "number",
              "description": "schema.org markup score (0-100)"
            },
            "nojs": {
              "type": "number",
              "description": "No-JS rendering score (0-100)"
            },
            "javascript": {
              "type": "number",
              "description": "JavaScript dependency score (0-100)"
            },
            "headings": {
              "type": "number",
              "description": "Heading structure score (0-100)"
            },
            "social": {
              "type": "number",
              "description": "Social tags score (0-100)"
            }
          },
          "description": "Score per analysis category (0-100)"
        },
        "categoryIssueCounts": {
          "type": "object",
          "properties": {
            "semantic": {
              "type": "integer",
              "description": "Number of open semantic HTML5 issues"
            },
            "accessibility": {
              "type": "integer",
              "description": "Number of open accessibility issues"
            },
            "schema": {
              "type": "integer",
              "description": "Number of open schema.org markup issues"
            },
            "nojs": {
              "type": "integer",
              "description": "Number of open No-JS rendering issues"
            },
            "javascript": {
              "type": "integer",
              "description": "Number of open JavaScript dependency issues"
            },
            "headings": {
              "type": "integer",
              "description": "Number of open heading structure issues"
            },
            "social": {
              "type": "integer",
              "description": "Number of open social tag issues"
            }
          },
          "description": "Open issue count per analysis category"
        },
        "jsDependencySource": {
          "type": "string",
          "enum": [
            "measured",
            "estimated",
            "unavailable"
          ],
          "description": "How the JS dependency score was derived"
        }
      }
    },
    "oldest": {
      "type": [
        "object",
        "null"
      ],
      "description": "Null when no test exists for the URL"
    },
    "message": {
      "type": "string",
      "description": "Present only in the no-test case"
    }
  },
  "description": "Oldest baseline snapshot for one URL, including expired tests. On success the snapshot fields sit at the top level; when no test exists the response is { url, oldest: null, message }."
}

Get the most recent non-expired test snapshot for a single URL. For pre-computed baseline-vs-latest deltas without fetching full snapshots, use gvt_get_score_trend instead. Use with gvt_get_baseline to compare baseline vs current when you need the full snapshot detail on both ends. The url must be passed exactly as the test was run — matching is exact string equality, not nearest-match; an unrecorded URL returns 404. Considers only the authenticated caller's own non-expired tests.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to look up (must match the URL used when the test was run)."
    }
  },
  "required": [
    "url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "Test ID of the snapshot"
    },
    "url": {
      "type": "string",
      "description": "The URL this snapshot analyzed"
    },
    "status": {
      "type": "string",
      "description": "Snapshot status (completed, failed, etc.)"
    },
    "findingSentence": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pre-generated natural language verdict for this snapshot"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO 8601 instant this snapshot was created"
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO 8601 instant this snapshot was last updated"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 instant this snapshot will expire"
    },
    "testType": {
      "type": "string",
      "enum": [
        "url",
        "html_paste"
      ],
      "description": "The type of the test run"
    },
    "isPublic": {
      "type": "boolean",
      "description": "Whether this test is publicly visible"
    },
    "shareableTid": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public share ID, non-null when shareable"
    },
    "analysisSummary": {
      "type": "object",
      "description": "Aggregate scores for this test",
      "properties": {
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 instant of the analysis"
        },
        "totalIssues": {
          "type": "integer",
          "description": "Total open issues across all categories"
        },
        "overallScore": {
          "type": "number",
          "description": "Overall GEO visibility score (0-100)"
        },
        "categoryScores": {
          "type": "object",
          "properties": {
            "semantic": {
              "type": "number",
              "description": "Semantic HTML5 score (0-100)"
            },
            "accessibility": {
              "type": "number",
              "description": "Accessibility score (0-100)"
            },
            "schema": {
              "type": "number",
              "description": "schema.org markup score (0-100)"
            },
            "nojs": {
              "type": "number",
              "description": "No-JS rendering score (0-100)"
            },
            "javascript": {
              "type": "number",
              "description": "JavaScript dependency score (0-100)"
            },
            "headings": {
              "type": "number",
              "description": "Heading structure score (0-100)"
            },
            "social": {
              "type": "number",
              "description": "Social tags score (0-100)"
            }
          },
          "description": "Score per analysis category (0-100)"
        },
        "categoryIssueCounts": {
          "type": "object",
          "properties": {
            "semantic": {
              "type": "integer",
              "description": "Number of open semantic HTML5 issues"
            },
            "accessibility": {
              "type": "integer",
              "description": "Number of open accessibility issues"
            },
            "schema": {
              "type": "integer",
              "description": "Number of open schema.org markup issues"
            },
            "nojs": {
              "type": "integer",
              "description": "Number of open No-JS rendering issues"
            },
            "javascript": {
              "type": "integer",
              "description": "Number of open JavaScript dependency issues"
            },
            "headings": {
              "type": "integer",
              "description": "Number of open heading structure issues"
            },
            "social": {
              "type": "integer",
              "description": "Number of open social tag issues"
            }
          },
          "description": "Open issue count per analysis category"
        },
        "jsDependencySource": {
          "type": "string",
          "enum": [
            "measured",
            "estimated",
            "unavailable"
          ],
          "description": "How the JS dependency score was derived"
        }
      }
    },
    "latest": {
      "type": [
        "object",
        "null"
      ],
      "description": "Null when no test exists for the URL"
    },
    "message": {
      "type": "string",
      "description": "Present only in the no-test case"
    }
  },
  "description": "Most recent non-expired snapshot for one URL. On success the snapshot fields sit at the top level; when no test exists the response is { url, latest: null, message }."
}

Get the oldest baseline test snapshots for a batch of URLs (up to 100) in a single call. Each result includes the URL and its oldest test object (null if no test exists for that URL). For a single URL use gvt_get_baseline; for pre-computed baseline-vs-latest deltas use gvt_get_score_trend. This bulk form is ideal for monthly/periodic batch comparisons: fetch baselines in bulk here, then call gvt_get_latest per URL. One call replaces up to 100 gvt_get_baseline calls; split larger URL sets into consecutive calls of at most 100. Order of results follows the submitted order.

{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "string"
      },
      "description": "Array of URLs to look up (max 100)."
    }
  },
  "required": [
    "urls"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "requested": {
      "type": "integer",
      "description": "Number of URLs requested"
    },
    "found": {
      "type": "integer",
      "description": "URLs that had at least one test"
    },
    "results": {
      "type": "array",
      "description": "One entry per requested URL, in request order",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL this record describes"
          },
          "oldest": {
            "type": [
              "object",
              "null"
            ],
            "description": "One test snapshot: tid, createdAt, overallScore, categoryScores",
            "properties": {
              "tid": {
                "type": "string",
                "description": "Test ID of this snapshot"
              },
              "createdAt": {
                "type": "string",
                "description": "ISO 8601 instant of this snapshot"
              },
              "overallScore": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Overall GEO visibility score (0-100), null when the test failed"
              },
              "categoryScores": {
                "type": "object",
                "properties": {
                  "semantic": {
                    "type": "number",
                    "description": "Semantic HTML5 score (0-100)"
                  },
                  "accessibility": {
                    "type": "number",
                    "description": "Accessibility score (0-100)"
                  },
                  "schema": {
                    "type": "number",
                    "description": "schema.org markup score (0-100)"
                  },
                  "nojs": {
                    "type": "number",
                    "description": "No-JS rendering score (0-100)"
                  },
                  "javascript": {
                    "type": "number",
                    "description": "JavaScript dependency score (0-100)"
                  },
                  "headings": {
                    "type": "number",
                    "description": "Heading structure score (0-100)"
                  },
                  "social": {
                    "type": "number",
                    "description": "Social tags score (0-100)"
                  }
                },
                "description": "Score per analysis category (0-100)"
              }
            }
          }
        }
      }
    },
    "ttlMs": {
      "type": "integer",
      "description": "Suggested client cache lifetime in milliseconds"
    }
  },
  "description": "Oldest baseline snapshots for a batch of URLs (up to 100)"
}

Compare the oldest baseline vs the latest non-expired test for a single URL or an entire domain, with pre-computed per-category deltas (latest minus baseline). Provide exactly one of url or domain. Domain mode matches the exact domain, www.<domain>, and subdomains (alphabetical, capped by limit). Page through the whole domain with offset: offset=0 for the first page, offset=limit for the second, following hasMore/nextOffset. Returns scores and deltas only, not full snapshot detail; for complete snapshots of one URL use gvt_get_baseline and gvt_get_latest. This replaces paging the full test history and computing comparisons client-side, one call per site.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Single URL scope (XOR with domain)."
    },
    "domain": {
      "type": "string",
      "description": "Domain scope — matches the domain, www.<domain>, and subdomains (XOR with url)."
    },
    "limit": {
      "type": "integer",
      "maximum": 100,
      "default": 25,
      "description": "Cap on returned records in domain mode (max 100, default 25)."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Number of matched URLs to skip in domain mode (row skip, not a page number). Use offset=0 for the first page, offset=limit for the second. Ignored in single-URL mode."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "url",
        "domain"
      ],
      "description": "Which mode the comparison ran in"
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The compared URL in url mode, else null"
    },
    "domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "The compared domain in domain mode, else null"
    },
    "urlCount": {
      "type": "integer",
      "description": "Total matched URLs before pagination"
    },
    "trends": {
      "type": "array",
      "description": "One row per matched URL, baseline vs latest with deltas",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL this trend row describes"
          },
          "testCount": {
            "type": "integer",
            "description": "Total tests ever run for this URL"
          },
          "baseline": {
            "type": [
              "object",
              "null"
            ],
            "description": "One test snapshot: tid, createdAt, overallScore, categoryScores",
            "properties": {
              "tid": {
                "type": "string",
                "description": "Test ID of this snapshot"
              },
              "createdAt": {
                "type": "string",
                "description": "ISO 8601 instant of this snapshot"
              },
              "overallScore": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Overall GEO visibility score (0-100), null when the test failed"
              },
              "categoryScores": {
                "type": "object",
                "properties": {
                  "semantic": {
                    "type": "number",
                    "description": "Semantic HTML5 score (0-100)"
                  },
                  "accessibility": {
                    "type": "number",
                    "description": "Accessibility score (0-100)"
                  },
                  "schema": {
                    "type": "number",
                    "description": "schema.org markup score (0-100)"
                  },
                  "nojs": {
                    "type": "number",
                    "description": "No-JS rendering score (0-100)"
                  },
                  "javascript": {
                    "type": "number",
                    "description": "JavaScript dependency score (0-100)"
                  },
                  "headings": {
                    "type": "number",
                    "description": "Heading structure score (0-100)"
                  },
                  "social": {
                    "type": "number",
                    "description": "Social tags score (0-100)"
                  }
                },
                "description": "Score per analysis category (0-100)"
              }
            }
          },
          "latest": {
            "type": [
              "object",
              "null"
            ],
            "description": "One test snapshot: tid, createdAt, overallScore, categoryScores",
            "properties": {
              "tid": {
                "type": "string",
                "description": "Test ID of this snapshot"
              },
              "createdAt": {
                "type": "string",
                "description": "ISO 8601 instant of this snapshot"
              },
              "overallScore": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Overall GEO visibility score (0-100), null when the test failed"
              },
              "categoryScores": {
                "type": "object",
                "properties": {
                  "semantic": {
                    "type": "number",
                    "description": "Semantic HTML5 score (0-100)"
                  },
                  "accessibility": {
                    "type": "number",
                    "description": "Accessibility score (0-100)"
                  },
                  "schema": {
                    "type": "number",
                    "description": "schema.org markup score (0-100)"
                  },
                  "nojs": {
                    "type": "number",
                    "description": "No-JS rendering score (0-100)"
                  },
                  "javascript": {
                    "type": "number",
                    "description": "JavaScript dependency score (0-100)"
                  },
                  "headings": {
                    "type": "number",
                    "description": "Heading structure score (0-100)"
                  },
                  "social": {
                    "type": "number",
                    "description": "Social tags score (0-100)"
                  }
                },
                "description": "Score per analysis category (0-100)"
              }
            }
          },
          "isSameTest": {
            "type": "boolean",
            "description": "True when baseline and latest are the same test (no movement yet)"
          },
          "deltas": {
            "type": [
              "object",
              "null"
            ],
            "description": "Latest minus baseline",
            "properties": {
              "overall": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Overall score change, latest minus baseline"
              },
              "categories": {
                "type": "object",
                "properties": {
                  "semantic": {
                    "type": "number",
                    "description": "Semantic HTML5 score (0-100)"
                  },
                  "accessibility": {
                    "type": "number",
                    "description": "Accessibility score (0-100)"
                  },
                  "schema": {
                    "type": "number",
                    "description": "schema.org markup score (0-100)"
                  },
                  "nojs": {
                    "type": "number",
                    "description": "No-JS rendering score (0-100)"
                  },
                  "javascript": {
                    "type": "number",
                    "description": "JavaScript dependency score (0-100)"
                  },
                  "headings": {
                    "type": "number",
                    "description": "Heading structure score (0-100)"
                  },
                  "social": {
                    "type": "number",
                    "description": "Social tags score (0-100)"
                  }
                },
                "description": "Per-category score change, latest minus baseline"
              }
            }
          }
        }
      }
    },
    "limit": {
      "type": "integer",
      "description": "Max records per page in domain mode"
    },
    "offset": {
      "type": "integer",
      "description": "Row offset applied to this page"
    },
    "returned": {
      "type": "integer",
      "description": "Records in this page"
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when more pages exist"
    },
    "nextOffset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Offset for the next page, null on the last page"
    },
    "truncated": {
      "type": "boolean",
      "deprecated": true,
      "description": "Deprecated. Use `hasMore` instead."
    },
    "includeSubdomains": {
      "type": "boolean",
      "description": "Whether subdomains were included in the domain search"
    },
    "compare": {
      "type": [
        "object",
        "null"
      ],
      "description": "Comparison window settings used"
    },
    "windowSummary": {
      "type": [
        "object",
        "null"
      ],
      "description": "Summary of window comparison results"
    },
    "ttlMs": {
      "type": "integer",
      "description": "Suggested client cache lifetime in milliseconds"
    }
  },
  "description": "Baseline vs latest comparison with pre-computed deltas, scoped to one URL or a whole domain"
}

Discovers and ranks URLs from a domain's XML sitemaps to find the most significant pages (homepages, product pages, recently updated content) before analyzing them. Supports URL-pattern filtering and automatically flags robots.txt-blocked and already-tested pages. Legal/policy boilerplate (privacy, terms, cookies, disclaimers, refunds) is flagged legalPage:true with a -25 significance penalty; use the legalPages filter to drop it (exclude) or isolate it for a policy-coverage audit (only). Parameters group into three jobs: discovery (url), ranking and paging (limit, sort), and filtering (include and exclude URL patterns, excludeDisallowed, excludeTested, excludeScheduled, legalPages).

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The target website URL or an explicit sitemap .xml URL."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "default": 10,
      "description": "Maximum number of URLs to return (default 10)."
    },
    "sort": {
      "type": "string",
      "enum": [
        "significance",
        "lastmod",
        "alphabetical",
        "document"
      ],
      "default": "significance",
      "description": "How to sort the discovered URLs. 'significance' uses SEO heuristics."
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Wildcard patterns to require (e.g., '*blog*'). Only '*' wildcards are supported."
    },
    "exclude": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Wildcard patterns to reject (e.g., '*archive*')."
    },
    "excludeDisallowed": {
      "type": "boolean",
      "default": false,
      "description": "If true, silently drops URLs that are blocked by robots.txt."
    },
    "excludeTested": {
      "type": "boolean",
      "default": false,
      "description": "If true, omits URLs the user has already tested."
    },
    "excludeScheduled": {
      "type": "boolean",
      "default": false,
      "description": "If true, omits URLs currently in the testing queue."
    },
    "legalPages": {
      "type": "string",
      "enum": [
        "include",
        "exclude",
        "only"
      ],
      "default": "include",
      "description": "Tri-state filter for legal/policy boilerplate pages (privacy, terms, cookies, disclaimers, refund policies, etc). \"include\" keeps them (default), \"exclude\" drops them, and \"only\" returns just the legal/policy pages — useful for auditing a site's policy coverage."
    }
  },
  "required": [
    "url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "requestedUrl": {
      "type": "string",
      "description": "The URL or sitemap URL that was resolved"
    },
    "resolvedSitemaps": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Sitemap URLs actually parsed"
    },
    "robotsTxtFound": {
      "type": "boolean",
      "description": "Whether a robots.txt was found and consulted"
    },
    "sitemapCount": {
      "type": "integer",
      "description": "Number of sitemaps parsed"
    },
    "totalDiscovered": {
      "type": "integer",
      "description": "Raw URL count discovered before filtering"
    },
    "matched": {
      "type": "integer",
      "description": "URLs remaining after include/exclude and legalPages filters"
    },
    "returned": {
      "type": "integer",
      "description": "URLs actually returned after the limit"
    },
    "limit": {
      "type": "integer",
      "description": "Effective result cap"
    },
    "sort": {
      "type": "string",
      "enum": [
        "significance",
        "lastmod",
        "alphabetical",
        "document"
      ],
      "description": "The sort actually applied to the results"
    },
    "legalPages": {
      "type": "string",
      "enum": [
        "include",
        "exclude",
        "only"
      ],
      "description": "The legal-page filter actually applied"
    },
    "legalPagesFound": {
      "type": "integer",
      "description": "How many of the URLs discovered across all sitemaps were detected as legal/policy boilerplate, counted BEFORE any filtering or limiting is applied."
    },
    "truncated": {
      "type": "boolean",
      "description": "True if the underlying sitemap parser hit its 5000-URL cap during fetching."
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when the filtered set was cut short by the limit"
    },
    "bulkUrlLimit": {
      "type": "integer",
      "description": "How many of these URLs the caller's tier permits in one batch-analyze call."
    },
    "urls": {
      "type": "array",
      "description": "Discovered URLs, ranked per the sort setting",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The discovered URL"
          },
          "significanceScore": {
            "type": "number",
            "description": "SEO significance score used for the default ranking"
          },
          "pathDepth": {
            "type": "integer",
            "description": "Path depth from the site root (1 = homepage)"
          },
          "legalPage": {
            "type": "boolean",
            "description": "True when detected as legal/policy boilerplate"
          },
          "lastmod": {
            "type": [
              "string",
              "null"
            ],
            "description": "Last-modified timestamp from the sitemap, when present"
          },
          "priority": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sitemap priority hint, when present"
          },
          "changefreq": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sitemap change frequency hint, when present"
          },
          "disallowedByRobots": {
            "type": "boolean",
            "description": "True when robots.txt disallows crawling this URL"
          },
          "alreadyTested": {
            "type": "boolean",
            "description": "True when the caller has an existing test for this URL"
          },
          "alreadyScheduled": {
            "type": "boolean",
            "description": "True when this URL is already in the testing queue"
          }
        }
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Per-sitemap fetch or parse failures; non-empty means discovery was partial"
    }
  },
  "description": "Ranked URL discovery from a domain XML sitemaps"
}

Toggle the public visibility of a test session. Set is_public to true to make the test shareable and receive its public share URL, or false to make it private. The response confirms the new state and, when making a test public, includes the share_url the recipient can visit without any authentication. is_public is the only lever: true both publishes and yields the link in this same response; false revokes access to any previously issued share_url immediately. This is the only way to control who can view a test result without requiring MCP authentication.

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "The 8-character test ID returned by gvt_run_visibility_test."
    },
    "is_public": {
      "type": "boolean",
      "description": "true to make the test publicly shareable, false to make it private."
    }
  },
  "required": [
    "tid",
    "is_public"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True when the visibility change was applied"
    },
    "is_public": {
      "type": "boolean",
      "description": "The new public visibility state"
    },
    "tid": {
      "type": "string",
      "description": "The test that was modified"
    },
    "share_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public share URL, present when is_public is true; the recipient needs no authentication. Null when sharing failed or the test is private"
    }
  }
}

Permanently delete a test session and all its associated results. This action cannot be undone. Use gvt_set_test_visibility instead if you only want to hide a test from public view. Deleting a test does not delete its schedule (if one exists): recurring runs continue until removed via gvt_schedule_test delete mode.

{
  "type": "object",
  "properties": {
    "tid": {
      "type": "string",
      "description": "The 8-character test ID of the test to delete."
    }
  },
  "required": [
    "tid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True when the test was deleted"
    },
    "message": {
      "type": "string",
      "description": "Human-readable confirmation"
    }
  }
}

Queue up to 500 URLs for batch GEO visibility testing. Returns a batch ID for tracking progress. Optionally add URLs to recurring schedules (daily, weekly, monthly) during the same call. Poll gvt_get_batch_status with the batchId until status is completed or failed; then get the compact per-page score summary with gvt_get_batch_summary, or individual results with gvt_get_test_results. This tool queues paid test runs and consumes credits; for score interpretation, methodology, or reference knowledge, use gvt_get_knowledge instead — it never runs tests. A webhook URL can be provided to receive a completion notification; when set, the response returns webhookSecret, an HMAC key for verifying that the notification genuinely came from GVT. Duplicate URLs in the submitted array are collapsed, so totalUrls may be smaller than the array you sent.

{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "minItems": 1,
      "maxItems": 500,
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL to analyze"
          },
          "wpPostId": {
            "type": "string",
            "description": "Optional WordPress post ID for association"
          },
          "addToSchedule": {
            "type": "object",
            "properties": {
              "frequency": {
                "type": "string",
                "enum": [
                  "daily",
                  "weekly",
                  "monthly"
                ],
                "description": "How often to re-run the test"
              }
            },
            "required": [
              "frequency"
            ]
          }
        },
        "required": [
          "url"
        ]
      },
      "description": "Array of URL objects to test (max 500)"
    },
    "webhookUrl": {
      "type": "string",
      "description": "Optional HTTPS URL to receive a batch completion webhook"
    }
  },
  "required": [
    "urls"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string",
      "description": "UUID for tracking the batch"
    },
    "totalUrls": {
      "type": "integer",
      "description": "URLs accepted into the batch"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued"
      ],
      "description": "Always queued at submission time"
    },
    "webhookConfigured": {
      "type": "boolean",
      "description": "True when a completion webhook URL was supplied"
    },
    "webhookSecret": {
      "type": [
        "string",
        "null"
      ],
      "description": "HMAC secret for verifying the webhook, null when no webhook"
    }
  },
  "description": "Batch acknowledgement. Poll gvt_get_batch_status with the batchId until status is completed or failed, then retrieve results via gvt_get_test_results."
}

Retrieves the current progress, state, and test IDs (tids) of an ongoing or completed visibility testing batch. Poll this tool with the batchId returned by gvt_run_visibility_batch until status is completed or failed. A tid appears on each URL entry only after its test completes — then call gvt_get_batch_summary for the compact per-page scores and top shared issues, or gvt_get_test_results for a single test. Batch records are retained for the lifetime of the account (no automated pruning); an unknown, pruned, or foreign batchId returns 404. Read-only: consumes rate limit, never test credits. Duplicate URLs in a batch are collapsed, so counts always sum to totalUrls.

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string",
      "format": "uuid",
      "description": "The UUID of the batch to check, returned by gvt_run_visibility_batch."
    }
  },
  "required": [
    "batchId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string",
      "description": "The batch that was queried"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "failed"
      ],
      "description": "Aggregate batch state; completed means every per-URL test reached a terminal state"
    },
    "totalUrls": {
      "type": "integer",
      "description": "URLs in the batch after duplicate collapsing"
    },
    "submittedAt": {
      "type": "string",
      "description": "ISO 8601 instant of batch submission"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 instant when the batch reached a terminal state, null while in flight"
    },
    "counts": {
      "type": "object",
      "description": "Per-URL test state counts; the four fields always sum to totalUrls",
      "properties": {
        "queued": {
          "type": "integer",
          "description": "Tests not yet started"
        },
        "running": {
          "type": "integer",
          "description": "Tests currently executing"
        },
        "completed": {
          "type": "integer",
          "description": "Tests that completed successfully"
        },
        "failed": {
          "type": "integer",
          "description": "Tests that failed or were skipped"
        }
      }
    },
    "urls": {
      "type": "array",
      "description": "One entry per submitted URL, in submission order",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The submitted URL"
          },
          "tid": {
            "type": [
              "string",
              "null"
            ],
            "description": "Test ID once that test completed, null while queued, running, or failed"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ],
            "description": "This URL test state"
          }
        }
      }
    }
  },
  "description": "Batch progress and per-URL state. Poll until status is completed or failed."
}

Compact per-page results and pre-computed aggregates for a completed visibility testing batch: per-URL overall and category scores, findingSentence, average overall score, strongest and weakest categories, best and worst scoring pages, and the top shared issue types with their fixIds. One call replaces one gvt_get_test_results call per URL for audit and status-report workflows — a 10-URL batch drops from roughly 1.6 MB to a few KB of context. The batch must be completed (poll gvt_get_batch_status first); an in-flight batch returns its current status without per-page data. Read-only: consumes rate limit, never test credits. For element-level detail on a single page, call gvt_get_test_results with that page's tid.

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string",
      "format": "uuid",
      "description": "The UUID of the completed batch to summarize, returned by gvt_run_visibility_batch."
    }
  },
  "required": [
    "batchId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string",
      "description": "The batch that was summarized"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "failed"
      ],
      "description": "Aggregate batch state; pages and summary are present only when completed"
    },
    "totalUrls": {
      "type": "integer",
      "description": "URLs in the batch after duplicate collapsing"
    },
    "counts": {
      "type": "object",
      "description": "Per-URL test state counts; the four fields always sum to totalUrls"
    },
    "message": {
      "type": "string",
      "description": "Polling guidance, present when the batch is not completed"
    },
    "pages": {
      "type": "array",
      "description": "One compact entry per URL, in batch order. Failed tests appear with status failed and null scores; they are excluded from the aggregates.",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The tested URL"
          },
          "tid": {
            "type": "string",
            "description": "Test ID, for gvt_get_test_results deep dives"
          },
          "status": {
            "type": "string",
            "description": "This URL test state"
          },
          "overallScore": {
            "type": [
              "number",
              "null"
            ],
            "description": "Overall GEO visibility score (0-100), null when the test failed"
          },
          "categoryScores": {
            "type": [
              "object",
              "null"
            ],
            "description": "Score per analysis category (0-100)"
          },
          "findingSentence": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pre-generated natural language verdict"
          }
        }
      }
    },
    "summary": {
      "type": "object",
      "description": "Aggregates computed over the completed pages",
      "properties": {
        "averageOverallScore": {
          "type": [
            "number",
            "null"
          ],
          "description": "Mean overall score across completed pages, rounded to one decimal"
        },
        "categoryAverages": {
          "type": "object",
          "description": "Mean score per category across completed pages"
        },
        "strongestCategory": {
          "type": [
            "string",
            "null"
          ],
          "description": "Category with the highest average score"
        },
        "weakestCategory": {
          "type": [
            "string",
            "null"
          ],
          "description": "Category with the lowest average score"
        },
        "bestPage": {
          "type": [
            "object",
            "null"
          ],
          "description": "Highest scoring page: url and overallScore"
        },
        "worstPage": {
          "type": [
            "object",
            "null"
          ],
          "description": "Lowest scoring page: url and overallScore"
        },
        "topIssueTypes": {
          "type": "array",
          "description": "Up to five issue types shared across pages (error and warning severities, counted once per page), each with its fixId for gvt_get_fix",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "Issue type identifier"
              },
              "count": {
                "type": "integer",
                "description": "Pages carrying this issue type"
              },
              "severity": {
                "type": "string",
                "description": "Highest severity observed for this issue type"
              },
              "fixId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "fixId for gvt_get_fix, when the issue type is mapped"
              }
            }
          }
        }
      }
    }
  },
  "description": "Compact per-page results and pre-computed aggregates for a completed batch. An in-flight or failed batch returns its status and counts without per-page data."
}

Retrieves the paginated roster of the authenticated caller's test monitoring schedules, allowing filtering by domain, frequency, and status. This is the only way to discover existing schedules and their schids, which the pause/resume/cancel/change_frequency modes of gvt_schedule_test require. Completed one-off rows are hidden by default: batch runs create a throwaway once row per queued URL, so include them only with includeCompletedOnce true. The row's tid is deliberately not surfaced (it is often stale); use gvt_list_tests or gvt_get_latest for test result lookups. Read-only: consumes rate limit, never test credits.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "The maximum number of schedules requested for this page."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "The number of skipped items from the beginning of the result set."
    },
    "domain": {
      "type": "string",
      "description": "Filter to schedules matching this domain substring."
    },
    "includeSubdomains": {
      "type": "boolean",
      "default": true,
      "description": "Whether subdomains should be included in the domain filter match."
    },
    "frequency": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "once"
      ],
      "description": "Filter by repetition interval."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "completed"
      ],
      "description": "Filter by the derived overall state of the schedule."
    },
    "includeCompletedOnce": {
      "type": "boolean",
      "default": false,
      "description": "Whether to include completed one-off schedules in the results. Hidden by default because batch runs create a throwaway once row per queued URL; include them only when investigating batch history."
    },
    "sortDirection": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Sort order by creation time; desc is newest first."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "schedules": {
      "type": "array",
      "description": "One entry per schedule, newest first by creation time",
      "items": {
        "type": "object",
        "properties": {
          "schid": {
            "type": "string",
            "description": "Opaque 8-character schedule identifier, accepted by the gvt_schedule_test pause/resume/cancel/change_frequency modes"
          },
          "url": {
            "type": "string",
            "description": "The monitored URL"
          },
          "wpPostId": {
            "type": [
              "string",
              "null"
            ],
            "description": "WordPress post ID when the schedule was created from the WordPress plugin, null otherwise"
          },
          "frequency": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "once"
            ],
            "description": "How often the test recurs; once is a one-off scheduled run"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "completed"
            ],
            "description": "Derived overall state; cancelled schedules are deleted outright and never appear here"
          },
          "isPaused": {
            "type": "boolean",
            "description": "True when the schedule is paused; a paused schedule retains its schid and its nextRunAt"
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 instant the schedule was created"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 8601 instant of the most recent schedule change, null when never modified"
          },
          "lastRunAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 8601 instant of the most recent completed run, null when it has not run yet"
          },
          "nextRunAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 8601 instant of the next queued run. Retained while paused (it fires on resume); null for completed one-off runs or when nothing is scheduled yet"
          },
          "consecutiveFailureCount": {
            "type": "integer",
            "description": "Number of consecutive failed runs; a high count precedes auto-pause"
          },
          "autoPauseReason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reason the schedule was automatically paused, null when not auto-paused"
          }
        }
      }
    },
    "total": {
      "type": "integer",
      "description": "Total schedules matching the filters, across all pages"
    },
    "limit": {
      "type": "integer",
      "description": "Page size applied to this response"
    },
    "offset": {
      "type": "integer",
      "description": "Offset applied to this response"
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when more results exist beyond this page"
    },
    "nextOffset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Offset for the next page, null when hasMore is false"
    },
    "domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "The applied domain filter, null when unfiltered"
    },
    "includeSubdomains": {
      "type": "boolean",
      "description": "The applied subdomain-inclusion setting"
    },
    "frequency": {
      "type": [
        "string",
        "null"
      ],
      "description": "The applied frequency filter, null when unfiltered"
    },
    "status": {
      "type": [
        "string",
        "null"
      ],
      "description": "The applied status filter, null when unfiltered"
    },
    "includeCompletedOnce": {
      "type": "boolean",
      "description": "Whether completed one-off rows were included in this response"
    },
    "maxActiveSchedules": {
      "type": "integer",
      "description": "The caller's cap on active schedules; add mode enforces this limit"
    },
    "allowedFrequencies": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Frequencies the caller may set when creating schedules"
    }
  },
  "description": "Paginated roster of the caller's monitoring schedules with applied filters echoed back."
}

Manage recurring GVT test schedules: add, delete, reset, pause, resume, cancel, and change_frequency. Discover existing schedules and their schids via gvt_list_schedules; control modes require a schid. For one-off tests use gvt_run_visibility_test; for queued batches without recurrence use gvt_run_visibility_batch. Modes: "add" upserts schedules for the provided urls without duplicating; "delete" permanently removes schedule entries by schid or url (test results are never deleted by any mode); "reset" is destructive — deletes all matching schedules first (domain-scoped when provided, otherwise ALL account-wide), then upserts the provided urls; "pause" halts reversibly; "resume" restarts a paused schedule and clears auto-pause reasons and failure counts; "cancel" permanently ends the schedule (schid unusable); "change_frequency" updates the recurrence interval. Management modes (add/delete/reset) require urls; control modes require schid. Subscription-tier enforcement applies.

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "add",
        "delete",
        "reset",
        "pause",
        "resume",
        "cancel",
        "change_frequency"
      ],
      "default": "add",
      "description": "Schedule operation mode. add/delete/reset operate on URLs (require urls array). pause/resume/cancel/change_frequency operate on a single schedule (require schid)."
    },
    "domain": {
      "type": "string",
      "description": "Domain to scope a reset operation (reset mode only). e.g. \"example.com\". Matches https://, http://, with/without www., with/without trailing path. Omit to reset ALL schedules."
    },
    "schid": {
      "type": "string",
      "description": "Schedule ID. Required for pause, resume, cancel, and change_frequency modes."
    },
    "frequency": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ],
      "description": "New frequency for the schedule. Required for change_frequency mode."
    },
    "urls": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "schid": {
            "type": "string",
            "description": "Schedule ID (required for delete/reset modes)"
          },
          "url": {
            "type": "string",
            "description": "The URL to schedule (required for add mode; optional in delete mode if schid is provided)"
          },
          "wpPostId": {
            "type": "string",
            "description": "Optional WordPress post ID for association"
          },
          "addToSchedule": {
            "type": "object",
            "properties": {
              "frequency": {
                "type": "string",
                "enum": [
                  "daily",
                  "weekly",
                  "monthly"
                ],
                "description": "How often to re-run the test"
              }
            },
            "required": [
              "frequency"
            ]
          }
        },
        "required": []
      },
      "description": "Array of URL/schedule objects. Required for add, delete, and reset modes."
    }
  },
  "required": [],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True when the requested mode completed"
    },
    "upsertedCount": {
      "type": "integer",
      "description": "Schedules created or updated (add/reset modes)"
    },
    "deletedCount": {
      "type": "integer",
      "description": "Schedule entries removed (delete/reset modes)"
    },
    "deletedByUrl": {
      "type": "array",
      "description": "Per-URL breakdown of deleted schedules (delete mode). Present on delete mode responses, including schid-based deletes; omitted for reset mode.",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL whose schedules were deleted"
          },
          "frequencies": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "daily",
                "weekly",
                "monthly",
                "once"
              ]
            },
            "description": "Frequencies that were removed for this URL"
          },
          "count": {
            "type": "integer",
            "description": "Number of schedule entries deleted for this URL"
          }
        }
      }
    },
    "scheduled": {
      "type": "array",
      "description": "Schedules now in effect (add/reset modes)",
      "items": {
        "type": "object",
        "properties": {
          "schid": {
            "type": "string",
            "description": "Schedule ID for later pause/resume/cancel calls"
          },
          "url": {
            "type": "string",
            "description": "The URL placed on schedule"
          },
          "wpPostId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Associated WordPress post ID, when provided"
          }
        }
      }
    }
  },
  "description": "Result varies by mode: add/reset return upsertedCount and scheduled; delete returns deletedCount and deletedByUrl"
}

Read GVT reference knowledge: how scoring works, score bands and category weights, what each analysis category checks, or GEO glossary definitions. Use it to interpret test results and scores correctly instead of guessing. The topic is matched exactly and case-sensitively (Methodology will not match methodology); unrecognized values fail fast with the valid list. The same content is served as MCP resources at gvt://knowledge/app/* for resource-capable clients.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "all",
        "methodology",
        "scoring",
        "categories",
        "glossary"
      ],
      "default": "all",
      "description": "Which knowledge topic to read: methodology (how GVT analyzes pages), scoring (score bands and category weights), categories (what each of the six categories checks), glossary (GEO term definitions), or all (complete knowledge base)."
    }
  },
  "required": [],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "all",
        "methodology",
        "scoring",
        "categories",
        "glossary"
      ],
      "description": "The topic that was served"
    },
    "uri": {
      "type": "string",
      "description": "The gvt:// resource the content came from"
    },
    "knowledge": {
      "type": "object",
      "description": "Reference content for the requested topic"
    },
    "ttlMs": {
      "type": "integer",
      "description": "Suggested client cache lifetime in milliseconds"
    }
  }
}

Read the canonical fix record for one GVT issue type: severity range, impact, scoring weight, plain-language description, and the recommended remediation. Issue IDs come from the fixId field on issues in gvt_get_test_results output. The same content is served as the gvt://knowledge/fixes/{issue_id} resource template for resource-capable clients. Copy fixId verbatim from the results output — unknown or mistyped IDs return not-found rather than a fuzzy match. Responses are static reference content and cacheable.

{
  "type": "object",
  "properties": {
    "issue_id": {
      "type": "string",
      "description": "Stable issue identifier, e.g. og_title_missing or color-contrast. Matches the fixId field in gvt_get_test_results output."
    }
  },
  "required": [
    "issue_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "issue_id": {
      "type": "string",
      "description": "Stable issue identifier, e.g. og_title_missing"
    },
    "category": {
      "type": "string",
      "description": "Analysis category the issue belongs to"
    },
    "subcategory": {
      "type": "string",
      "description": "Finer-grained grouping within the category"
    },
    "severity_range": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Severity levels this issue can take"
    },
    "impact": {
      "type": "string",
      "description": "Plain-language statement of what the issue costs"
    },
    "weight": {
      "type": "number",
      "description": "Scoring weight"
    },
    "human_description": {
      "type": "string",
      "description": "Human-readable description of the issue"
    },
    "recommendation": {
      "type": "string",
      "description": "The recommended remediation"
    },
    "resourceUri": {
      "type": "string",
      "description": "The gvt:// resource this record was read from"
    },
    "ttlMs": {
      "type": "integer",
      "description": "Suggested client cache lifetime in milliseconds"
    }
  },
  "description": "Canonical fix record for one issue type"
}

List the GVT prompt workflows: user-invocable recipes that chain GVT tools into complete tasks (check a page, review a monthly batch, analyze regressions, verify fixes, set up domain monitoring, report client status). Each entry lists its arguments. Use gvt_get_prompt to render a prompt with concrete argument values, then follow the rendered instructions to run the workflow. This catalog is static and costs nothing to call on every session start — it never queues tests or consumes credits.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "prompts": {
      "type": "array",
      "description": "The prompt workflow catalog",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Prompt name for gvt_get_prompt"
          },
          "title": {
            "type": "string",
            "description": "Human-readable display name"
          },
          "description": {
            "type": "string",
            "description": "What the prompt workflow does"
          },
          "arguments": {
            "type": "array",
            "description": "Arguments the prompt accepts",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Argument name"
                },
                "description": {
                  "type": "string",
                  "description": "What the argument controls"
                },
                "required": {
                  "type": "boolean",
                  "description": "True when the argument must be supplied"
                }
              }
            }
          }
        }
      }
    },
    "promptCount": {
      "type": "integer",
      "description": "Number of prompt workflows in the catalog"
    },
    "ttlMs": {
      "type": "integer",
      "description": "Suggested client cache lifetime in milliseconds"
    }
  }
}

Render a GVT prompt workflow with concrete argument values, returning the complete step-by-step instruction text ready to follow. Also returns the effective arguments that were bound (provided values plus defaults for omitted optionals). Prompt names and their arguments come from gvt_list_prompts; an unknown name or argument key errors rather than guessing. The rendered text references GVT tools by name — call them as instructed.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Prompt name from gvt_list_prompts, e.g. gvt_setup_domain_monitoring."
    },
    "arguments": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Argument values for the prompt, keyed by argument name (e.g. {\"domain\": \"example.com\", \"frequency\": \"weekly\"}). Omit optional arguments to use their defaults."
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The prompt name that was rendered"
    },
    "description": {
      "type": "string",
      "description": "The prompt catalog description"
    },
    "text": {
      "type": "string",
      "description": "Fully interpolated instruction text referencing GVT tools by name"
    },
    "arguments": {
      "type": "object",
      "description": "Effective arguments after binding defaults"
    }
  }
}