Server definition
- Hash
- sha256:3979038ff8785a9f3fe76ef6b2a06f092ef49cbc472c4c80ec94b210156dd65e
- What it is
- What a remote MCP server returned when asked what it offers: 29 tools
The blob, as servednamed by its sha256
{
"instructions": "GetCited audits a site the way an answer engine reads it, tracks its keyword ranks, records which AI engines cite it, and files each measured problem as an action carrying its evidence. It reports what is wrong and why it matters; deciding how to fix it is yours.\n\nGetCited is not authenticated. The request carried no Authorization header, so this server does not know which account you are.\n\nNone of the SEO tools are available until this is fixed. Retrying the same\nrequest will not help, and this server does not use OAuth, so there is no\nsign-in flow to complete.\n\nFix it by giving the MCP client a static header:\n\n Authorization: Bearer <your key>\n\nIn a Claude Code project that means an entry in .mcp.json:\n\n {\n \"mcpServers\": {\n \"getcited\": {\n \"type\": \"http\",\n \"url\": \"https://0.0.0.0:3000/api/mcp\",\n \"headers\": { \"Authorization\": \"Bearer vseo_...\" }\n }\n }\n }\n\nKeys look like vseo_XXXXXXXX_… and are created at https://0.0.0.0:3000/settings/api-keys.\nThe client reads this config at startup, so restart it after editing.\n\nTell the person running you which of these you need; you cannot mint a key yourself.",
"tools": [
{
"description": "Pass `prompts` as an array of objects, not strings: each is { prompt: \"best seo tool for agents\", stage?: \"tofu\" | \"mofu\" | \"bofu\", format?: \"keyword\" | \"conversational\" | \"list\" }, with the projectId from add_project or list_projects. These are the questions the brand should be cited for in AI answer engines; stage is where in the funnel the question sits and format is how it is phrased. Returns `added`; a prompt already tracked is skipped, so calling again is safe, and adding costs no quota. Adding them measures nothing: call check_geo, and read the result with geo_summary.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"prompts": {
"description": "Array of objects, one per prompt: [{ prompt: \"best seo tool for agents\", stage: \"bofu\" }]",
"items": {
"properties": {
"format": {
"description": "How the question is phrased",
"enum": [
"keyword",
"conversational",
"list"
],
"type": "string"
},
"prompt": {
"description": "The question as a visitor would ask it, e.g. \"best seo tool for agents\"",
"maxLength": 500,
"minLength": 3,
"type": "string"
},
"stage": {
"description": "Funnel stage of the question",
"enum": [
"tofu",
"mofu",
"bofu"
],
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
},
"required": [
"projectId",
"prompts"
],
"type": "object"
},
"name": "add_geo_prompts",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"added": {
"description": "Rows inserted; duplicates are skipped",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"added"
],
"type": "object"
}
},
{
"description": "Starts tracking search `terms` for a project and returns `added`, the number of new keywords. Pass terms as an array of plain search phrases (terms: [\"seo tool\", \"rank tracker\"]) with the projectId from add_project or list_projects. Terms are lowercased, and one already tracked is skipped, so calling again is safe. Adding measures no rank: call check_rankings for positions. Search volume and difficulty arrive within about ten minutes, looked up in one request pooled with other keywords, costing one keyword_lookups unit per keyword; read them with list_keywords.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"terms": {
"description": "The search phrases to track, as plain strings, 1-200 per call: [\"seo tool\", \"rank tracker\"]",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"type": "array"
}
},
"required": [
"projectId",
"terms"
],
"type": "object"
},
"name": "add_keywords",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"added": {
"description": "Rows inserted; duplicates are skipped",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"added"
],
"type": "object"
}
},
{
"description": "Register the site you are working in, and get its project id back. Pass the domain you derived from this codebase (git remote, deployed URL, site config). Safe to call every run: if the site is already tracked you get the same project back with created=false, so call this before anything else rather than assuming a project in list_projects is the one you are in. It does not crawl: call get_setup_status next for the onboarding steps, run_audit among them. Returns projectId, the normalized domain, brandName and created. Private, loopback and internal hosts are refused as invalid_request; a plan's site limit answers quota_exceeded with metric sites. Without a plan the first site gets the one free audit, and the answer says what that includes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"brandName": {
"description": "How the brand is written, when it differs from the domain",
"maxLength": 120,
"type": "string"
},
"domain": {
"description": "Domain of the site you are working in, e.g. example.com",
"maxLength": 255,
"minLength": 3,
"type": "string"
}
},
"required": [
"domain"
],
"type": "object"
},
"name": "add_project",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"brandName": {
"type": [
"string",
"null"
]
},
"created": {
"description": "true if this call registered the site, false if it was already tracked",
"type": "boolean"
},
"domain": {
"description": "The normalized domain that is tracked",
"type": "string"
},
"note": {
"description": "Present only on the free preview: what it includes and what it does not",
"type": "string"
},
"plan": {
"const": "none",
"description": "Present only when there is no subscription: this account is on the free preview",
"type": "string"
},
"projectId": {
"description": "Pass this to every other tool",
"type": "string"
}
},
"required": [
"projectId",
"domain",
"brandName",
"created"
],
"type": "object"
}
},
{
"description": "Queues a run of every tracked GEO prompt against each configured AI answer engine and returns status, jobId and the prompt count. The work runs asynchronously in the worker and takes minutes; this returns as soon as it is queued. Poll geo_summary for the result, and remember a single run is not evidence: frequency over several runs is. Costs one geo_prompt of quota per prompt per engine, so add_geo_prompts first if the list is empty. Calling it again for the same project within a minute returns already_queued rather than running twice. If the last run is under 20 hours old it returns fresh and bills nothing: runs on different days are the independent samples geo_summary needs, so read it instead, or pass force: true.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"force": {
"description": "Re-check even though the last check is under 20 hours old. Bills again; leave unset unless a same-day re-check is genuinely needed",
"type": "boolean"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "check_geo",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"hint": {
"description": "Present only with nothing_to_check: the tool to call before checking again",
"type": "string"
},
"jobId": {
"description": "Job id, null when this call was deduplicated into an already-queued run",
"type": [
"string",
"null"
]
},
"lastCheckedAt": {
"description": "ISO time of the project's newest check of this kind, null when never checked",
"type": [
"string",
"null"
]
},
"nextCheckAfter": {
"description": "Present only with fresh: when an unforced check will run again",
"type": "string"
},
"pollWith": {
"const": "geo_summary",
"description": "Call geo_summary once the worker has finished the run",
"type": "string"
},
"prompts": {
"description": "Active GEO prompts the run will ask, once on every configured engine; 0 queues nothing",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"status": {
"description": "queued when this call created the job. already_queued when the same job for this project was enqueued moments ago and this call was deduplicated: the work is coming and nothing extra was billed. nothing_to_check when the project tracks nothing for this run: no job was enqueued, nothing was billed, and hint names the tool to call first. fresh when the last check is under 20 hours old: nothing was enqueued or billed, read the existing result now, and pass force: true only if a re-check today is genuinely needed.",
"enum": [
"queued",
"already_queued",
"nothing_to_check",
"fresh"
],
"type": "string"
}
},
"required": [
"status",
"jobId",
"prompts",
"pollWith"
],
"type": "object"
}
},
{
"description": "Queues a search-position check (top 30 results) for every keyword tracked on this project and returns status, jobId and the keyword count. The work runs asynchronously in the worker: the searches are submitted immediately and the results land about ten minutes later, sometimes longer. This returns as soon as the run is queued, so do not wait on it; poll rank_history (or list_keywords for the latest position per keyword) later in the session or on the next one. Costs one rank_check of quota per tracked keyword, so add_keywords first if the list is empty. Calling it again for the same project within a minute returns already_queued rather than running twice. If the last check is under 20 hours old it returns fresh and bills nothing: positions do not move within a day, so read list_keywords instead, or pass force: true.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"force": {
"description": "Re-check even though the last check is under 20 hours old. Bills again; leave unset unless a same-day re-check is genuinely needed",
"type": "boolean"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "check_rankings",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"hint": {
"description": "Present only with nothing_to_check: the tool to call before checking again",
"type": "string"
},
"jobId": {
"description": "Job id, null when this call was deduplicated into an already-queued run",
"type": [
"string",
"null"
]
},
"keywords": {
"description": "Tracked keywords the run will check, one rank_check of quota each; 0 queues nothing",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"lastCheckedAt": {
"description": "ISO time of the project's newest check of this kind, null when never checked",
"type": [
"string",
"null"
]
},
"nextCheckAfter": {
"description": "Present only with fresh: when an unforced check will run again",
"type": "string"
},
"pollWith": {
"const": "rank_history",
"description": "Call rank_history once the worker has finished the run",
"type": "string"
},
"status": {
"description": "queued when this call created the job. already_queued when the same job for this project was enqueued moments ago and this call was deduplicated: the work is coming and nothing extra was billed. nothing_to_check when the project tracks nothing for this run: no job was enqueued, nothing was billed, and hint names the tool to call first. fresh when the last check is under 20 hours old: nothing was enqueued or billed, read the existing result now, and pass force: true only if a re-check today is genuinely needed.",
"enum": [
"queued",
"already_queued",
"nothing_to_check",
"fresh"
],
"type": "string"
}
},
"required": [
"status",
"jobId",
"keywords",
"pollWith"
],
"type": "object"
}
},
{
"description": "Marks an open action as claimed by this API key, so other agents working the same queue skip it, and returns the updated action. Only an open action can be claimed: one already claimed (by any agent, this one included), done or dismissed answers not_found, so a repeat call changes nothing. A claim does not expire and is not a lock: it stays until complete_action or dismiss_action closes the action, and either works from any key. Claiming is optional; complete_action also accepts an open action. Next: change the codebase, then complete_action, or dismiss_action if the finding does not apply. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actionId": {
"description": "Action id (a UUID) from the id field of a list_actions row, an exampleActionIds entry of a group, or get_next_work",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId",
"actionId"
],
"type": "object"
},
"name": "claim_action",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"alsoClosed": {
"description": "Further findings closed by this call's actionIds, beyond the one reported here",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"claimedAt": {
"anyOf": [
{
"description": "When the action was claimed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"claimedByApiKeyId": {
"type": [
"string",
"null"
]
},
"commitSha": {
"description": "The commit the agent reported when completing this, if it reported one",
"type": [
"string",
"null"
]
},
"createdAt": {
"description": "When the action was filed as an ISO 8601 timestamp",
"type": "string"
},
"doneAt": {
"anyOf": [
{
"description": "When the action was closed, completed or dismissed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"notFound": {
"description": "actionIds that named no open finding of this project: already closed, or not ours",
"items": {
"type": "string"
},
"type": "array"
},
"note": {
"description": "Why the agent closed this: required on dismissal, optional on completion",
"type": [
"string",
"null"
]
},
"payload": {
"additionalProperties": {},
"description": "Evidence; shape varies by type",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"priority": {
"description": "1 is most urgent, 5 least",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"projectId": {
"type": "string"
},
"rationale": {
"description": "What was measured and why it matters",
"type": "string"
},
"refreshId": {
"description": "The action-list refresh that filed this action, if any",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"targetUrl": {
"description": "The affected URL, if the problem is page-level",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"updatedAt": {
"description": "When the action last changed as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"id",
"projectId",
"refreshId",
"type",
"priority",
"title",
"rationale",
"targetUrl",
"payload",
"status",
"claimedByApiKeyId",
"claimedAt",
"doneAt",
"note",
"commitSha",
"createdAt",
"updatedAt"
],
"type": "object"
}
},
{
"description": "Mark a problem done after you have addressed it in the codebase. Pass `note` to record what you changed; the owner reads it to tell a real fix from a box ticked. Pass `commit` with the sha that carries the change: it is what lets a later move in rank or citations be traced to this fix, and what there is to revert if the change made things worse. When one change closed several findings — an edit to a shared layout usually does — pass their ids as `actionIds` so they close together under that one commit, rather than being recorded as unrelated fixes; get_next_work gives you the set as `sameFix.actionIds`. Accepts an open or claimed action and returns it with status done; one already done or dismissed answers not_found, so a repeat call changes nothing. If a later audit still measures the problem, a new action is filed. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actionId": {
"description": "Action id (a UUID) from the id field of a list_actions row, an exampleActionIds entry of a group, or get_next_work",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"actionIds": {
"description": "Further findings the same change closed. Only include what this commit actually fixed; ids that are not open findings of this project come back in notFound.",
"items": {
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"commit": {
"description": "The commit that carries the change, so the fix can be traced and reverted.",
"pattern": "^[0-9a-f]{7,64}$",
"type": "string"
},
"note": {
"description": "What you changed, in one line. Shown to the owner alongside the finding.",
"maxLength": 500,
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId",
"actionId"
],
"type": "object"
},
"name": "complete_action",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"alsoClosed": {
"description": "Further findings closed by this call's actionIds, beyond the one reported here",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"claimedAt": {
"anyOf": [
{
"description": "When the action was claimed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"claimedByApiKeyId": {
"type": [
"string",
"null"
]
},
"commitSha": {
"description": "The commit the agent reported when completing this, if it reported one",
"type": [
"string",
"null"
]
},
"createdAt": {
"description": "When the action was filed as an ISO 8601 timestamp",
"type": "string"
},
"doneAt": {
"anyOf": [
{
"description": "When the action was closed, completed or dismissed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"notFound": {
"description": "actionIds that named no open finding of this project: already closed, or not ours",
"items": {
"type": "string"
},
"type": "array"
},
"note": {
"description": "Why the agent closed this: required on dismissal, optional on completion",
"type": [
"string",
"null"
]
},
"payload": {
"additionalProperties": {},
"description": "Evidence; shape varies by type",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"priority": {
"description": "1 is most urgent, 5 least",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"projectId": {
"type": "string"
},
"rationale": {
"description": "What was measured and why it matters",
"type": "string"
},
"refreshId": {
"description": "The action-list refresh that filed this action, if any",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"targetUrl": {
"description": "The affected URL, if the problem is page-level",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"updatedAt": {
"description": "When the action last changed as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"id",
"projectId",
"refreshId",
"type",
"priority",
"title",
"rationale",
"targetUrl",
"payload",
"status",
"claimedByApiKeyId",
"claimedAt",
"doneAt",
"note",
"commitSha",
"createdAt",
"updatedAt"
],
"type": "object"
}
},
{
"description": "Drop a problem you are deliberately not acting on, and say why. `reason` is required and is shown to the site owner: explain what makes this finding wrong or inapplicable here, in a sentence they could disagree with. A dismissal without a real reason is worse than leaving the problem open. Accepts an open or claimed action and returns it with status dismissed; later refreshes do not file the same finding again. One already done or dismissed answers not_found. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actionId": {
"description": "Action id (a UUID) from the id field of a list_actions row, an exampleActionIds entry of a group, or get_next_work",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"reason": {
"description": "Why this finding does not apply to this site, in your own words. Shown to the owner, so a bare 'not applicable' is not useful.",
"maxLength": 500,
"minLength": 15,
"type": "string"
}
},
"required": [
"projectId",
"actionId",
"reason"
],
"type": "object"
},
"name": "dismiss_action",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"alsoClosed": {
"description": "Further findings closed by this call's actionIds, beyond the one reported here",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"claimedAt": {
"anyOf": [
{
"description": "When the action was claimed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"claimedByApiKeyId": {
"type": [
"string",
"null"
]
},
"commitSha": {
"description": "The commit the agent reported when completing this, if it reported one",
"type": [
"string",
"null"
]
},
"createdAt": {
"description": "When the action was filed as an ISO 8601 timestamp",
"type": "string"
},
"doneAt": {
"anyOf": [
{
"description": "When the action was closed, completed or dismissed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"notFound": {
"description": "actionIds that named no open finding of this project: already closed, or not ours",
"items": {
"type": "string"
},
"type": "array"
},
"note": {
"description": "Why the agent closed this: required on dismissal, optional on completion",
"type": [
"string",
"null"
]
},
"payload": {
"additionalProperties": {},
"description": "Evidence; shape varies by type",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"priority": {
"description": "1 is most urgent, 5 least",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"projectId": {
"type": "string"
},
"rationale": {
"description": "What was measured and why it matters",
"type": "string"
},
"refreshId": {
"description": "The action-list refresh that filed this action, if any",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"targetUrl": {
"description": "The affected URL, if the problem is page-level",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"updatedAt": {
"description": "When the action last changed as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"id",
"projectId",
"refreshId",
"type",
"priority",
"title",
"rationale",
"targetUrl",
"payload",
"status",
"claimedByApiKeyId",
"claimedAt",
"doneAt",
"note",
"commitSha",
"createdAt",
"updatedAt"
],
"type": "object"
}
},
{
"description": "Returns how often the site appears in AI answers: one row per tracked prompt, and within it one entry per engine with runs, citedRuns, mentionedRuns, citedRate and mentionedRate, plus the competitor domains cited instead, over the last `days`. Read-only. Frequency over the window is the metric: there is never a per-run rank, and engines are never blended. An empty array means no prompts (add_geo_prompts); runs of 0 mean nothing measured in the window yet (check_geo). Fewer than three runs on an engine is too few to call a gap. Pass view: \"full\" for the competitor URLs and the fan-out queries the engine issued behind each prompt; that payload is per prompt per engine and grows past what fits in a context window, which is why it is not the default.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"description": "Window in days, counted back from now, 1-365; default 30, e.g. 90 for a quarter",
"maximum": 365,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"view": {
"description": "brief (the default) is the rates and the top competitor domains. full adds the competitor URLs and fan-out queries per engine, which is far larger.",
"enum": [
"brief",
"full"
],
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "geo_summary",
"outputSchema": null
},
{
"description": "Returns one action in full: type, priority, title, rationale (what was measured and why it matters), targetUrl, status, the claim and closing fields, and `payload`, the evidence (the audit rule id and its measured values, such as the current title and its length; the shape varies by type). Read-only. Use it on the one action you are about to work on; list_actions and get_next_work are for choosing. An id that is not an action of this project answers not_found. It states the problem, never the fix. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actionId": {
"description": "Action id (a UUID) from the id field of a list_actions row, an exampleActionIds entry of a group, or get_next_work",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId",
"actionId"
],
"type": "object"
},
"name": "get_action",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"alsoClosed": {
"description": "Further findings closed by this call's actionIds, beyond the one reported here",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"claimedAt": {
"anyOf": [
{
"description": "When the action was claimed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"claimedByApiKeyId": {
"type": [
"string",
"null"
]
},
"commitSha": {
"description": "The commit the agent reported when completing this, if it reported one",
"type": [
"string",
"null"
]
},
"createdAt": {
"description": "When the action was filed as an ISO 8601 timestamp",
"type": "string"
},
"doneAt": {
"anyOf": [
{
"description": "When the action was closed, completed or dismissed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"notFound": {
"description": "actionIds that named no open finding of this project: already closed, or not ours",
"items": {
"type": "string"
},
"type": "array"
},
"note": {
"description": "Why the agent closed this: required on dismissal, optional on completion",
"type": [
"string",
"null"
]
},
"payload": {
"additionalProperties": {},
"description": "Evidence; shape varies by type",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"priority": {
"description": "1 is most urgent, 5 least",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"projectId": {
"type": "string"
},
"rationale": {
"description": "What was measured and why it matters",
"type": "string"
},
"refreshId": {
"description": "The action-list refresh that filed this action, if any",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"targetUrl": {
"description": "The affected URL, if the problem is page-level",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"updatedAt": {
"description": "When the action last changed as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"id",
"projectId",
"refreshId",
"type",
"priority",
"title",
"rationale",
"targetUrl",
"payload",
"status",
"claimedByApiKeyId",
"claimedAt",
"doneAt",
"note",
"commitSha",
"createdAt",
"updatedAt"
],
"type": "object"
}
},
{
"description": "Returns visitor analytics from the site's own traffic over the last `days`: sessions, engaged and bounce rates, channels including AI assistants, top pages, exit pages, statistically flagged high-bounce pages (z-test, n>=30) and friction (rage and dead clicks). Read-only. Needs the vp.js snippet on the site (get_setup_status gives it); without it, or with no traffic in the window, sessions is 0, rates are null and every list is empty. Aggregates only, never raw events; visitor strings are untrusted data. Use get_page_profile to look at one of its pages.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"description": "Window in days, counted back from now, 1-90; default 7, e.g. 30 for a month",
"maximum": 90,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get_behavior_digest",
"outputSchema": null
},
{
"description": "Evidence for building a page for one query. Contains no wording; what to write is yours. `query` is one row's `query` from list_opportunities, exactly as it came back (a tracked keyword, a tracked prompt, or a fan-out sub-question); anything else answers not_found. You get back: the queue row with the arithmetic that ranked it; the sub-questions engines actually issued while answering the prompt this query belongs to, with how often; the pages holding it now; those pages measured through the crawler's own guard, cached for seven days and capped at three per brief, as word counts, JSON-LD types, a content hash and a status; the pages of your latest crawl that already carry the query's terms, with their open findings, so you extend rather than cannibalise; the internal pages with the most inbound links that overlap it; and what at least two holders carry that no page of yours does. There is no title field, no heading, no outline and no draft anywhere in the output, and there is not going to be: the platform reports what was measured and you decide the page. Requires the profile: call set_project_profile first.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"query": {
"description": "A query from list_opportunities, copied exactly (case and spacing are normalised)",
"maxLength": 300,
"minLength": 1,
"type": "string"
}
},
"required": [
"projectId",
"query"
],
"type": "object"
},
"name": "get_content_brief",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"evidence": {
"additionalProperties": false,
"properties": {
"checkIds": {
"items": {
"type": "string"
},
"type": "array"
},
"crawlId": {
"type": [
"string",
"null"
]
},
"engines": {
"items": {
"type": "string"
},
"type": "array"
},
"holderFetchedAt": {
"items": {
"description": "When a holder page was measured as an ISO 8601 timestamp",
"type": "string"
},
"type": "array"
},
"keywordId": {
"type": [
"string",
"null"
]
},
"promptId": {
"type": [
"string",
"null"
]
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"windowDays": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"crawlId",
"checkIds",
"runs",
"windowDays",
"engines",
"keywordId",
"promptId",
"holderFetchedAt"
],
"type": "object"
},
"existingPages": {
"description": "Pages of the latest crawl that already speak to this query",
"items": {
"additionalProperties": false,
"properties": {
"matchedIn": {
"description": "Where the query's head terms were found",
"enum": [
"title",
"h1"
],
"type": "string"
},
"openIssues": {
"description": "Rule ids still open on this page",
"items": {
"type": "string"
},
"type": "array"
},
"schemaTypes": {
"items": {
"type": "string"
},
"type": "array"
},
"url": {
"type": "string"
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"url",
"wordCount",
"matchedIn",
"schemaTypes",
"openIssues"
],
"type": "object"
},
"type": "array"
},
"holderPages": {
"description": "Those pages as measured through the crawler's own guard, cached for 7 days, at most three per brief. Counts, types, a hash and a status; never their text.",
"items": {
"additionalProperties": false,
"properties": {
"contentHash": {
"description": "sha256 of the page's visible text",
"type": [
"string",
"null"
]
},
"error": {
"description": "Why no measurement was taken, when none was",
"type": [
"string",
"null"
]
},
"fetchedAt": {
"description": "When this page was last measured as an ISO 8601 timestamp",
"type": "string"
},
"schemaTypes": {
"description": "JSON-LD @type values found on the page",
"items": {
"type": "string"
},
"type": "array"
},
"statusCode": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
],
"description": "HTTP status; null when nothing answered"
},
"url": {
"type": "string"
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"url",
"statusCode",
"wordCount",
"schemaTypes",
"contentHash",
"fetchedAt",
"error"
],
"type": "object"
},
"type": "array"
},
"holders": {
"description": "The pages holding this query now",
"items": {
"additionalProperties": false,
"properties": {
"count": {
"description": "Checks or runs in the window in which it held the query",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"engine": {
"description": "Engine that cited it; null for a keyword",
"type": [
"string",
"null"
]
},
"host": {
"type": "string"
},
"position": {
"description": "SERP position; null for an AI answer",
"type": [
"number",
"null"
]
},
"url": {
"type": "string"
}
},
"required": [
"url",
"host",
"position",
"engine",
"count"
],
"type": "object"
},
"type": "array"
},
"linkFrom": {
"description": "The site's own pages with the most inbound internal links that overlap the query",
"items": {
"additionalProperties": false,
"properties": {
"inboundLinks": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"url": {
"type": "string"
}
},
"required": [
"url",
"inboundLinks"
],
"type": "object"
},
"type": "array"
},
"missing": {
"additionalProperties": false,
"properties": {
"page": {
"description": "True when nothing measured covers this query at all",
"type": "boolean"
},
"schemaTypes": {
"description": "Types at least two holders carry and no page of the site does",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"schemaTypes",
"page"
],
"type": "object"
},
"opportunity": {
"additionalProperties": false,
"description": "The queue row for this query",
"properties": {
"coverage": {
"additionalProperties": false,
"description": "What the site already has for this query, from the latest finished crawl",
"properties": {
"pages": {
"items": {
"additionalProperties": false,
"properties": {
"matchedIn": {
"description": "Where the head terms were found, or that the page ranks for the query",
"enum": [
"title",
"h1",
"ranking"
],
"type": "string"
},
"url": {
"type": "string"
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"url",
"wordCount",
"matchedIn"
],
"type": "object"
},
"type": "array"
},
"state": {
"description": "held: a page of the site already ranks or is cited for it. partial: a page carries the query's head terms. none: nothing measured covers it.",
"enum": [
"none",
"partial",
"held"
],
"type": "string"
}
},
"required": [
"state",
"pages"
],
"type": "object"
},
"demand": {
"description": "Comparable within a kind only; demandBasis says what it counts",
"type": "number"
},
"demandBasis": {
"type": "string"
},
"evidence": {
"additionalProperties": false,
"properties": {
"checkIds": {
"description": "The rank_check or geo_check rows the counts came from",
"items": {
"type": "string"
},
"type": "array"
},
"crawlId": {
"type": [
"string",
"null"
]
},
"engines": {
"items": {
"type": "string"
},
"type": "array"
},
"keywordId": {
"type": [
"string",
"null"
]
},
"promptId": {
"type": [
"string",
"null"
]
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"windowDays": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"checkIds",
"crawlId",
"runs",
"windowDays",
"engines",
"keywordId",
"promptId"
],
"type": "object"
},
"gap": {
"description": "Computed by gapFormula; the sort key",
"type": "number"
},
"gapFormula": {
"description": "The exact arithmetic behind gap",
"type": "string"
},
"holder": {
"description": "The pages measured holding this query, strongest first",
"items": {
"additionalProperties": false,
"properties": {
"count": {
"description": "Checks or runs in the window in which it held the query",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"engine": {
"description": "Engine that cited it; null for a keyword",
"type": [
"string",
"null"
]
},
"host": {
"type": "string"
},
"position": {
"description": "SERP position; null for an AI answer",
"type": [
"number",
"null"
]
},
"url": {
"type": "string"
}
},
"required": [
"url",
"host",
"position",
"engine",
"count"
],
"type": "object"
},
"type": "array"
},
"holderStrength": {
"description": "The share of checks or runs the strongest holder held",
"type": "number"
},
"kind": {
"description": "keyword: a tracked search term. prompt: a tracked question asked of AI answer engines. fanout: a sub-question an engine issued while answering a tracked prompt.",
"enum": [
"keyword",
"prompt",
"fanout"
],
"type": "string"
},
"ownPosition": {
"description": "The site's best search position over the window. Always null for prompt and fanout rows: an AI answer has no rank, only a frequency, which is ownShare.",
"type": [
"number",
"null"
]
},
"ownShare": {
"description": "The share of the query the site already holds, per gapFormula",
"type": "number"
},
"query": {
"description": "The keyword, prompt or sub-question, as it was measured",
"type": "string"
}
},
"required": [
"query",
"kind",
"demand",
"demandBasis",
"holder",
"ownPosition",
"ownShare",
"holderStrength",
"coverage",
"gap",
"evidence",
"gapFormula"
],
"type": "object"
},
"query": {
"description": "The tracked query this brief is about, as it is stored",
"type": "string"
},
"questionsToAnswer": {
"description": "Sub-questions the engines actually issued while answering the prompt(s) this query belongs to, seen at least twice. Measured, not generated.",
"items": {
"additionalProperties": false,
"properties": {
"count": {
"description": "Sightings across those engines",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"engines": {
"items": {
"type": "string"
},
"type": "array"
},
"query": {
"description": "A sub-question an engine issued, as it issued it",
"type": "string"
}
},
"required": [
"query",
"engines",
"count"
],
"type": "object"
},
"type": "array"
},
"wordCountBand": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"max": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"min": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"min",
"max"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Min and max word count across the measured holder pages"
}
},
"required": [
"query",
"opportunity",
"questionsToAnswer",
"holders",
"holderPages",
"wordCountBand",
"existingPages",
"linkFrom",
"missing",
"evidence"
],
"type": "object"
}
},
{
"description": "The one call an unattended agent needs: the findings worth acting on now, most important first, or an instruction to stand by until a given time. Ordering is severity weighted by the page's own measured traffic. Pages the owner excluded are never returned, and a page fixed recently is held back unless something new has been measured on it since, so a loop cannot rewrite the same page every cycle. `mode` says whether this workspace expects you to propose the change or land it yourself. Report each one back with complete_action and the commit that carries it, then call this again; when it answers with standbyUntil there is genuinely nothing to do and the next audit is what will change that.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "How many to take on now. Defaults to 5.",
"maximum": 20,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get_next_work",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"items": {
"description": "What to work on now, most important first, one entry per kind of finding rather than one per finding. Empty when there is nothing to do.",
"items": {
"additionalProperties": false,
"properties": {
"action": {
"additionalProperties": false,
"properties": {
"claimedAt": {
"anyOf": [
{
"description": "When the action was claimed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"claimedByApiKeyId": {
"type": [
"string",
"null"
]
},
"commitSha": {
"description": "The commit the agent reported when completing this, if it reported one",
"type": [
"string",
"null"
]
},
"createdAt": {
"description": "When the action was filed as an ISO 8601 timestamp",
"type": "string"
},
"doneAt": {
"anyOf": [
{
"description": "When the action was closed, completed or dismissed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"note": {
"description": "Why the agent closed this: required on dismissal, optional on completion",
"type": [
"string",
"null"
]
},
"payload": {
"additionalProperties": {},
"description": "Evidence; shape varies by type",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"priority": {
"description": "1 is most urgent, 5 least",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"projectId": {
"type": "string"
},
"rationale": {
"description": "What was measured and why it matters",
"type": "string"
},
"refreshId": {
"description": "The action-list refresh that filed this action, if any",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"targetUrl": {
"description": "The affected URL, if the problem is page-level",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"updatedAt": {
"description": "When the action last changed as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"id",
"projectId",
"refreshId",
"type",
"priority",
"title",
"rationale",
"targetUrl",
"payload",
"status",
"claimedByApiKeyId",
"claimedAt",
"doneAt",
"note",
"commitSha",
"createdAt",
"updatedAt"
],
"type": "object"
},
"importance": {
"description": "Why this is in front: severity weighted by the page's measured traffic",
"type": "number"
},
"sameFix": {
"additionalProperties": false,
"description": "The other open findings that are the same piece of work. One entry can stand for many pages.",
"properties": {
"actionIds": {
"description": "Pass to complete_action as actionIds to close the whole set with one note and one commit.",
"items": {
"type": "string"
},
"type": "array"
},
"count": {
"description": "Open findings of this kind, this one included: the blast radius",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"fixScope": {
"description": "How findings of this rule usually go: page is writing that belongs to one page, template is markup a shared layout emits, site is about the origin. It describes the rule, not your repository — you are the one who knows.",
"enum": [
"page",
"template",
"site"
],
"type": "string"
},
"key": {
"description": "The audit rule, or the action type when there is none",
"type": "string"
},
"morePages": {
"description": "Pages beyond those listed",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"pages": {
"description": "Their pages, this one first",
"items": {
"type": "string"
},
"type": "array"
},
"ruleId": {
"type": [
"string",
"null"
]
},
"samePages": {
"description": "Other kinds of finding standing on exactly the same pages. They are separate edits, so they are separate entries, but they are one visit to each page rather than three.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"key",
"ruleId",
"fixScope",
"count",
"pages",
"morePages",
"actionIds",
"samePages"
],
"type": "object"
}
},
"required": [
"importance",
"action",
"sameFix"
],
"type": "object"
},
"type": "array"
},
"mode": {
"description": "What this workspace expects you to do with a fix: propose leaves the change for a human to accept, commit means land it yourself.",
"enum": [
"propose",
"commit"
],
"type": "string"
},
"quotaWarnings": {
"description": "Metrics this workspace will spend before the month resets, at the current rate. Nothing breaks when one runs out: the scheduled audits stop until it resets. Tell the owner rather than working around it.",
"items": {
"additionalProperties": false,
"properties": {
"daysEarly": {
"type": "number"
},
"exhaustsOn": {
"type": [
"string",
"null"
]
},
"limit": {
"type": "number"
},
"metric": {
"type": "string"
},
"used": {
"type": "number"
}
},
"required": [
"metric",
"limit",
"used",
"exhaustsOn",
"daysEarly"
],
"type": "object"
},
"type": "array"
},
"remaining": {
"description": "Open findings not covered by these entries; call again when done with them",
"type": "number"
},
"standbyUntil": {
"description": "ISO time to sleep until, set only when there is nothing to do. The next scheduled audit is what produces new findings.",
"type": [
"string",
"null"
]
},
"withheldByCooldown": {
"description": "Findings held back because their page was fixed recently and nothing new has been measured on it since",
"type": "number"
}
},
"required": [
"mode",
"items",
"remaining",
"withheldByCooldown",
"standbyUntil",
"quotaWarnings"
],
"type": "object"
}
},
{
"description": "Every measurement that touched one page, newest first, so a change can be matched to its effect. `url` is the full url of a page on the tracked site (https://example.com/guide); `days` defaults to 90. Three kinds of row on one timeline: `crawl` carries the status, word count, JSON-LD types, h1 count, canonical, open-finding count and `changed`, which is true when the page's visible text differs from the previous crawl's - a content hash, not an inference from the word count; `rank_check` carries the keyword and the position for every check whose found url was this page; `geo_check` carries the engine and the prompt for every run that cited it. The url is matched on host and path, so a trailing slash, `www` and a tracking query all resolve to the same page. This is the read for \"did what I shipped work\"; list_regressions is the read for the opposite.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"description": "Window in days, default 90",
"maximum": 365,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"url": {
"description": "Full url of one page, e.g. https://example.com/guide",
"format": "uri",
"maxLength": 2048,
"type": "string"
}
},
"required": [
"projectId",
"url"
],
"type": "object"
},
"name": "get_page_history",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"days": {
"description": "Window the timeline covers",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"events": {
"description": "One row per measurement, newest first",
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"at": {
"description": "When the crawl finished as an ISO 8601 timestamp",
"type": "string"
},
"canonical": {
"type": [
"string",
"null"
]
},
"changed": {
"description": "Whether the visible text differs from the previous crawl in the window. False for the first crawl, and for a page crawled before the hash was recorded.",
"type": "boolean"
},
"contentHash": {
"description": "sha256 of the page's visible text",
"type": [
"string",
"null"
]
},
"crawlId": {
"type": "string"
},
"h1Count": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"issueCount": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"kind": {
"const": "crawl",
"type": "string"
},
"schemaTypes": {
"items": {
"type": "string"
},
"type": "array"
},
"statusCode": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"kind",
"at",
"crawlId",
"statusCode",
"wordCount",
"contentHash",
"schemaTypes",
"h1Count",
"canonical",
"issueCount",
"changed"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"at": {
"description": "When the position was sampled as an ISO 8601 timestamp",
"type": "string"
},
"keywordId": {
"type": "string"
},
"kind": {
"const": "rank_check",
"type": "string"
},
"position": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"term": {
"description": "The tracked keyword, as it is stored",
"type": "string"
}
},
"required": [
"kind",
"at",
"keywordId",
"term",
"position"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"at": {
"description": "When the engine was asked as an ISO 8601 timestamp",
"type": "string"
},
"engine": {
"type": "string"
},
"kind": {
"const": "geo_check",
"type": "string"
},
"prompt": {
"description": "The tracked prompt, as it is stored",
"type": "string"
},
"promptId": {
"type": "string"
}
},
"required": [
"kind",
"at",
"engine",
"promptId",
"prompt"
],
"type": "object"
}
]
},
"type": "array"
},
"url": {
"description": "The page the timeline is for, as it was asked for",
"type": "string"
}
},
"required": [
"url",
"days",
"events"
],
"type": "object"
}
},
{
"description": "Returns the visitor behaviour of one page over the last `days`: pageviews, entries, bounce rate, exits, 50% and 100% scroll rates, average active time, rage and dead clicks, and vsSite, a two-proportion z-test of its bounce rate against the rest of the site (only meaningful with at least 30 entries on each side). Read-only. Needs the vp.js snippet; take the path from get_behavior_digest's topPages. A path with no recorded traffic returns zero counts and null rates, not an error.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"description": "Window in days, counted back from now, 1-90; default 7",
"maximum": 90,
"minimum": 1,
"type": "integer"
},
"path": {
"description": "Page path exactly as recorded, e.g. \"/pricing\": no scheme, host or query string (query strings are dropped when visits are recorded). \"/pricing\" and \"/pricing/\" are different pages, so copy the path from get_behavior_digest",
"maxLength": 200,
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId",
"path"
],
"type": "object"
},
"name": "get_page_profile",
"outputSchema": null
},
{
"description": "The stored profile for a project: the three texts as they were written and where they came from, the market country and language, the tracked competitors, the declared techStack next to the detectedStack the latest crawl saw, whether it is complete, and `missing`, which names the fields that are still empty. Call it before list_opportunities to see whether set_project_profile is needed.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get_project_profile",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"audience": {
"description": "Who buys it",
"type": [
"string",
"null"
]
},
"competitors": {
"description": "Tracked competitor hostnames, at most 5",
"items": {
"type": "string"
},
"type": "array"
},
"completed": {
"description": "true once productSummary, valueProposition and audience are all filled in",
"type": "boolean"
},
"completedAt": {
"anyOf": [
{
"description": "When the profile was first complete as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"detectedStack": {
"description": "What the latest crawl recognised from the HTML, or null when nothing matched",
"type": [
"string",
"null"
]
},
"marketCountry": {
"description": "Two-letter country the checks are run for, e.g. us",
"type": "string"
},
"marketLanguage": {
"description": "Two-letter language, e.g. en",
"type": "string"
},
"missing": {
"description": "Profile fields still empty; the strategy tools refuse while this is non-empty",
"items": {
"type": "string"
},
"type": "array"
},
"productSummary": {
"description": "What the product is, as the customer wrote it",
"type": [
"string",
"null"
]
},
"profileSource": {
"description": "Where the texts came from, when the owner did not write them",
"type": [
"string",
"null"
]
},
"projectId": {
"type": "string"
},
"techStack": {
"description": "What the site is built with, as declared; the audit prefers it over detectedStack",
"type": [
"string",
"null"
]
},
"valueProposition": {
"description": "Why someone picks it",
"type": [
"string",
"null"
]
}
},
"required": [
"projectId",
"productSummary",
"valueProposition",
"audience",
"marketCountry",
"marketLanguage",
"competitors",
"techStack",
"detectedStack",
"profileSource",
"completed",
"completedAt",
"missing"
],
"type": "object"
}
},
{
"description": "The onboarding as a checklist for one project: each step (profile, tech stack, competitors, first audit, keywords, rank check, GEO prompts, GEO check, visitor snippet) with whether it is done, what it needs and the tool that completes it, plus `next`, the first step still open. Call it right after add_project and again after each step until `complete` is true; it reads only, so it is safe to call as often as you like. An unknown projectId answers not_found.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get_setup_status",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"complete": {
"type": "boolean"
},
"domain": {
"type": "string"
},
"next": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"detail": {
"type": "string"
},
"done": {
"type": "boolean"
},
"step": {
"type": "string"
},
"tool": {
"description": "The tool that completes it; null when it happens outside MCP",
"type": [
"string",
"null"
]
}
},
"required": [
"step",
"done",
"tool",
"detail"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The first step still open; call its tool"
},
"plan": {
"description": "The workspace plan; \"none\" is the free preview, where only run_audit runs",
"type": "string"
},
"projectId": {
"type": "string"
},
"steps": {
"items": {
"additionalProperties": false,
"properties": {
"detail": {
"type": "string"
},
"done": {
"type": "boolean"
},
"step": {
"type": "string"
},
"tool": {
"description": "The tool that completes it; null when it happens outside MCP",
"type": [
"string",
"null"
]
}
},
"required": [
"step",
"done",
"tool",
"detail"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"projectId",
"domain",
"plan",
"complete",
"next",
"steps"
],
"type": "object"
}
},
{
"description": "Returns the project's current state: the latest crawl (status, pages crawled, when), issue counts by severity and by rule, the open action count and the scores, where a dimension with no data yet is null rather than 0. Read-only. Call it after run_audit to see whether the crawl finished, and before list_actions for the overview. With no crawl yet latestCrawl is null and the counts are 0: call run_audit. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan. There the answer also carries freeAudit: the audit's outcome and a next line naming the tools that reach its findings; until the free audit has finished it is the preview instead (preview=true, the state, and freeAudit.next).",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get_site_health",
"outputSchema": null
},
{
"description": "This server is not authenticated, so none of its SEO tools will answer. Call this for the exact steps to fix it. Retrying other tools will not help.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "how_to_authenticate",
"outputSchema": null
},
{
"description": "Returns the prioritized problems filed for a project, most urgent first; priority 1 is most urgent, 5 least. Read-only. Defaults to open ones. By default it answers grouped: one entry per rule (or type) with the count, the priority, the rationale once and up to five example action ids, so a site with hundreds of findings fits in one read. Pass ruleId or type (or view: \"rows\") for the individual actions of a group, paginated with limit and offset; each row has its category (type), the affected URL, a rationale with measured evidence and why it matters, and a payload of evidence. verbose adds bookkeeping fields (run id, claiming key, timestamps). An empty answer for status open means nothing is filed: run run_audit (or refresh_actions after new rank or GEO data). Use get_action for one row in full, get_next_work to be told what to take next. Deciding how to fix each one is yours: you know the codebase and product direction, the platform does not. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Rows per page, default 50",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"offset": {
"description": "Rows to skip, from nextOffset",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"ruleId": {
"description": "Only actions filed from this audit rule, e.g. missing_title (a group's key)",
"maxLength": 64,
"type": "string"
},
"status": {
"description": "Which actions to return; default open. open: not yet taken; claimed: taken by an agent with claim_action; done: closed with complete_action; dismissed: closed with dismiss_action and a reason",
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"type": {
"description": "Only actions of this category",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"verbose": {
"description": "Include bookkeeping fields on each row; default false",
"type": "boolean"
},
"view": {
"description": "grouped (default) or rows; rows is the default when ruleId or type is given",
"enum": [
"grouped",
"rows"
],
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "list_actions",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"actions": {
"description": "The rows view, one page",
"items": {
"additionalProperties": false,
"properties": {
"claimedAt": {
"anyOf": [
{
"description": "When the action was claimed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"claimedByApiKeyId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"description": "When the action was filed as an ISO 8601 timestamp",
"type": "string"
},
"doneAt": {
"anyOf": [
{
"description": "When the action was closed, completed or dismissed as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"lastSeenAt": {
"description": "When a run last measured this problem; its rationale and payload are from that run as an ISO 8601 timestamp",
"type": "string"
},
"note": {
"description": "Why the agent closed this: required on dismissal, optional on completion",
"type": [
"string",
"null"
]
},
"payload": {
"additionalProperties": {},
"description": "Evidence; shape varies by type",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"priority": {
"description": "1 is most urgent, 5 least",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"projectId": {
"type": "string"
},
"rationale": {
"description": "What was measured and why it matters",
"type": "string"
},
"refreshId": {
"description": "The action-list refresh that filed this action, if any",
"type": [
"string",
"null"
]
},
"ruleId": {
"description": "The audit rule that filed it, when one did",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"targetUrl": {
"description": "The affected URL, if the problem is page-level",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
},
"updatedAt": {
"description": "When the action last changed as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"id",
"type",
"ruleId",
"priority",
"title",
"rationale",
"targetUrl",
"payload",
"status",
"note",
"lastSeenAt"
],
"type": "object"
},
"type": "array"
},
"groups": {
"description": "The grouped view",
"items": {
"additionalProperties": false,
"properties": {
"count": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"examples": {
"items": {
"additionalProperties": false,
"properties": {
"evidence": {
"additionalProperties": {
"type": [
"number",
"boolean"
]
},
"description": "This example's own measurements",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"id": {
"type": "string"
},
"targetUrl": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"targetUrl",
"evidence"
],
"type": "object"
},
"type": "array"
},
"key": {
"description": "Pass as ruleId (or, when ruleId is null, as type) for the rows",
"type": "string"
},
"measured": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"max": {
"type": "number"
},
"min": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"type": "object"
},
"description": "Each numeric measurement across the group, as the range it spans",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"moreNotShown": {
"description": "Items in the group beyond the examples",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"priority": {
"description": "The group's most urgent priority; 1 is most urgent",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"rationale": {
"description": "The first item's rationale; the others differ in their numbers",
"type": "string"
},
"ruleId": {
"type": [
"string",
"null"
]
},
"type": {
"description": "Category of problem",
"enum": [
"fix_title",
"fix_meta_description",
"fix_heading",
"fix_broken_links",
"add_canonical",
"add_structured_data",
"improve_content",
"create_content",
"geo_gap",
"allow_ai_crawler",
"ssr_content",
"refresh_content",
"add_evidence",
"restructure_sections",
"cover_fanout_query",
"third_party_placement",
"claim_review_profile",
"fix_intent_mismatch",
"improve_landing_page",
"fix_friction",
"review_indexing",
"improve_speed",
"add_internal_links",
"add_sitemap",
"review_crawler_access",
"other"
],
"type": "string"
}
},
"required": [
"key",
"type",
"ruleId",
"priority",
"count",
"rationale",
"measured",
"examples",
"moreNotShown"
],
"type": "object"
},
"type": "array"
},
"nextOffset": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Pass as offset for the next page; null on the last one"
},
"offset": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"priorityScale": {
"type": "string"
},
"status": {
"enum": [
"open",
"claimed",
"done",
"dismissed"
],
"type": "string"
},
"total": {
"description": "Actions matching the status and filters",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"view": {
"enum": [
"grouped",
"rows"
],
"type": "string"
}
},
"required": [
"view",
"priorityScale",
"status",
"total"
],
"type": "object"
}
},
{
"description": "Returns `keywords`, one row per tracked keyword, newest first: id (the keywordId rank_history takes), term, country, language, createdAt, `metric` (search volume, cpc, difficulty, fetchedAt) and `rank` (latest position within the top 30, null when the site is not in it, foundUrl, checkedAt, and whether an AI Overview appeared and cited the site). Read-only. metric is null until enrichment lands, about ten minutes after add_keywords; rank is null until check_rankings has run and its results have landed. An empty array means no keywords: call add_keywords.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "list_keywords",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"keywords": {
"items": {
"additionalProperties": false,
"properties": {
"country": {
"type": "string"
},
"createdAt": {
"description": "When the keyword was added as an ISO 8601 timestamp",
"type": "string"
},
"id": {
"description": "Keyword id, pass as keywordId to rank_history",
"type": "string"
},
"language": {
"type": "string"
},
"metric": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"cpc": {
"type": [
"number",
"null"
]
},
"difficulty": {
"type": [
"number",
"null"
]
},
"fetchedAt": {
"description": "When the metric was fetched as an ISO 8601 timestamp",
"type": "string"
},
"volume": {
"type": [
"number",
"null"
]
}
},
"required": [
"volume",
"cpc",
"difficulty",
"fetchedAt"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Latest keyword metrics, null until the monitor has run"
},
"rank": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"aiOverviewCited": {
"type": "boolean"
},
"aiOverviewPresent": {
"type": "boolean"
},
"checkedAt": {
"description": "When the rank was checked as an ISO 8601 timestamp",
"type": "string"
},
"foundUrl": {
"type": [
"string",
"null"
]
},
"position": {
"type": [
"number",
"null"
]
}
},
"required": [
"position",
"foundUrl",
"checkedAt",
"aiOverviewPresent",
"aiOverviewCited"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Latest rank check, null until the monitor has run"
},
"term": {
"type": "string"
}
},
"required": [
"id",
"term",
"country",
"language",
"createdAt",
"metric",
"rank"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"keywords"
],
"type": "object"
}
},
{
"description": "The opportunity queue: one row per query the site should hold and does not, or holds badly, built only from rows already measured. Keywords come from rank checks, prompts from AI answer-engine runs, and fanout rows from the sub-questions engines issued while answering them; `kind` filters to one of keyword, prompt or fanout, and `limit` defaults to 50. Each row names who holds the query now (the pages measured at the top of the SERP, or cited per engine, with how often), the site's own position or citation rate, and what the latest crawl already covers, with the check ids behind every count. `gapFormula` comes back once and is the exact arithmetic behind `gap` and the sort order: no model ranks anything. Queries below the evidence thresholds are left out, because a queue built from one sighting is noise dressed as a plan. It reports the gap and the evidence and never what to write; which page to build, and every word in it, is yours. Requires the profile: call set_project_profile first.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kind": {
"description": "Return only rows of this kind; omit for all three",
"enum": [
"keyword",
"prompt",
"fanout"
],
"type": "string"
},
"limit": {
"description": "Rows to return, default 50",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "list_opportunities",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"gapFormula": {
"description": "The exact arithmetic behind gap, and the sort order",
"type": "string"
},
"opportunities": {
"items": {
"additionalProperties": false,
"properties": {
"coverage": {
"additionalProperties": false,
"description": "What the site already has for this query, from the latest finished crawl",
"properties": {
"pages": {
"items": {
"additionalProperties": false,
"properties": {
"matchedIn": {
"description": "Where the head terms were found, or that the page ranks for the query",
"enum": [
"title",
"h1",
"ranking"
],
"type": "string"
},
"url": {
"type": "string"
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"url",
"wordCount",
"matchedIn"
],
"type": "object"
},
"type": "array"
},
"state": {
"description": "held: a page of the site already ranks or is cited for it. partial: a page carries the query's head terms. none: nothing measured covers it.",
"enum": [
"none",
"partial",
"held"
],
"type": "string"
}
},
"required": [
"state",
"pages"
],
"type": "object"
},
"demand": {
"description": "Comparable within a kind only; demandBasis says what it counts",
"type": "number"
},
"demandBasis": {
"type": "string"
},
"evidence": {
"additionalProperties": false,
"properties": {
"checkIds": {
"description": "The rank_check or geo_check rows the counts came from",
"items": {
"type": "string"
},
"type": "array"
},
"crawlId": {
"type": [
"string",
"null"
]
},
"engines": {
"items": {
"type": "string"
},
"type": "array"
},
"keywordId": {
"type": [
"string",
"null"
]
},
"promptId": {
"type": [
"string",
"null"
]
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"windowDays": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"checkIds",
"crawlId",
"runs",
"windowDays",
"engines",
"keywordId",
"promptId"
],
"type": "object"
},
"gap": {
"description": "Computed by gapFormula; the sort key",
"type": "number"
},
"holder": {
"description": "The pages measured holding this query, strongest first",
"items": {
"additionalProperties": false,
"properties": {
"count": {
"description": "Checks or runs in the window in which it held the query",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"engine": {
"description": "Engine that cited it; null for a keyword",
"type": [
"string",
"null"
]
},
"host": {
"type": "string"
},
"position": {
"description": "SERP position; null for an AI answer",
"type": [
"number",
"null"
]
},
"url": {
"type": "string"
}
},
"required": [
"url",
"host",
"position",
"engine",
"count"
],
"type": "object"
},
"type": "array"
},
"holderStrength": {
"description": "The share of checks or runs the strongest holder held",
"type": "number"
},
"kind": {
"description": "keyword: a tracked search term. prompt: a tracked question asked of AI answer engines. fanout: a sub-question an engine issued while answering a tracked prompt.",
"enum": [
"keyword",
"prompt",
"fanout"
],
"type": "string"
},
"ownPosition": {
"description": "The site's best search position over the window. Always null for prompt and fanout rows: an AI answer has no rank, only a frequency, which is ownShare.",
"type": [
"number",
"null"
]
},
"ownShare": {
"description": "The share of the query the site already holds, per gapFormula",
"type": "number"
},
"query": {
"description": "The keyword, prompt or sub-question, as it was measured",
"type": "string"
}
},
"required": [
"query",
"kind",
"demand",
"demandBasis",
"holder",
"ownPosition",
"ownShare",
"holderStrength",
"coverage",
"gap",
"evidence"
],
"type": "object"
},
"type": "array"
},
"windowDays": {
"description": "Rolling window every count in a row is measured over",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"gapFormula",
"windowDays",
"opportunities"
],
"type": "object"
}
},
{
"description": "Lists the sites this API key can operate on and returns `projects`, newest first, each with id (the projectId every other tool takes), domain and createdAt. Read-only. Sites removed with remove_project are not listed, and an empty array means nothing is tracked yet. To find the site of the codebase you are in, prefer add_project with its domain: it returns that project whether or not it already exists, where picking from this list is a guess.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "list_projects",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projects": {
"items": {
"additionalProperties": false,
"properties": {
"createdAt": {
"description": "When the project was created as an ISO 8601 timestamp",
"type": "string"
},
"domain": {
"type": "string"
},
"id": {
"description": "Project id, pass as projectId to every other tool",
"type": "string"
}
},
"required": [
"id",
"domain",
"createdAt"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"projects"
],
"type": "object"
}
},
{
"description": "What is measurably worse than it was, over the last `days` (default 30). Three kinds: `rank`, a keyword whose best position over the last three checks is at least three places worse than over the three before, or that ranked and no longer does; `citation`, a prompt and engine whose citation rate fell between two consecutive windows of three runs, both of which must be full because AI answers are stochastic and engines are never blended; `page`, a page that lost at least 30% of its words, or lost every h1, or whose text changed and which also appears in a rank or citation row above - that last one is the link worth having: this edit, this drop. Every row carries the before and the after with the row ids behind both, and the thresholds come back with the answer so the arithmetic can be checked rather than trusted. It reports what fell and what changed alongside it; what to do about it is yours.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"description": "Window in days, default 30",
"maximum": 365,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "list_regressions",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"regressions": {
"description": "Sorted by kind, then by the size of the drop",
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"after": {
"additionalProperties": false,
"properties": {
"bestPosition": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"checkIds": {
"items": {
"type": "string"
},
"type": "array"
},
"from": {
"description": "Oldest check in the window as an ISO 8601 timestamp",
"type": "string"
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"to": {
"description": "Newest check in the window as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"bestPosition",
"runs",
"from",
"to",
"checkIds"
],
"type": "object"
},
"before": {
"additionalProperties": false,
"properties": {
"bestPosition": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"checkIds": {
"items": {
"type": "string"
},
"type": "array"
},
"from": {
"description": "Oldest check in the window as an ISO 8601 timestamp",
"type": "string"
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"to": {
"description": "Newest check in the window as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"bestPosition",
"runs",
"from",
"to",
"checkIds"
],
"type": "object"
},
"drop": {
"description": "Places lost; a keyword that stopped ranking sorts above every slide",
"type": "number"
},
"foundUrls": {
"description": "The urls that ranked in the earlier window",
"items": {
"type": "string"
},
"type": "array"
},
"keywordId": {
"type": "string"
},
"kind": {
"const": "rank",
"type": "string"
},
"query": {
"type": "string"
},
"stoppedRanking": {
"description": "True when it ranked in the earlier window and does not now",
"type": "boolean"
}
},
"required": [
"kind",
"keywordId",
"query",
"before",
"after",
"stoppedRanking",
"drop",
"foundUrls"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"after": {
"additionalProperties": false,
"properties": {
"checkIds": {
"items": {
"type": "string"
},
"type": "array"
},
"from": {
"description": "Oldest run in the window as an ISO 8601 timestamp",
"type": "string"
},
"rate": {
"description": "Share of the window's runs that cited the site, 0 to 1",
"type": "number"
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"to": {
"description": "Newest run in the window as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"rate",
"runs",
"from",
"to",
"checkIds"
],
"type": "object"
},
"before": {
"additionalProperties": false,
"properties": {
"checkIds": {
"items": {
"type": "string"
},
"type": "array"
},
"from": {
"description": "Oldest run in the window as an ISO 8601 timestamp",
"type": "string"
},
"rate": {
"description": "Share of the window's runs that cited the site, 0 to 1",
"type": "number"
},
"runs": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"to": {
"description": "Newest run in the window as an ISO 8601 timestamp",
"type": "string"
}
},
"required": [
"rate",
"runs",
"from",
"to",
"checkIds"
],
"type": "object"
},
"citedUrls": {
"description": "The urls cited in the earlier window",
"items": {
"type": "string"
},
"type": "array"
},
"drop": {
"description": "Points of citation rate lost, 0 to 1",
"type": "number"
},
"engine": {
"description": "Engines are never blended; each is its own row",
"type": "string"
},
"kind": {
"const": "citation",
"type": "string"
},
"promptId": {
"type": "string"
},
"query": {
"type": "string"
}
},
"required": [
"kind",
"promptId",
"query",
"engine",
"before",
"after",
"drop",
"citedUrls"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"after": {
"additionalProperties": false,
"properties": {
"at": {
"description": "When that crawl finished as an ISO 8601 timestamp",
"type": "string"
},
"contentHash": {
"type": [
"string",
"null"
]
},
"crawlId": {
"type": "string"
},
"h1Count": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"crawlId",
"at",
"wordCount",
"h1Count",
"contentHash"
],
"type": "object"
},
"before": {
"additionalProperties": false,
"properties": {
"at": {
"description": "When that crawl finished as an ISO 8601 timestamp",
"type": "string"
},
"contentHash": {
"type": [
"string",
"null"
]
},
"crawlId": {
"type": "string"
},
"h1Count": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"wordCount": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"crawlId",
"at",
"wordCount",
"h1Count",
"contentHash"
],
"type": "object"
},
"drop": {
"description": "The share of its words the page lost, 0 when it lost none",
"type": "number"
},
"kind": {
"const": "page",
"type": "string"
},
"linkedTo": {
"description": "The rank or citation regressions measured on this same page",
"items": {
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"rank",
"citation"
],
"type": "string"
},
"query": {
"type": "string"
}
},
"required": [
"kind",
"query"
],
"type": "object"
},
"type": "array"
},
"reasons": {
"description": "word_count: it lost at least 30% of its words. h1: it lost every h1. content_hash: its text changed, reported only because something measured fell with it.",
"items": {
"enum": [
"word_count",
"h1",
"content_hash"
],
"type": "string"
},
"type": "array"
},
"url": {
"type": "string"
}
},
"required": [
"kind",
"url",
"reasons",
"before",
"after",
"linkedTo",
"drop"
],
"type": "object"
}
]
},
"type": "array"
},
"thresholds": {
"additionalProperties": false,
"description": "The exact floors a movement has to clear to be reported",
"properties": {
"citationMinRuns": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"rankDropPlaces": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"wordCountDropRatio": {
"type": "number"
}
},
"required": [
"rankDropPlaces",
"citationMinRuns",
"wordCountDropRatio"
],
"type": "object"
},
"windowDays": {
"description": "Window both halves of every comparison come from",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"windowDays",
"thresholds",
"regressions"
],
"type": "object"
}
},
{
"description": "Pass `keywordId`, which is the id field of an entry from list_keywords, together with the projectId that keyword belongs to. Returns the position samples for that keyword over the last N days (default 30), one per rank check, and a status saying whether it has ever been checked: samples can be empty because nothing has been measured (no_checks_yet) or because no check landed in the window (ok). Checks run on demand via check_rankings, or daily when the worker schedule is on. Read-only; a position is null when the site was not in the top 30.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"description": "How many days back to sample, default 30",
"maximum": 365,
"minimum": 1,
"type": "integer"
},
"keywordId": {
"description": "Keyword id (a UUID) from the id field of list_keywords",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId",
"keywordId"
],
"type": "object"
},
"name": "rank_history",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"samples": {
"items": {
"additionalProperties": false,
"properties": {
"aiOverviewCited": {
"type": "boolean"
},
"aiOverviewPresent": {
"type": "boolean"
},
"checkedAt": {
"description": "When the position was sampled as an ISO 8601 timestamp",
"type": "string"
},
"foundUrl": {
"type": [
"string",
"null"
]
},
"position": {
"description": "null means not found in the top 30 results, the depth every check reads",
"type": [
"number",
"null"
]
}
},
"required": [
"checkedAt",
"position",
"foundUrl",
"aiOverviewPresent",
"aiOverviewCited"
],
"type": "object"
},
"type": "array"
},
"status": {
"description": "no_checks_yet when this keyword has never been rank-checked, so an empty samples list means nothing has been measured; call check_rankings. ok when it has been checked at least once, so an empty samples list means no check landed inside the requested window.",
"enum": [
"no_checks_yet",
"ok"
],
"type": "string"
}
},
"required": [
"samples",
"status"
],
"type": "object"
}
},
{
"description": "Rebuilds this project's action list from what is already measured (crawl findings, ranks, AI-engine citations, visitor behavior) by fixed rules: no model, no provider call, no quota. Every crawl already triggers one, so call it only after check_rankings or check_geo results have landed and you want them turned into actions now. It measures nothing new: run run_audit, check_rankings or check_geo first if the data is stale. Runs in the worker within seconds to minutes; this returns once it is queued, so poll list_actions. Returns status (queued or already_queued), jobId and trigger. A second call for the same project within a minute returns already_queued.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "refresh_actions",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"jobId": {
"description": "Job id, null when this call was deduplicated into an already-queued run",
"type": [
"string",
"null"
]
},
"pollWith": {
"const": "list_actions",
"description": "Call list_actions once the worker has finished the run",
"type": "string"
},
"status": {
"description": "queued when this call created the job. already_queued when the same job for this project was enqueued moments ago and this call was deduplicated: the work is coming and nothing extra was billed.",
"enum": [
"queued",
"already_queued"
],
"type": "string"
},
"trigger": {
"const": "manual",
"description": "How the refresh was triggered; always manual over MCP",
"type": "string"
}
},
"required": [
"status",
"jobId",
"trigger",
"pollWith"
],
"type": "object"
}
},
{
"description": "Stop tracking a site: it leaves list_projects, stops being crawled or checked, and frees a site slot on the plan. Nothing is erased. Its crawls, findings and history are kept, and add_project on the same domain brings the same project back with its history intact. Use it for a site you no longer work on, or one you registered by mistake. Returns projectId, domain and removed; calling it again is harmless. Destructive only in that tracking stops: open actions stay as they were, and no scheduled audit or check runs until add_project restores it. Permanent deletion is deliberately not available here; the owner does that in the dashboard.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "remove_project",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"domain": {
"type": "string"
},
"projectId": {
"type": "string"
},
"removed": {
"description": "true if the site was being tracked; false if it already was not",
"type": "boolean"
}
},
"required": [
"projectId",
"domain",
"removed"
],
"type": "object"
}
},
{
"description": "Queues a fresh crawl and audit of the site and returns the crawl id and status, up to maxPages pages (default 100; the response says how many it used). Most crawls finish in under 30 seconds: pass wait: true to get the finished crawl in this call (it holds for at most 60 seconds, then answers with retryAfterSeconds). Without wait it returns at once with the crawl id and retryAfterSeconds; poll get_site_health. Each call starts a new crawl that fetches the live site. Costs pages_crawled quota, checked up front: a month that cannot cover maxPages answers quota_exceeded at once. When it finishes, the action list is rebuilt automatically; read list_actions or get_next_work. Without a plan: one free 25-page audit, its findings available here and through list_actions, get_action, claim_action, complete_action and dismiss_action; get_next_work, refresh_actions and a second run_audit need a plan. The free audit is clamped to 25 pages and runs once; its findings are filed as actions for list_actions, and a second run_audit answers subscription_required.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"maxPages": {
"description": "Pages to crawl at most, 1-5000; default 100, e.g. 250 for a larger site",
"maximum": 5000,
"minimum": 1,
"type": "integer"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"wait": {
"description": "true holds the call until the crawl finishes, for at most 60 seconds; default false returns at once",
"type": "boolean"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "run_audit",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"crawlId": {
"description": "Poll get_site_health for the result",
"type": "string"
},
"error": {
"description": "Why the crawl failed, when it did",
"type": "string"
},
"maxPages": {
"description": "Present only on the free preview: pages this crawl will cover, after clamping",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"maxPagesUsed": {
"description": "The page cap this crawl runs with",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"note": {
"description": "Present only on the free preview: what the crawl produces and where to read it",
"type": "string"
},
"pagesCrawled": {
"description": "Present when the call waited",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"retryAfterSeconds": {
"description": "Present while the crawl is still running: wait this long, then get_site_health",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"status": {
"enum": [
"queued",
"running",
"finished",
"failed"
],
"type": "string"
}
},
"required": [
"crawlId",
"status",
"maxPagesUsed"
],
"type": "object"
}
},
{
"description": "Step one of the growth recipe, and the gate on the rest of it. Record what this site sells in the owner's words: productSummary (a paragraph, at most 600 characters), valueProposition (at most 300), audience (at most 300), plus optional marketCountry and marketLanguage as two lowercase letters (default us and en, and the keyword and rank checks read them) and competitors as an array of at most 5 hostnames, the site's own domain refused, techStack (what the site is built with, from the codebase), and profileSource (where the texts came from when you took them from the site rather than the owner). Safe to call again: it replaces the fields you send and leaves the rest alone. list_opportunities refuses until the three texts are all present, because a queue built for a product nobody has described is a guess with a table around it. Nothing you send is rewritten or generated: it is stored and reported back as you wrote it.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"audience": {
"description": "Who buys it, in the owner's words",
"maxLength": 300,
"type": "string"
},
"competitors": {
"description": "Hostnames, e.g. [\"rival.com\"]. Replaces the stored list; an empty array clears it.",
"items": {
"maxLength": 255,
"type": "string"
},
"maxItems": 5,
"type": "array"
},
"marketCountry": {
"description": "Two lowercase letters, e.g. \"us\". Defaults to us.",
"maxLength": 2,
"type": "string"
},
"marketLanguage": {
"description": "Two lowercase letters, e.g. \"en\". Defaults to en.",
"maxLength": 2,
"type": "string"
},
"productSummary": {
"description": "What the product is, one paragraph. Send an empty string to clear it.",
"maxLength": 600,
"type": "string"
},
"profileSource": {
"description": "Where the three texts came from if the owner did not write them, e.g. \"the site's meta description and homepage hero\". Empty string clears it.",
"maxLength": 200,
"type": "string"
},
"projectId": {
"description": "Project id (a UUID) from add_project or list_projects, e.g. \"0190f7a2-8c1e-7d3a-9b4f-2e6c1a5d8f30\"",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"techStack": {
"anyOf": [
{
"enum": [
"nextjs",
"nuxt",
"sveltekit",
"remix",
"astro",
"gatsby",
"react_spa",
"vue_spa",
"angular",
"wordpress",
"shopify",
"webflow",
"wix",
"squarespace",
"framer",
"static",
"other"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "What the site is built with; read it from the codebase (package.json, config files). The audit uses it to tell a framework's by-design behaviour from a problem, from the next run_audit on. null clears it and falls back to detectedStack."
},
"valueProposition": {
"description": "Why someone picks it over the alternatives",
"maxLength": 300,
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "set_project_profile",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"audience": {
"description": "Who buys it",
"type": [
"string",
"null"
]
},
"competitors": {
"description": "Tracked competitor hostnames, at most 5",
"items": {
"type": "string"
},
"type": "array"
},
"completed": {
"description": "true once productSummary, valueProposition and audience are all filled in",
"type": "boolean"
},
"completedAt": {
"anyOf": [
{
"description": "When the profile was first complete as an ISO 8601 timestamp",
"type": "string"
},
{
"type": "null"
}
]
},
"detectedStack": {
"description": "What the latest crawl recognised from the HTML, or null when nothing matched",
"type": [
"string",
"null"
]
},
"marketCountry": {
"description": "Two-letter country the checks are run for, e.g. us",
"type": "string"
},
"marketLanguage": {
"description": "Two-letter language, e.g. en",
"type": "string"
},
"missing": {
"description": "Profile fields still empty; the strategy tools refuse while this is non-empty",
"items": {
"type": "string"
},
"type": "array"
},
"productSummary": {
"description": "What the product is, as the customer wrote it",
"type": [
"string",
"null"
]
},
"profileSource": {
"description": "Where the texts came from, when the owner did not write them",
"type": [
"string",
"null"
]
},
"projectId": {
"type": "string"
},
"techStack": {
"description": "What the site is built with, as declared; the audit prefers it over detectedStack",
"type": [
"string",
"null"
]
},
"valueProposition": {
"description": "Why someone picks it",
"type": [
"string",
"null"
]
}
},
"required": [
"projectId",
"productSummary",
"valueProposition",
"audience",
"marketCountry",
"marketLanguage",
"competitors",
"techStack",
"detectedStack",
"profileSource",
"completed",
"completedAt",
"missing"
],
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:3979038ff8785a9f3fe76ef6b2a06f092ef49cbc472c4c80ec94b210156dd65e | sha256sum