compare_runs
ChatGPTWhy a brand's numbers changed between two analyses. Every other tool here reports the CURRENT state. This is the only one that can explain a CHANGE, so use it whenever the question is "why did my score drop / go up since last time" — never answer that from get_visibility_summary alone. Read comparable FIRST. When it is false, notComparableReasons says why the two scores are not on the same scale — catalog_changed means the prompt set was edited and the baseline restarted, so the difference is NOT a result about the brand. Say that plainly instead of reporting a decline. Then regressed and improved name the individual questions and engines that moved (regressedCount is the true total when the list is capped), perception.dimensions carries the five funnel stages with their deltas, and topics / competitors carry the rollups. A prompt in rewordedPrompts was edited between the runs — a different question, so it has no comparable history. Never present it as a loss. A null delta means "not measured", never zero.
explain_prompt_change
ChatGPTWhy ONE question's rank moved — what the answer itself changed. Call this after compare_runs names a question that gained or lost ground. The prompt is identical between runs; the ANSWER is not, and this is the only tool that shows what the engine actually said, which brands it named, and which sources it cited each time. overtakenBy names the brands positioned ahead of this one NOW that were not ahead before — usually the real answer to "why did my rank drop". nowAheadOf is the same in reverse. When stillVisible is false the brand fell out of the answer entirely, so there is no rank to be overtaken in and namedInstead says who occupies the space. citations.gained / lost is the actionable half: a customer cannot make a model prefer them, but they can go and exist on the sources it reads. comparable: false means the pair was not measured in both runs — say so rather than inferring a cause. Every answer is the short stored summary, not the full response.
get_brand_perception
ChatGPTHow AI assistants PERCEIVE a brand, across the five funnel stages. Returns dimensions in funnel order — awareness, authority, recommendation, preference, trust — each with score (0-100 or null), measured, and how many answers it was judged over. Each stage also carries delta — the change against the most recent EARLIER run that measured that stage. A null delta means there is no earlier measurement to compare with, never "no change". This is different from get_visibility_summary: visibility is how OFTEN the brand appears, perception is WHAT is said about it. A stage with measured: false was not evaluated — report it as not measured and never as a score of 0.
get_competitors
ChatGPTWhich brands AI assistants name alongside (or instead of) this one. Returns competitors ordered by share of voice, each with domain, name, shareOfVoice and mentions, plus brandStats for the user's own brand so the two can be compared directly.
get_prompt_ranks
ChatGPTEvery prompt with the brand's text rank and source rank. Use this for "list my prompts with their ranks" and for "where am I ranked?" on a specific question. get_prompts answers what is being asked; this answers how the brand did. Returns prompts in catalog order, each with text, topic, isEnabled, textRank, sourceRank, measured and measuredAnswers, plus promptCount and measuredCount. textRank is the brand's position among the brands NAMED in the answer; sourceRank is its position among the sources the answer CITES. 1 is best. Each is the best position reached across the platforms that answered, and the two are independent — a brand can be cited without being named, or named without being cited. null is never 0 and never last place. A null textRank means the brand was not named; a null sourceRank means it was not cited. A row with measured: false was never run at all — report that as "not measured yet", never as a poor result.
get_prompts
ChatGPTThe questions a brand is measured on, grouped by topic. Returns topics, each with a name and its prompts (text plus isEnabled), and promptCount for the catalog total. Use it for "what are you actually asking the AI about my brand?".
get_suggestions
ChatGPTConcrete, stored recommendations for improving a brand's AI visibility. Returns suggestions (each with title, category, priority and description), hasSuggestions, and hiddenCount for any the workspace's plan withholds. Use this for "how do I improve?" — do NOT infer advice from scores. When hasSuggestions is false, say none have been generated yet rather than composing your own; and when hiddenCount is above zero, report only the number, never invent what the withheld ones say.
get_topics
ChatGPTThe topics a brand is measured on, and how it performs on each. Returns topics, each with name, visibility (percent of measured answers naming the brand) and responses (how many were measured). Useful for "where am I weak?" questions.
get_visibility_summary
ChatGPTHow visible a brand currently is in AI search. Returns visibilityScore (0-100), aiMentions, averageRank, hasData, and platformBreakdown per AI platform. These are the same numbers the Lens dashboard shows. When baselineReset is true the prompt catalog changed, so this score is NOT comparable to the one before it and visibilityDelta is null for that reason rather than for lack of history. Say so instead of reporting a change. For "why did it move", call compare_runs — this tool reports the current state only.
list_brands
ChatGPTList the brands in the user's Lens workspace. Use this first — the other tools need a brandId from here. Returns brands, each with brandId, domain and name.
