Skip to main content
Glama
Sign In

Mark

by com.use-mark.app
OverviewDiscussionsAdmin

Get AI Visibility

get_ai_visibility
Read-onlyIdempotent

Shows how AI assistants see you: buyer questions (each with answerPages: the website posts linked to it with save_post buyerQuestionIds, label, status, live URL; empty means no page answers it yet), suggestions from People Also Ask, Search Console question searches and Reddit threads Google showed for audience-checked saved keywords (redditSuggestions: question, url, subreddit, keywords, total), AI search volume on each buyer question (aiSearchVolume: the monthly estimate summed across every active market with a location and language, null when none has one; aiSearchVolumeByMarket: marketId, market, country, aiSearchVolume, fetchedAt per market, highest first, then markets with no data, then markets not fetched yet with fetchedAt null; aiSearchVolumeFetchedAt: the newest fetch), traffic: pages AI assistants' bots fetched (not referrals or citations), where each bot row's hits split into verified (IP on the vendor's published list), checkable minus verified (failed the check) and hits minus checkable (no list, list not loaded, or no IP), and paths are the top 10 pages without fonts, images, styles or scripts, each with lastStatus: the HTTP status of Mark's latest daily check of that path on the primary site (404 means AI assistants can't find it; see get_site_audit aiCrawler404s), or null when unchecked or unknown; traffic.state is ready, no-posthog, no-signal (PostHog has received no events yet) or failed, and a failed read has reason: busy means PostHog didn't answer in time (it runs 3 queries at once per project and queues the rest), so try again in a minute; the PostHog connection is fine. error is any other failure, such as lost access, so check the PostHog connection. verificationSetup: the last result of Mark installing its IP check in your PostHog project (status ok or failed, reason limit, access or error, checkedAt; null before the first run or with no project), readiness, and AI answers: for the priority market's latest weekly check, how often ChatGPT, Gemini, AI Overview, AI Mode, Claude and Perplexity named or cited you (Claude and Perplexity are asked through their APIs with web search on, not the consumer apps, so their answers can differ from what people see in the apps), the top domains they cited, and up to 5 suggested competitors from the third-party sites they cite most (null with a reason when there is nothing yet), plus shareOfVoice: your share of mentions among you and your tracked competitors per engine in that run, and your share over the last 12 weekly runs, and nextAnswerCheck: how many checks the next weekly AI answer check sends (active questions × markets with a location and language × engines), the line Settings > Workspace shows. Does not change anything. Add any suggestion with save_strategy_item (kind buyer_question, fields.question). Related: refresh_ai_volume, save_strategy_item, check_site_readiness.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_ai_visibility"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
appUrlYes
trafficYes
readinessYes
suggestionsYes
answerEngineYes
buyerQuestionsYes
nextAnswerCheckYesWhat a new weekly AI answer check sends now. Counts what it would ask even while AI answer checks are off.
redditSuggestionsYes
verificationSetupYes
answerEngineReasonYes
searchConsoleSuggestionsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedOutput schema / properties / buyerQuestions / items / additionalProperties
      Added value: +{}
    • addedOutput schema / properties / buyerQuestions / items / properties
      Added value: +{
+  "aiSearchVolume": {
+    "description": "Monthly estimate summed across markets; null when none.",
+    "type": [
+      "number",
+      "null"
+    ]
+  },
+  "aiSearchVolumeByMarket": {
+    "description": "Every active market with a location and language, highest first, then no data, then not fetched.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "aiSearchVolume": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "country": {
+          "type": "string"
+        },
+        "fetchedAt": {
+          "description": "Null when not fetched for this market yet.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "market": {
+          "type": "string"
+        },
+        "marketId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "marketId",
+        "market",
+        "country",
+        "aiSearchVolume",
+        "fetchedAt"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "aiSearchVolumeFetchedAt": {
+    "type": [
+      "string",
+      "null"
+    ]
+  }
+}
    • addedOutput schema / properties / buyerQuestions / items / required
      Added value: +[
+  "aiSearchVolume",
+  "aiSearchVolumeByMarket",
+  "aiSearchVolumeFetchedAt"
+]
    • addedOutput schema / properties / buyerQuestions / items / type
      Added value: +"object"
  2. Changed1 schema field changed
    • changedOutput schema / properties / answerEngine / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "engines": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "cited": {
-              "anyOf": [
-                {
-                  "additionalProperties": false,
-                  "properties": {
-                    "count": {
-                      "type": "number"
-                    },
-                    "total": {
-                      "type": "number"
-                    }
-                  },
-                  "required": [
-                    "count",
-                    "total"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "count of total answers where the match is known; null when none"
-            },
-            "dataThrough": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "named": {
-              "anyOf": [
-                {
-                  "additionalProperties": false,
-                  "properties": {
-                    "count": {
-                      "type": "number"
-                    },
-                    "total": {
-                      "type": "number"
-                    }
-                  },
-                  "required": [
-                    "count",
-                    "total"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "count of total answers where the match is known; null when none"
-            },
-            "platform": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "platform",
-            "named",
-            "cited",
-            "dataThrough"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "market": {
-        "type": "string"
-      },
-      "shareOfVoice": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "engines": {
-                "items": {
-                  "additionalProperties": false,
-                  "properties": {
-                    "engine": {
-                      "description": "One engine, or all for the four summed.",
-                      "enum": [
-                        "all",
-                        "chatgpt_search",
-                        "gemini",
-                        "google_ai_overview",
-                        "google_ai_mode"
-                      ],
-                      "type": "string"
-                    },
-                    "rows": {
-                      "items": {
-                        "additionalProperties": false,
-                        "properties": {
-                          "cited": {
-                            "type": "number"
-                          },
-                          "citedTotal": {
-                            "type": "number"
-                          },
-                          "isYou": {
-                            "type": "boolean"
-                          },
-                          "name": {
-                            "type": "string"
-                          },
-                          "named": {
-                            "type": "number"
-                          },
-                          "namedTotal": {
-                            "type": "number"
-                          },
-                          "share": {
-                            "description": "Named answers over the sum of every listed brand's named answers; null when no brand was named.",
-                            "type": [
-                              "number",
-                              "null"
-                            ]
-                          }
-                        },
-                        "required": [
-                          "name",
-                          "isYou",
-                          "named",
-                          "namedTotal",
-                          "cited",
-                          "citedTotal",
-                          "share"
-                        ],
-                        "type": "object"
-                      },
-                      "type": "array"
-                    }
-                  },
-                  "required": [
-                    "engine",
-                    "rows"
-                  ],
-                  "type": "object"
-                },
-                "type": "array"
-              },
-              "weekOf": {
-                "description": "The Monday the newest run's ISO week starts.",
-                "type": "string"
-              },
-              "yourShareByWeek": {
-                "description": "All engines, oldest first; null is a week no brand was named.",
-                "items": {
-                  "additionalProperties": false,
-                  "properties": {
-                    "share": {
-                      "type": [
-                        "number",
-                        "null"
-                      ]
-                    },
-                    "weekOf": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "weekOf",
-                    "share"
-                  ],
-                  "type": "object"
-                },
-                "type": "array"
-              }
-            },
-            "required": [
-              "weekOf",
-              "engines",
-              "yourShareByWeek"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Share of mentions among you and your active tracked competitors over the last 12 finished runs; null with no tracked competitor or when the read failed."
-      },
-      "suggestedCompetitors": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "answers": {
-                  "type": "number"
-                },
-                "domain": {
-                  "type": "string"
-                },
-                "name": {
-                  "type": "string"
-                },
-                "questions": {
-                  "type": "number"
-                }
-              },
-              "required": [
-                "domain",
-                "name",
-                "answers",
-                "questions"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Up to 5 third-party domains the answers cite most that are not tracked: not yours, no active or untracked competitor, no .gov/.edu, Wikipedia, Reddit or YouTube. Track one with track_competitor. Null when the read failed."
-      },
-      "topCitedDomains": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "answers": {
-                  "type": "number"
-                },
-                "competitor": {
-                  "type": "string"
-                },
-                "domain": {
-                  "type": "string"
-                },
-                "questions": {
-                  "type": "number"
-                },
-                "source": {
-                  "enum": [
-                    "yours",
-                    "competitor",
-                    "third_party"
-                  ],
-                  "type": "string"
-                }
-              },
-              "required": [
-                "domain",
-                "source",
-                "answers",
-                "questions"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Top 10 domains the run's answers cited, most answers first; an answer counts once per domain. Null when the read failed."
-      },
-      "weekOf": {
-        "description": "The Monday the run's ISO week starts.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "market",
-      "weekOf",
-      "engines",
-      "topCitedDomains",
-      "shareOfVoice",
-      "suggestedCompetitors"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "engines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "cited": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "count": {
+                      "type": "number"
+                    },
+                    "total": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "count",
+                    "total"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "count of total answers where the match is known; null when none"
+            },
+            "dataThrough": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "named": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "count": {
+                      "type": "number"
+                    },
+                    "total": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "count",
+                    "total"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "count of total answers where the match is known; null when none"
+            },
+            "platform": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "platform",
+            "named",
+            "cited",
+            "dataThrough"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "market": {
+        "type": "string"
+      },
+      "shareOfVoice": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "engines": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "engine": {
+                      "description": "One engine, or all for the six summed.",
+                      "enum": [
+                        "all",
+                        "chatgpt_search",
+                        "gemini",
+                        "google_ai_overview",
+                        "google_ai_mode",
+                        "claude",
+                        "perplexity"
+                      ],
+                      "type": "string"
+                    },
+                    "rows": {
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "cited": {
+                            "type": "number"
+                          },
+                          "citedTotal": {
+                            "type": "number"
+                          },
+                          "isYou": {
+                            "type": "boolean"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "named": {
+                            "type": "number"
+                          },
+                          "namedTotal": {
+                            "type": "number"
+                          },
+                          "share": {
+                            "description": "Named answers over the sum of every listed brand's named answers; null when no brand was named.",
+                            "type": [
+                              "number",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "name",
+                          "isYou",
+                          "named",
+                          "namedTotal",
+                          "cited",
+                          "citedTotal",
+                          "share"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "engine",
+                    "rows"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "weekOf": {
+                "description": "The Monday the newest run's ISO week starts.",
+                "type": "string"
+              },
+              "yourShareByWeek": {
+                "description": "All engines, oldest first; null is a week no brand was named.",
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "share": {
+                      "type": [
+                        "number",
+                        "null"
+                      ]
+                    },
+                    "weekOf": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "weekOf",
+                    "share"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "weekOf",
+              "engines",
+              "yourShareByWeek"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Share of mentions among you and your active tracked competitors over the last 12 finished runs; null with no tracked competitor or when the read failed."
+      },
+      "suggestedCompetitors": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "answers": {
+                  "type": "number"
+                },
+                "domain": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "questions": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "domain",
+                "name",
+                "answers",
+                "questions"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Up to 5 third-party domains the answers cite most that are not tracked: not yours, no active or untracked competitor, no .gov/.edu, Wikipedia, Reddit or YouTube. Track one with track_competitor. Null when the read failed."
+      },
+      "topCitedDomains": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "answers": {
+                  "type": "number"
+                },
+                "competitor": {
+                  "type": "string"
+                },
+                "domain": {
+                  "type": "string"
+                },
+                "questions": {
+                  "type": "number"
+                },
+                "source": {
+                  "enum": [
+                    "yours",
+                    "competitor",
+                    "third_party"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "domain",
+                "source",
+                "answers",
+                "questions"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Top 10 domains the run's answers cited, most answers first; an answer counts once per domain. Null when the read failed."
+      },
+      "weekOf": {
+        "description": "The Monday the run's ISO week starts.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "market",
+      "weekOf",
+      "engines",
+      "topCitedDomains",
+      "shareOfVoice",
+      "suggestedCompetitors"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  3. Changed2 schema fields changed
    • addedOutput schema / properties / nextAnswerCheck
      Added value: +{
+  "additionalProperties": false,
+  "description": "What a new weekly AI answer check sends now. Counts what it would ask even while AI answer checks are off.",
+  "properties": {
+    "checks": {
+      "type": "number"
+    },
+    "engines": {
+      "type": "number"
+    },
+    "markets": {
+      "description": "Active markets with a location and language.",
+      "type": "number"
+    },
+    "questions": {
+      "type": "number"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "questions",
+    "markets",
+    "engines",
+    "checks",
+    "summary"
+  ],
+  "type": "object"
+}
    • changedOutput schema / required
      Previous value: -[
-  "buyerQuestions",
-  "readiness",
-  "redditSuggestions",
-  "searchConsoleSuggestions",
-  "suggestions",
-  "traffic",
-  "verificationSetup",
-  "answerEngine",
-  "answerEngineReason",
-  "appUrl"
-]New value: +[
+  "buyerQuestions",
+  "readiness",
+  "redditSuggestions",
+  "searchConsoleSuggestions",
+  "suggestions",
+  "traffic",
+  "verificationSetup",
+  "answerEngine",
+  "answerEngineReason",
+  "nextAnswerCheck",
+  "appUrl"
+]
  4. Changed2 schema fields changed
    • addedOutput schema / properties / redditSuggestions
      Added value: +{}
    • changedOutput schema / required
      Previous value: -[
-  "buyerQuestions",
-  "readiness",
-  "searchConsoleSuggestions",
-  "suggestions",
-  "traffic",
-  "verificationSetup",
-  "answerEngine",
-  "answerEngineReason",
-  "appUrl"
-]New value: +[
+  "buyerQuestions",
+  "readiness",
+  "redditSuggestions",
+  "searchConsoleSuggestions",
+  "suggestions",
+  "traffic",
+  "verificationSetup",
+  "answerEngine",
+  "answerEngineReason",
+  "appUrl"
+]
  5. Changed2 schema fields changed
    • addedOutput schema / properties / verificationSetup
      Added value: +{
+  "anyOf": [
+    {
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "checkedAt": {
+              "type": "string"
+            },
+            "status": {
+              "const": "ok",
+              "type": "string"
+            }
+          },
+          "required": [
+            "checkedAt",
+            "status"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "checkedAt": {
+              "type": "string"
+            },
+            "reason": {
+              "enum": [
+                "limit",
+                "access",
+                "error"
+              ],
+              "type": "string"
+            },
+            "status": {
+              "const": "failed",
+              "type": "string"
+            }
+          },
+          "required": [
+            "checkedAt",
+            "reason",
+            "status"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • changedOutput schema / required
      Previous value: -[
-  "buyerQuestions",
-  "readiness",
-  "searchConsoleSuggestions",
-  "suggestions",
-  "traffic",
-  "answerEngine",
-  "answerEngineReason",
-  "appUrl"
-]New value: +[
+  "buyerQuestions",
+  "readiness",
+  "searchConsoleSuggestions",
+  "suggestions",
+  "traffic",
+  "verificationSetup",
+  "answerEngine",
+  "answerEngineReason",
+  "appUrl"
+]
  6. Changed4 schema fields changed
    • addedOutput schema / properties / answerEngine / anyOf
      Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "engines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "cited": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "count": {
+                      "type": "number"
+                    },
+                    "total": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "count",
+                    "total"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "count of total answers where the match is known; null when none"
+            },
+            "dataThrough": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "named": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "count": {
+                      "type": "number"
+                    },
+                    "total": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "count",
+                    "total"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "count of total answers where the match is known; null when none"
+            },
+            "platform": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "platform",
+            "named",
+            "cited",
+            "dataThrough"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "market": {
+        "type": "string"
+      },
+      "shareOfVoice": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "engines": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "engine": {
+                      "description": "One engine, or all for the four summed.",
+                      "enum": [
+                        "all",
+                        "chatgpt_search",
+                        "gemini",
+                        "google_ai_overview",
+                        "google_ai_mode"
+                      ],
+                      "type": "string"
+                    },
+                    "rows": {
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "cited": {
+                            "type": "number"
+                          },
+                          "citedTotal": {
+                            "type": "number"
+                          },
+                          "isYou": {
+                            "type": "boolean"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "named": {
+                            "type": "number"
+                          },
+                          "namedTotal": {
+                            "type": "number"
+                          },
+                          "share": {
+                            "description": "Named answers over the sum of every listed brand's named answers; null when no brand was named.",
+                            "type": [
+                              "number",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "name",
+                          "isYou",
+                          "named",
+                          "namedTotal",
+                          "cited",
+                          "citedTotal",
+                          "share"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "engine",
+                    "rows"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "weekOf": {
+                "description": "The Monday the newest run's ISO week starts.",
+                "type": "string"
+              },
+              "yourShareByWeek": {
+                "description": "All engines, oldest first; null is a week no brand was named.",
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "share": {
+                      "type": [
+                        "number",
+                        "null"
+                      ]
+                    },
+                    "weekOf": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "weekOf",
+                    "share"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "weekOf",
+              "engines",
+              "yourShareByWeek"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Share of mentions among you and your active tracked competitors over the last 12 finished runs; null with no tracked competitor or when the read failed."
+      },
+      "suggestedCompetitors": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "answers": {
+                  "type": "number"
+                },
+                "domain": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "questions": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "domain",
+                "name",
+                "answers",
+                "questions"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Up to 5 third-party domains the answers cite most that are not tracked: not yours, no active or untracked competitor, no .gov/.edu, Wikipedia, Reddit or YouTube. Track one with track_competitor. Null when the read failed."
+      },
+      "topCitedDomains": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "answers": {
+                  "type": "number"
+                },
+                "competitor": {
+                  "type": "string"
+                },
+                "domain": {
+                  "type": "string"
+                },
+                "questions": {
+                  "type": "number"
+                },
+                "source": {
+                  "enum": [
+                    "yours",
+                    "competitor",
+                    "third_party"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "domain",
+                "source",
+                "answers",
+                "questions"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Top 10 domains the run's answers cited, most answers first; an answer counts once per domain. Null when the read failed."
+      },
+      "weekOf": {
+        "description": "The Monday the run's ISO week starts.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "market",
+      "weekOf",
+      "engines",
+      "topCitedDomains",
+      "shareOfVoice",
+      "suggestedCompetitors"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedOutput schema / properties / answerEngine / type
      Removed value: -"string"
    • addedOutput schema / properties / answerEngineReason
      Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / required
      Previous value: -[
-  "buyerQuestions",
-  "readiness",
-  "searchConsoleSuggestions",
-  "suggestions",
-  "traffic",
-  "answerEngine",
-  "appUrl"
-]New value: +[
+  "buyerQuestions",
+  "readiness",
+  "searchConsoleSuggestions",
+  "suggestions",
+  "traffic",
+  "answerEngine",
+  "answerEngineReason",
+  "appUrl"
+]
  7. Changed2 schema fields changed
    • addedOutput schema / properties / searchConsoleSuggestions
      Added value: +{}
    • changedOutput schema / required
      Previous value: -[
-  "buyerQuestions",
-  "readiness",
-  "suggestions",
-  "traffic",
-  "answerEngine",
-  "appUrl"
-]New value: +[
+  "buyerQuestions",
+  "readiness",
+  "searchConsoleSuggestions",
+  "suggestions",
+  "traffic",
+  "answerEngine",
+  "appUrl"
+]
  8. First observed

TDQS

A3.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint and idempotentHint already covering the safety profile, the description adds substantial behavior the annotations cannot: traffic.state values including no-posthog and no-signal, the distinction between 'busy' (PostHog timed out, retry in a minute) and 'error' (lost access, check the connection), null semantics for unfetched market volumes, and the caveat that Claude/Perplexity results come from APIs rather than consumer apps. These are exactly the failure and interpretation cues an agent needs and they cannot be derived from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The body is effectively one enormous run-on block with deeply nested parentheticals (answerPages, aiSearchVolumeByMarket, the verified/checkable/hits decomposition), making it hard to scan. Since an output schema already exists, most of the field-by-field enumeration is redundant, and the genuinely valuable parts — the failure-state guidance and the related-tool routing — are buried at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter dashboard read with a full output schema, the description is more than complete: it covers data staleness (fetchedAt), degraded states, and cross-references to get_site_audit for 404 context. Nothing an agent needs to interpret the response is missing, though the completeness is achieved through bulk rather than structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing to disambiguate. The extensive field explanation is return-value semantics rather than parameter help, which is already covered by the output schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific and vivid framing — 'Shows how AI assistants see you' — then enumerates the concrete payload (buyer questions, suggestions, AI search volume, bot traffic, verification setup, AI answers/share of voice). It is clearly distinguishable from siblings like check_ai_assistant_tracking or get_site_audit by naming them in context, but the purpose statement is buried under output field enumeration rather than stated crisply up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Does not change anything' plus a 'Related:' list (refresh_ai_volume, save_strategy_item, check_site_readiness) gives some routing signal, and it names save_strategy_item for adding a suggestion. However, it never states when to call this dashboard versus sibling reads such as get_buyer_question_answers, get_competitor_ai_detail, or check_ai_assistant_tracking, so the choice is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Mark toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources