{ "count": 78, "tools": [ { "name": "sites_list", "title": "List sites", "description": "Sites on this account with keys, snippet and last 7 days.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_get", "title": "Get one site", "description": "One site with its key, snippet and settings (open-startup, allowed origins).", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_portfolio", "title": "Portfolio daily rollup", "description": "Daily visitors, pageviews and goals per site across the account, from the hourly rollup (the portfolio page sparklines and heatmap).", "scope": "read", "inputSchema": { "type": "object", "properties": { "days": { "description": "Window, default 30.", "type": "integer", "minimum": 1, "maximum": 90 } }, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "control_overview", "title": "Control overview", "description": "Everything on the dashboard's all-sites Control page: revenue (EUR, all time), traffic per day, traffic mix (AI agents / search / direct / referral, 1 cell = 1% of visits), site setup across all sites, a 52-week visitor heatmap and the sites table sorted by visitors.", "scope": "read", "inputSchema": { "type": "object", "properties": { "days": { "description": "Window for the traffic chart and the traffic mix, in UTC days. Default 30.", "anyOf": [ { "type": "number", "const": 7 }, { "type": "number", "const": 30 }, { "type": "number", "const": 90 } ] } }, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_setup", "title": "Site setup", "description": "The 7 setup steps of one site (snippet, Search Console property, goals, revenue, AEO scan, Domain Rating, AI buyer questions): done or not, with a status line each.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_overview", "title": "Site overview", "description": "Headline numbers for a period, optionally filtered and compared with the previous period.", "scope": "read", "inputSchema": { "type": "object", "properties": { "period": { "description": "Relative period, default 7d. Ignored when from/to are given.", "type": "string", "enum": [ "today", "yesterday", "7d", "30d", "90d", "12mo" ] }, "from": { "description": "First day, YYYY-MM-DD (UTC).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Last day, YYYY-MM-DD (UTC), inclusive.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "filters": { "type": "object", "properties": { "page": { "type": "string", "minLength": 1, "maxLength": 500 }, "entry": { "type": "string", "minLength": 1, "maxLength": 500 }, "exit": { "type": "string", "minLength": 1, "maxLength": 500 }, "channel": { "type": "string", "minLength": 1, "maxLength": 500 }, "referrer": { "type": "string", "minLength": 1, "maxLength": 500 }, "campaign": { "type": "string", "minLength": 1, "maxLength": 500 }, "country": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": "string", "minLength": 1, "maxLength": 500 }, "city": { "type": "string", "minLength": 1, "maxLength": 500 }, "device": { "type": "string", "minLength": 1, "maxLength": 500 }, "browser": { "type": "string", "minLength": 1, "maxLength": 500 }, "os": { "type": "string", "minLength": 1, "maxLength": 500 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false, "description": "Session filters, e.g. {\"channel\":\"organic_search\",\"country\":\"DE\"}. All must match." }, "compare": { "description": "Also return the previous period of equal length and the change.", "type": "boolean" } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_timeseries", "title": "Site timeseries", "description": "Visitors, sessions, pageviews and bounces per UTC day.", "scope": "read", "inputSchema": { "type": "object", "properties": { "period": { "description": "Relative period, default 7d. Ignored when from/to are given.", "type": "string", "enum": [ "today", "yesterday", "7d", "30d", "90d", "12mo" ] }, "from": { "description": "First day, YYYY-MM-DD (UTC).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Last day, YYYY-MM-DD (UTC), inclusive.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "filters": { "type": "object", "properties": { "page": { "type": "string", "minLength": 1, "maxLength": 500 }, "entry": { "type": "string", "minLength": 1, "maxLength": 500 }, "exit": { "type": "string", "minLength": 1, "maxLength": 500 }, "channel": { "type": "string", "minLength": 1, "maxLength": 500 }, "referrer": { "type": "string", "minLength": 1, "maxLength": 500 }, "campaign": { "type": "string", "minLength": 1, "maxLength": 500 }, "country": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": "string", "minLength": 1, "maxLength": 500 }, "city": { "type": "string", "minLength": 1, "maxLength": 500 }, "device": { "type": "string", "minLength": 1, "maxLength": 500 }, "browser": { "type": "string", "minLength": 1, "maxLength": 500 }, "os": { "type": "string", "minLength": 1, "maxLength": 500 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false, "description": "Session filters, e.g. {\"channel\":\"organic_search\",\"country\":\"DE\"}. All must match." } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_breakdown", "title": "Site breakdown", "description": "Top values of one dimension (pages, channels, referrers, countries, goals, ...).", "scope": "read", "inputSchema": { "type": "object", "properties": { "period": { "description": "Relative period, default 7d. Ignored when from/to are given.", "type": "string", "enum": [ "today", "yesterday", "7d", "30d", "90d", "12mo" ] }, "from": { "description": "First day, YYYY-MM-DD (UTC).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Last day, YYYY-MM-DD (UTC), inclusive.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "filters": { "type": "object", "properties": { "page": { "type": "string", "minLength": 1, "maxLength": 500 }, "entry": { "type": "string", "minLength": 1, "maxLength": 500 }, "exit": { "type": "string", "minLength": 1, "maxLength": 500 }, "channel": { "type": "string", "minLength": 1, "maxLength": 500 }, "referrer": { "type": "string", "minLength": 1, "maxLength": 500 }, "campaign": { "type": "string", "minLength": 1, "maxLength": 500 }, "country": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": "string", "minLength": 1, "maxLength": 500 }, "city": { "type": "string", "minLength": 1, "maxLength": 500 }, "device": { "type": "string", "minLength": 1, "maxLength": 500 }, "browser": { "type": "string", "minLength": 1, "maxLength": 500 }, "os": { "type": "string", "minLength": 1, "maxLength": 500 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false, "description": "Session filters, e.g. {\"channel\":\"organic_search\",\"country\":\"DE\"}. All must match." }, "dimension": { "type": "string", "enum": [ "page", "entry", "exit", "channel", "referrer", "campaign", "country", "region", "city", "device", "browser", "os", "hostname", "goal", "outbound" ] }, "limit": { "description": "Rows, default 10.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "site_id", "dimension" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_realtime", "title": "Site realtime", "description": "Visitors in the last 5 minutes, what they view, where they are.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } }, { "name": "site_goals", "title": "Site goals", "description": "Goal names declared for a site.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_create", "title": "Create site", "description": "Add a site (idempotent per domain). Needs the write scope. Returns the snippet.", "scope": "read", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "Bare domain, e.g. example.com. Subdomains are included." }, "allowed_origins": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 253 } } }, "required": [ "name", "domain" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "goal_create", "title": "Declare goal", "description": "Declare or describe a goal name. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "description": { "type": "string", "maxLength": 300 } }, "required": [ "site_id", "name" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "score_url", "title": "Score URL", "description": "Fetch a public URL and score its on-page AI-search readiness (0-10 per dimension, ranked action items). Deterministic; it does not measure whether an engine cites the page.", "scope": "read", "inputSchema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The page URL to score." } }, "required": [ "url" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "rubric_list", "title": "List AEO rubric", "description": "The weighted dimensions score_url uses.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_authority", "title": "Site Domain Rating", "description": "Daily Domain Rating (0-100, DataForSEO rank, not Ahrefs DR) and referring domains, with gaps and why. Returns {configured:false} when no DataForSEO key resolves and there is no history.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 800 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_aeo", "title": "Site AEO scan", "description": "Latest stored on-page AI-search readiness scan of the site, with action items, and the score history.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "aeo_scan", "title": "Scan a page now", "description": "Score a page of the site (the homepage by default) and store the scan. Free. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } }, { "name": "site_search", "title": "Site Search Console", "description": "Google Search Console: clicks and impressions per day with the previous period, top queries, and stuck queries (positions 11 to 20, the cheapest wins). Returns {connected:false} until Search Console is connected in the dashboard.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 7, "maximum": 480 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "proof_progress", "title": "Launch proof: weekly Google clicks vs baseline", "description": "Per site with a Search Console property: clicks and impressions for the 4 weeks before 2026-10-22, the baseline (mean weekly clicks, floored at 1), the latest 7 synced days and their ratio. Also how many sites tripled (launch rule: 3).", "scope": "read", "inputSchema": { "type": "object", "properties": {}, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_indexing", "title": "Site indexing issues", "description": "Sitemap URLs Google has not indexed, grouped by reason, each with a fix hint and an Inspect link. Checked daily, 20 URLs at a time, never-seen and oldest first.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "indexing_check", "title": "Check indexing now", "description": "Inspect up to 10 more sitemap URLs now. Once an hour per site. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } }, { "name": "submit_sitemap", "title": "Submit sitemap to Search Console", "description": "Submit the site sitemap to Google Search Console (sitemaps.submit), then read it back (lastSubmitted, lastDownloaded, warnings) and run URL Inspection on up to 10 listed URLs. The only write call agentsgym makes against Search Console; a read-only grant is refused with the step to take. Google has no public API for \"Request indexing\", that stays manual.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "sitemap": { "type": "string", "format": "uri" } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "google_properties", "title": "List Search Console properties", "description": "The connected Google account's Search Console properties, for site_property_set. 409 until Search Console is connected in the dashboard.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "site_property_set", "title": "Set Search Console property", "description": "Pin a site to one Search Console property, or pass null to re-run the auto-match by domain. A change clears the sync markers and submits the sitemap once when write access is granted. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "property": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ], "description": "A property from google_properties, or null for auto-match." } }, "required": [ "site_id", "property" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "site_annotations", "title": "Site annotations", "description": "Deploy and change annotations drawn on the traffic chart (merged loop PRs and recorded changes), newest first.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_plan", "title": "Site keyword plan", "description": "The keyword plan for a site: market, competitors and audiences with coverage (\"1 of 2\" published; needs attention at 0), every keyword with status planned, scheduled, published or saved, and stage ranking when Search Console reports the query. Articles are written in the repo; this plans and measures them.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "plan_next", "title": "Next keyword to write", "description": "The next keyword for the seo-content skill: a scheduled keyword that is due, else the best planned one by opportunity (volume discounted by difficulty). After opening the PR call plan_keyword_update with status published, pr_url and published_url.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_pages", "title": "Site best pages", "description": "Best pages from Search Console over the last sync window: clicks, impressions, CTR, average position, and the plan keyword a page was published for. Returns an empty list with a note until Search Console is connected and synced.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "sort": { "type": "string", "enum": [ "clicks", "impressions", "ctr", "position", "page" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "limit": { "description": "Rows, default 50.", "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "plan_inputs_set", "title": "Set keyword plan inputs", "description": "Set the competitor domains and target audiences (short phrases) discovery starts from, and the market (location_code, language_code). Each list given replaces the old one; omitted lists stay. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "competitors": { "description": "Competitor domains. Replaces the list when given.", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 300 } }, "audiences": { "description": "Target audiences as short phrases (\"indie hackers\"). Replaces the list when given.", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 80 } }, "location_code": { "description": "DataForSEO location, e.g. 2276.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "language_code": { "description": "e.g. en, de.", "type": "string", "minLength": 2, "maxLength": 8 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "plan_discover", "title": "Discover plan keywords", "description": "Fill the plan from its inputs through DataForSEO: a competitor contributes the keywords it ranks for, an audience contributes keyword ideas. Runs up to three sources per call (cached, within the daily budget, cost_usd reported); repeat while remaining_sources is above 0. Only keywords with volume are kept; existing ones are never overwritten. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "source": { "description": "One competitor domain or audience phrase to run now. Omitted: up to three sources, never-discovered first, then the one discovered longest ago.", "type": "string", "minLength": 2, "maxLength": 300 }, "per_source": { "description": "Keywords to ask for per source, default 20.", "type": "integer", "minimum": 5, "maximum": 50 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "plan_keywords_add", "title": "Add plan keywords", "description": "Add up to 40 keywords by hand, with optional volume, difficulty and intent from keyword_ideas. Existing keywords are skipped. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "keywords": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "minLength": 2, "maxLength": 120 }, "volume": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "difficulty": { "type": "integer", "minimum": 0, "maximum": 100 }, "intent": { "type": "string", "maxLength": 40 }, "status": { "description": "Default planned.", "type": "string", "enum": [ "planned", "saved" ] }, "source": { "type": "string", "enum": [ "competitor", "audience", "other" ] }, "source_ref": { "type": "string", "maxLength": 300 }, "notes": { "type": "string", "maxLength": 400 } }, "required": [ "keyword" ] } } }, "required": [ "site_id", "keywords" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "plan_keyword_update", "title": "Update a plan keyword", "description": "Move a keyword: planned, scheduled (needs scheduled_for), published (needs published_url or pr_url, on the site domain) or saved for later. Going back to planned or saved clears the date and URLs. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "keyword_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "planned", "scheduled", "published", "saved" ] }, "scheduled_for": { "description": "Publish date; required for scheduled.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "published_url": { "description": "The page URL on the site. Published needs this or pr_url.", "type": "string", "maxLength": 500, "format": "uri" }, "pr_url": { "description": "The pull request that ships the page.", "type": "string", "maxLength": 500, "format": "uri" }, "notes": { "type": "string", "maxLength": 400 } }, "required": [ "site_id", "keyword_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_backlinks", "title": "Site backlink ledger", "description": "The backlink ledger of a site: counts (live, in progress, lost), a 12-week live-link trend, strongest live links (Domain Rating, target page, anchor, first seen, how we got it), links in progress, lost links, and AI citation strength per page, which is an estimate from the strength of the linking domains and never a measured AI result. No money value is estimated.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "backlink_record", "title": "Record a backlink", "description": "Log a backlink in the ledger: call it with status in_progress as soon as an outreach email is sent or a directory submitted, how = outreach, directory, organic or own_product. The same source and target again updates the row. Links are earned; this never buys or exchanges one. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "source_url": { "type": "string", "maxLength": 500, "format": "uri", "description": "The page that links (or will link) to the site." }, "target_url": { "description": "The page of the site it points at. Default: the home page.", "type": "string", "maxLength": 500, "format": "uri" }, "anchor": { "type": "string", "maxLength": 200 }, "status": { "description": "Default in_progress: asked or submitted, not seen yet.", "type": "string", "enum": [ "in_progress", "live", "lost" ] }, "how": { "description": "outreach, directory, organic or own_product. Default outreach.", "type": "string", "enum": [ "outreach", "directory", "organic", "own_product" ] }, "dr": { "description": "Domain Rating of the linking domain, when known.", "type": "integer", "minimum": 0, "maximum": 100 }, "link_type": { "type": "string", "enum": [ "dofollow", "nofollow", "ugc", "sponsored" ] }, "first_seen": { "description": "Default today.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "notes": { "description": "Who was asked, which batch, evidence path.", "type": "string", "maxLength": 400 } }, "required": [ "site_id", "source_url" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "backlink_update", "title": "Update a backlink", "description": "Change one ledger row by id: status (in_progress, live, lost), anchor, how, Domain Rating, link type, notes. A status change is dated, so the trend stays true. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "backlink_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "in_progress", "live", "lost" ] }, "anchor": { "type": "string", "maxLength": 200 }, "how": { "type": "string", "enum": [ "outreach", "directory", "organic", "own_product" ] }, "dr": { "type": "integer", "minimum": 0, "maximum": 100 }, "link_type": { "type": "string", "enum": [ "dofollow", "nofollow", "ugc", "sponsored" ] }, "notes": { "type": "string", "maxLength": 400 } }, "required": [ "site_id", "backlink_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "backlinks_check", "title": "Check backlinks", "description": "Confirm links by fetching their source pages (up to 10 per call, least recently checked first): a link to the site found makes the row live and reads dofollow or nofollow; a page that loads without it turns a live link lost and leaves an in-progress one in progress; a page that cannot be loaded changes nothing. Static HTML only. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "backlink_ids": { "description": "Links to check. Default: the 10 least recently checked live or in-progress ones.", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "backlinks_sync", "title": "Sync backlinks from DataForSEO", "description": "Import the strongest live backlinks DataForSEO sees for the site as live ledger rows (how organic), and with lost=true mark known links it no longer finds as lost. Paid and cached 7 days; returns cost_usd, or {configured:false}. DataForSEO lists one link per referring domain, so a link missing from a short list is not proof it is gone. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "lost": { "description": "Also pull links DataForSEO saw once and no longer finds, and mark them lost.", "type": "boolean" }, "limit": { "description": "Links to pull, default 25, at most 50.", "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "launch_platforms", "title": "Launch platform registry", "description": "The researched registry of launch platforms and directories (Product Hunt, TinyLaunch, communities, awesome lists): tier, pricing, link type, Domain Rating, who must own the account (christoph or agent), fit tags. Default shows the included ones; registry_status excluded lists dead, paid-only and spam sites not to retry. Pass site_id to see which the site already tracks.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "description": "Mark which platforms this site already tracks.", "type": "string", "minLength": 1 }, "q": { "description": "Match on name, id or domain.", "type": "string", "maxLength": 80 }, "registry_status": { "description": "The registry verdict, default included.", "type": "string", "enum": [ "included", "deferred", "excluded" ] }, "tier": { "type": "string", "enum": [ "A", "B", "C" ] }, "fit": { "type": "string", "maxLength": 20 }, "limit": { "description": "Rows, default 40.", "type": "integer", "minimum": 1, "maximum": 200 } }, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_launches", "title": "Site launch tracker", "description": "The launch tracker of one app: per platform the status (todo, prepared, waiting_christoph, submitted, live, rejected), account owner, profile URL, date, link type and result (link live, referral visitors and goals reached, last 30 days, from agentsgym analytics), plus counts and the best platforms not tracked yet.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "launch_set", "title": "Set a launch status", "description": "Create or update one platform on a site's launch tracker. platform is a registry id (launch_platforms) or a domain for a site the registry does not know. Statuses: todo, prepared, waiting_christoph (a human must act), submitted, live, rejected. Submitted and live listings appear in the backlink ledger; set link_live once the link is confirmed (backlinks_check does it for you). Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "platform": { "type": "string", "minLength": 2, "maxLength": 300, "description": "A registry id from launch_platforms (product-hunt), or the platform site as a domain or URL for one the registry does not know (custom: when it has no site of its own, like an awesome list)." }, "name": { "description": "Display name for a platform outside the registry.", "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "description": "Default todo on a new row.", "type": "string", "enum": [ "todo", "prepared", "waiting_christoph", "submitted", "live", "rejected" ] }, "account_owner": { "description": "Default from the registry, else agent.", "type": "string", "enum": [ "christoph", "agent" ] }, "profile_url": { "description": "The listing or profile page.", "type": "string", "maxLength": 500, "format": "uri" }, "date": { "description": "Submitted, live or rejected on. Default today for those statuses.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "link_type": { "type": "string", "enum": [ "dofollow", "nofollow", "ugc", "sponsored", "none" ] }, "link_live": { "description": "Whether the link to the site is there. Leave out until known.", "type": "boolean" }, "notes": { "description": "Why it is blocked, what Christoph must do, evidence.", "type": "string", "maxLength": 400 } }, "required": [ "site_id", "platform" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "launches_seed", "title": "Seed the launch tracker", "description": "Add the registry's included platforms of the given tiers (default A and B, optionally only those with a fit tag such as ios or dev) to a site as todo rows. Platforms already tracked are skipped. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1, "description": "Site id from sites_list." }, "tiers": { "description": "Registry tiers to add as todo rows. Default A and B.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C" ] } }, "fit": { "description": "Only platforms with one of these fit tags (web, ios, mac, dev, ai, saas, german, ...).", "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 20 } } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_workout", "title": "Site workout", "description": "The only SEO-loop backlog for this site: open, claimed, merged and rejected tasks, plus rep verdicts seven days after a merge.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_wins", "title": "Weekly wins", "description": "The last complete week against the one before, computed from stored data only: average Google position, clicks, new live backlinks, pages published, Domain Rating, visitors, goal completions and AI mention rate. Each win carries its evidence (dashboard page, tool, REST route, source URLs). Nothing is invented: a quiet week answers \"No movement this week\", and measures that moved down are listed separately. Without site_id, every site.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "list_actions", "title": "Next actions", "description": "The to-do list for the weekly runs: up to 5 recommended actions per site, ranked by expected effect, derived from rules over the data (page ranking 11 to 20, competitor with no coverage, sitemap not submitted, no goal declared, lost link, unindexed pages, overdue keyword, low AEO). Each says why, who owns it (agent or human), the exact step, the tool call or skill that does it, and its evidence. Without site_id, the ranked list across every site. Claim one with claim_action, close it with complete_action.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "owner": { "type": "string", "enum": [ "agent", "human" ] }, "status": { "type": "string", "enum": [ "open", "claimed" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "claim_action", "title": "Claim a next action", "description": "Take one action from list_actions so another agent does not start it. Refuses with 409 when it is already claimed or was completed in the last 14 days. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "action_id": { "type": "string", "minLength": 1, "maxLength": 300 }, "by": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "site_id", "action_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "complete_action", "title": "Complete a next action", "description": "Close an action with evidence: what was done and where to see it (a PR URL, a page URL, a ledger row). It stays out of the list for 14 days while the data catches up and comes back only if its rule still fires. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "action_id": { "type": "string", "minLength": 1, "maxLength": 300 }, "evidence": { "type": "string", "minLength": 10, "maxLength": 1000, "description": "What was done and where to see it: a PR URL, a page URL, a ledger row" } }, "required": [ "site_id", "action_id", "evidence" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_brief", "title": "Site Monday brief", "description": "Week-over-week Search Console, traffic, AI referrals, indexing, Domain Rating, loop counts and rep verdicts for one site.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "project_brief", "title": "Portfolio Monday brief", "description": "The Monday brief for every site on this account.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "workout_claim", "title": "Claim a workout task", "description": "Mark a task claimed with the loop PR URL. Refuses with 409 while another task for that site is claimed. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1 }, "pr_url": { "type": "string", "format": "uri" } }, "required": [ "site_id", "task_id", "pr_url" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "workout_reject", "title": "Reject a workout task", "description": "Reject a task with a reason. Its fingerprint never comes back. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 400 } }, "required": [ "site_id", "task_id", "reason" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_ai_mentions", "title": "Site AI mentions", "description": "7-day rolling rate of whether AI answers via API with web search name this site, per engine. {configured:false} means connect DataForSEO; it is not a zero.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 7, "maximum": 90 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_ai_prompts", "title": "Site AI prompts", "description": "Buyer questions sampled across engines, with aliases, competitors and the latest answers. AI answers via API with web search, not what a logged-in user sees.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_ai_prompts_set", "title": "Set AI prompts", "description": "Replace the buyer questions, aliases and competitors sampled for this site. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "prompts": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 8, "maxLength": 400 } }, "aliases": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 80 } }, "competitors": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 80 } } }, "required": [ "site_id", "prompts" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_revenue", "title": "Site revenue", "description": "Sales in a period, attributed to consented visitors and their first-touch channel. Unattributed when checkout had no visitor id.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 90 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_funnel", "title": "Site funnel", "description": "Declared goals and how many times each completed.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "visitor_journey", "title": "Visitor journey", "description": "Events and sales for one consented visitor (agv_ id). Daily-hash visitors have no multi-day journey.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "visitor_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id", "visitor_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "revenue_record", "title": "Record a sale", "description": "Record a first-party sale. Needs the write scope. Use webhooks for Stripe, Polar and App Store.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "default": "usd", "type": "string", "minLength": 3, "maxLength": 3 }, "visitor_id": { "type": "string", "pattern": "^agv_[a-z0-9]{8,40}$" }, "provider": { "default": "manual", "type": "string", "enum": [ "stripe", "polar", "appstore", "manual" ] }, "provider_event_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "occurred_at": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "site_id", "amount_cents" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } }, { "name": "project_leaderboard", "title": "Portfolio leaderboard", "description": "Sites on this account ranked by week-over-week visitor growth.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_records", "title": "Site records", "description": "Personal bests, current streaks and milestone OG cards for one site.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_open_startup_set", "title": "Set open-startup board", "description": "Opt this site into a public board at /board/:domain. Off by default. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "open": { "type": "boolean" } }, "required": [ "site_id", "open" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_share_card", "title": "Public share card", "description": "The site public share card: whether it is on, its link and image URL, a preview of the numbers the public sees (Domain Rating, live backlinks, Google clicks, visitors, optional revenue) and a ready X post draft. Off by default.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_share_card_set", "title": "Set public share card", "description": "Publish, change, rotate or revoke the public share card. enabled=true publishes (mints the link), enabled=false kills the link, rotate=true swaps it for a new one, period_days is 7, 30 or 90, show_revenue is a separate switch and stays off unless set. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "enabled": { "description": "true publishes the card (mints a link if there is none), false revokes the link.", "type": "boolean" }, "rotate": { "description": "true replaces the link with a new one and kills the old one. Needs the card on.", "type": "boolean" }, "period_days": { "description": "Window of the visitors and clicks numbers, default 30.", "anyOf": [ { "type": "number", "const": 7 }, { "type": "number", "const": 30 }, { "type": "number", "const": 90 } ] }, "show_revenue": { "description": "Show revenue on the card. Off by default; revenue is private unless you say so.", "type": "boolean" } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "keyword_ideas", "title": "Keyword ideas", "description": "Keyword ideas for up to 20 seed keywords in a market (location_code + language_code, e.g. 2276 + de), with search volume, difficulty, intent and CPC. DataForSEO Labs, paid; cached 7 days, returns cost_usd. {configured:false} means connect DataForSEO.", "scope": "read", "inputSchema": { "type": "object", "properties": { "keywords": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "1-20 seed keywords in the market language." }, "location_code": { "description": "DataForSEO location code, e.g. 2840 (US), 2276 (Germany). Default 2840.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "language_code": { "description": "Language code, e.g. en, de. Default en.", "type": "string", "minLength": 2, "maxLength": 8 }, "limit": { "description": "Ideas to return, default 50.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "keywords" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "ranked_keywords", "title": "Ranked keywords of a domain", "description": "Keywords any domain (ours or a competitor) ranks for in a market, highest traffic first, each with position, URL, volume and difficulty, plus the domain organic metrics. DataForSEO Labs, paid; cached 7 days, returns cost_usd.", "scope": "read", "inputSchema": { "type": "object", "properties": { "target": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^[a-z0-9.-]+$", "description": "Bare domain, no scheme — ours or a competitor." }, "location_code": { "description": "DataForSEO location code, e.g. 2840 (US), 2276 (Germany). Default 2840.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "language_code": { "description": "Language code, e.g. en, de. Default en.", "type": "string", "minLength": 2, "maxLength": 8 }, "limit": { "description": "Keywords to return, default 50.", "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "target" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "domain_overview", "title": "Domain overview", "description": "Competitor snapshot in one call: estimated monthly organic traffic (ETV), ranked-keyword counts (total, top 3, top 10) and the 10 strongest keywords. DataForSEO Labs, paid; cached 7 days, returns cost_usd.", "scope": "read", "inputSchema": { "type": "object", "properties": { "target": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^[a-z0-9.-]+$", "description": "Bare domain, no scheme — ours or a competitor." }, "location_code": { "description": "DataForSEO location code, e.g. 2840 (US), 2276 (Germany). Default 2840.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "language_code": { "description": "Language code, e.g. en, de. Default en.", "type": "string", "minLength": 2, "maxLength": 8 } }, "required": [ "target" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "backlinks_list", "title": "Backlink list", "description": "Strongest live backlinks of any domain, one per referring domain, with anchor, dofollow and the linking domain Domain Rating. site_authority has the daily summary; this is the list. DataForSEO Backlinks, paid; cached 7 days, returns cost_usd.", "scope": "read", "inputSchema": { "type": "object", "properties": { "target": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^[a-z0-9.-]+$", "description": "Bare domain, no scheme — ours or a competitor." }, "limit": { "description": "Backlinks to return, default 25.", "type": "integer", "minimum": 1, "maximum": 100 }, "status": { "description": "live (default) or lost: links DataForSEO saw once and no longer finds.", "type": "string", "enum": [ "live", "lost" ] } }, "required": [ "target" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "referring_domains", "title": "Referring domains", "description": "Referring domains of any domain, strongest first, with Domain Rating, backlink count and first seen. DataForSEO Backlinks, paid; cached 7 days, returns cost_usd.", "scope": "read", "inputSchema": { "type": "object", "properties": { "target": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^[a-z0-9.-]+$", "description": "Bare domain, no scheme — ours or a competitor." }, "limit": { "description": "Backlinks to return, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "target" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "serp_live", "title": "Live Google SERP", "description": "The live Google SERP for one keyword in a market: every feature present (ai_overview, people_also_ask, ...) and each result with position, URL, title and domain. DataForSEO SERP, paid; cached 1 day, returns cost_usd.", "scope": "read", "inputSchema": { "type": "object", "properties": { "keyword": { "type": "string", "minLength": 1, "maxLength": 200 }, "location_code": { "description": "DataForSEO location code, e.g. 2840 (US), 2276 (Germany). Default 2840.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "language_code": { "description": "Language code, e.g. en, de. Default en.", "type": "string", "minLength": 2, "maxLength": 8 }, "depth": { "description": "Results to fetch, default 10.", "type": "integer", "minimum": 10, "maximum": 30 } }, "required": [ "keyword" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "page_audit", "title": "On-page audit of one URL", "description": "A live on-page audit of one URL, ours or a competitor: HTTP status, title, meta description, canonical, H1, word count, link and image counts, load timing and the list of failed checks (issues). DataForSEO OnPage, paid; cached 1 day, returns cost_usd.", "scope": "read", "inputSchema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "Full page URL, https://…" } }, "required": [ "url" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "agent_gap_report", "title": "Report a gap", "description": "Report something you needed from agentsgym and could not read or do: a missing tool or number, an error you could not get past. Any key may call it. It lands in feedback_list, on the dashboard Brief page and in the weekly agentsgym improvement loop.", "scope": "read", "inputSchema": { "type": "object", "properties": { "need": { "type": "string", "minLength": 3, "maxLength": 500, "description": "What you needed and could not read or do, in one sentence." }, "tool": { "description": "The tool or route that fell short, e.g. site_breakdown.", "type": "string", "maxLength": 80 }, "site_id": { "description": "The site it was about, when it was one site.", "type": "string", "minLength": 1 }, "detail": { "description": "What you tried, the error, and what would have helped.", "type": "string", "maxLength": 2000 } }, "required": [ "need" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } }, { "name": "feedback_list", "title": "Feedback list", "description": "What agents (agent_gap_report) reported they could not read or do, newest first, with how many are new. The weekly agentsgym improvement loop works from this list.", "scope": "read", "inputSchema": { "type": "object", "properties": { "limit": { "description": "Reports, newest first. Default 50.", "type": "integer", "minimum": 1, "maximum": 200 } }, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_audits", "title": "Weekly SEO audits", "description": "The weekly SEO audit history of a site, newest first: per dimension the score, IST (measured), SOLL (target) and what it became the following week, the actions taken (PRs, articles, backlinks), the verdict, the seo-review health /10 and what agentsgym itself measured that week.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "weeks": { "description": "Weeks of history, default 12.", "type": "integer", "minimum": 1, "maximum": 52 } }, "required": [ "site_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_audit_record", "title": "Record the weekly SEO audit", "description": "Record this week's SEO audit of a site: per dimension a 0-10 score, IST and SOLL; the actions taken with their URLs; next week's verdict. One per site and ISO week, recording again replaces it. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "week": { "description": "Any day of the audited week (UTC); stored as its Monday. Default this week.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dimensions": { "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "indexability", "metadata", "content_intent", "internal_links", "search_console", "keywords", "ai_visibility", "buy_intent", "aeo" ] }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "0-10 against the seo-review anchors; null when not applicable this week (N/A is not 10)." }, "ist": { "anyOf": [ { "type": "number" }, { "type": "string", "minLength": 1, "maxLength": 200 } ], "description": "IST: what was measured this week." }, "soll": { "anyOf": [ { "type": "number" }, { "type": "string", "minLength": 1, "maxLength": 200 } ], "description": "SOLL: the target this dimension should reach." }, "metric": { "description": "What the IST/SOLL numbers count, e.g. \"GSC impressions / week\".", "type": "string", "maxLength": 80 }, "lower_is_better": { "description": "True for positions and error counts: the target is reached at or below SOLL.", "type": "boolean" }, "note": { "type": "string", "maxLength": 400 } }, "required": [ "dimension", "score", "ist", "soll" ] }, "description": "One entry per dimension reviewed, each with IST and SOLL." }, "actions": { "description": "What was changed this week: PR URLs, articles, backlink actions.", "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pr", "article", "backlink", "fix", "other" ], "description": "pr: a code change; article: a page published (keyword plan); backlink: an outreach or submission (backlink ledger); fix: a setting or data fix; other." }, "title": { "type": "string", "minLength": 3, "maxLength": 200 }, "url": { "description": "The PR, the page, the backlink source.", "type": "string", "maxLength": 500, "format": "uri" }, "status": { "description": "Default done.", "type": "string", "enum": [ "planned", "done" ] } }, "required": [ "kind", "title" ] } }, "verdict": { "description": "Next week: keep, change or stop, and why, in one or two sentences.", "type": "string", "maxLength": 600 }, "summary": { "type": "string", "maxLength": 600 }, "source": { "description": "Who recorded it, e.g. \"seo-review weekly loop\".", "type": "string", "maxLength": 80 } }, "required": [ "site_id", "dimensions" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "site_delete", "title": "Delete a site", "description": "Delete a site and every event, rollup and reading stored for it. Cannot be undone. confirm must be the site domain. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 }, "confirm": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The site domain, typed out. The delete cannot be undone." } }, "required": [ "site_id", "confirm" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } }, { "name": "providers_status", "title": "Provider status", "description": "Which paid providers are connected (DataForSEO, an engine-level secret — not set per account), the daily budget and today's spend, and exactly what is missing.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "keys_list", "title": "List API keys", "description": "API keys on this account: name, prefix, scopes, created and last used. Never the secret.", "scope": "read", "inputSchema": { "type": "object", "properties": {} }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "key_create", "title": "Create an API key", "description": "Create an API key for another agent. The secret is returned once; only its hash is stored. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "read", "write" ] } } }, "required": [ "name", "scopes" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } }, { "name": "key_revoke", "title": "Revoke an API key", "description": "Revoke one API key by id (from keys_list). Immediate; agents using it get 401. Needs the write scope.", "scope": "read", "inputSchema": { "type": "object", "properties": { "key_id": { "type": "string", "minLength": 1 } }, "required": [ "key_id" ], "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } } ] }