{"capabilities":{"extendedAgentCard":false,"pushNotifications":false,"streaming":false},"defaultInputModes":["application/json"],"defaultOutputModes":["application/json","text/plain"],"description":"Heading measures how AI assistants answer questions about a brand: which prompts are tracked, how often each brand is mentioned, what the answers actually say, which sources they cite, and how the brand is depicted. Its agent surface is an MCP server and a read-only REST API; neither speaks the A2A method set, and the protocol binding on each interface below says which one it does speak. The MCP server also has writes, which act as the person its credential belongs to; the REST API changes nothing, and only brands on a paid plan or a trial return data.","documentationUrl":"https://docs.useheading.com","iconUrl":"https://www.useheading.com/icon.png","name":"Heading","preferredTransport":"MCP","protocolVersion":"1.0","provider":{"organization":"Heading","url":"https://www.useheading.com"},"securityRequirements":[{"schemes":{"bearer":{"list":[]}}}],"securitySchemes":{"bearer":{"httpAuthSecurityScheme":{"bearerFormat":"A Heading API key, or an OAuth 2.1 access token minted for the MCP resource","description":"Send the credential as an Authorization header. OAuth discovery starts at the protected resource metadata, https://mcp.useheading.com/.well-known/oauth-protected-resource/mcp; the whole flow, both credentials and what each one may read are written out at https://www.useheading.com/auth.md.","scheme":"Bearer"}}},"skills":[{"description":"The brands this connection can work on, each with its id, name and domains, its profile (summary, positioning, description), the AI platforms it is tracked on, its collection cadence, its primary, measured and target markets, and its prompt quota (used and total). Every other brand tool takes a brandId, and this is where the ids come from: call it first in any conversation that has not already established which brand is in scope. A brand missing from this list cannot be reached through any tool.","id":"list-brands","name":"List brands","tags":["heading","read-only","brands"]},{"description":"The brand's tracked prompts: the questions Heading asks the AI platforms every collection day. Each row carries the prompt's id, its exact text, its market, its query type (branded or unbranded), its status, its tags, its target page and its figures across every tracked platform on its latest measured UTC day (Mentioned %, mentions, citations, average rank among tracked brands, sentiment, and the day itself), which are the figures the Prompts page shows. An unmeasured prompt states null, never zero. The answer also states how many prompts the brand holds in each status and its prompt quota (used, total and free slots), whatever the filters. Visibility is measured over the active prompts, so this list defines what every figure means. Filter by status, tags, market, query type or text; page with limit and cursor. Use it before adding prompts, to see what is tracked and how many slots are free, and to find the prompt ids other tools take.","id":"list-prompts","name":"List prompts","tags":["heading","read-only","prompts"]},{"description":"The brand's tags and tag folders, as the dashboard's tag manager shows them. A tag is a label on prompts, used to segment the portfolio (by topic, product line, funnel stage); a prompt can carry several. Each tag row carries its id, its name, its folder (or null), how many of the brand's prompts carry it and whether it is a system tag. Every folder is listed in the answer whatever the page, with its order and how many tags it holds. Tags come in folder order, then by name, with tags in no folder last. Filter by folder or by text in the name; page with limit and cursor. Use it to find the tag ids that list_prompts, create_prompts and saved views take, and before creating tags so a name is not repeated.","id":"list-tags","name":"List tags","tags":["heading","read-only","tags"]},{"description":"The brand's saved views: named filters the team set up in the dashboard to focus on one segment of the portfolio, such as one market and a few tags. Each view carries its id, its name and its filters exactly as get_visibility_report takes them (market, tagIds, queryType: spread them into its arguments), with the market and tags also named and how the view matches its tags. A view saved with no query type reads all prompts, and its filters say queryType all. The report matches tags by folder; a view whose several tags match by any or all reads a different set, and reportMatchesView says so. The filters are the view as the dashboard applies it: a tag the brand has since deleted is listed under missingTagIds and left out, a market with no tracked prompts is left out (market.measured false), and a view with nothing left says so in reportNote. Views come by name. Use it to report on the segments the team already uses, or before creating a view so a name is not repeated.","id":"list-views","name":"List views","tags":["heading","read-only","views"]},{"description":"The brand's tracked competitors and the competitor candidates waiting on a decision. Each competitor carries its id, its name, the tracked name answers are matched on, its aliases, its own domains, when it started being tracked, and whether it is tracked for this brand or for every brand in the team. Every comparison figure (Mention share, the leaderboard, rank among tracked brands) is measured over this set, so it says what those figures mean. Each candidate is a business the competitor passes found in the brand's answers or market research: its id, name, domain, the check's verdict, confidence and evidence, where it came from, and how many answers named or cited it. Candidates the team rejected or the check judged not a competitor are left out unless includeNotCompetitors is true. This tool carries no visibility figures: for each competitor's share of answers and rank, call get_visibility_report with breakdown brand; for the answers that name it, list_answers with its id in competitorIds. Pages over the…","id":"list-competitors","name":"List competitors","tags":["heading","read-only","competitors"]},{"description":"The brand's visibility in AI answers, as the visibility page measures it, over a UTC day range: Mentioned %, Cited %, Mention share, Citation share, average mentions, average citations, responses, average rank among tracked brands and average sentiment. One call answers one question: no breakdown gives a summary; breakdown date gives a series; breakdown brand gives the leaderboard of the brand and its tracked competitors; platform, prompt, tag and market split the figures; up to three combine (such as brand and platform). Filter by tags (OR within a tag folder, AND across folders, as the page does), market, query type, platforms and prompts. Set compare for the previous period of the same length: every row then carries its previous figures and its change. Defaults: the last 28 days and unbranded prompts, which is what the visibility page opens on. A figure Heading did not measure is null with a reason, never zero. A range that opens before daily tracking began is clamped, and notes say so; a brand on no…","id":"get-visibility-report","name":"Get visibility report","tags":["heading","read-only","visibility","report"]},{"description":"The figure a metric key result is judged on, exactly as the objective page charts it: visibility, the share of one UTC day's tracked answers that mention the brand, for one scope (query type, and optionally a market and tags), on the latest measured day by the page's own rule (for a brand whose plan lapsed, its last collected day). Read it to set a baseline before create_objectives or update_objectives: write its reading's value and day into measureConfig.baseline and its scope into measureConfig.scope, unchanged, so the key result is judged on the same measure over the same prompts. Read it again with a key result's own scope and its baseline day as sinceDay to verify that key result: the reading is then the key result's current figure on the objective page. It is a different figure from get_visibility_report, whose range figures pool many days; never compare one with the other. A scope with no measured day answers a null reading with a reason, never zero.","id":"get-objective-measure","name":"Get objective measure","tags":["heading","read-only","objective","measure"]},{"description":"How AI depicts the brand, as the Perception page measures it, over a UTC day range. Perception is measured on dimensions: ten spine qualities every brand shares plus qualities generated for the brand's category, and every tracked brand is judged on the same dimensions, so a dimension a rival holds and the brand does not is visible. The summary is the brand's own: overall sentiment, focused dimensions led and the strongest quality. breakdown dimension lists every dimension with the brand's rate, the best compared competitor's rate and the gap, widest deficit first, as the page ranks them; breakdown brand lists the brand and every tracked competitor with their own sentiment and focus figures (the page's brand switcher); both together give each brand's rate on each dimension. Focused dimensions are flagged, never filtered: every dimension is readable. Retired dimensions are listed with the day they retired and measured over the days before it. A brand with fewer than 10 assessed answers reads null with the…","id":"get-perception-report","name":"Get perception report","tags":["heading","read-only","perception","report"]},{"description":"The sources AI platforms cite in their answers to the brand's tracked prompts, as the Sources page measures them, over a UTC day range. level domain (the default) lists cited domains with Used % and average citations; level url lists cited pages with Citation % and Retrieval %. Every row says whether the domain is the brand's own, and carries two flags over the whole range: gap (cited in answers that name a tracked competitor and in none that name the brand, over this report's own answers: co-citation in answers, never a claim about what the source's pages say, and not the Sources page's Gaps tab figure) and rising (its citation rate rose against the period just before). Filter by tags (OR within a tag folder, AND across folders), market and query type; at level url also by one platform and page format. Break down by date (domains by month; pages by day, week or month) or, at level url, by each platform the brand tracks. Set compare for the previous period of the same length. Defaults: the last 28 days and…","id":"get-sources-report","name":"Get sources report","tags":["heading","read-only","sources","report"]},{"description":"The AI platform answers collected for the brand's active prompts, newest first, as the visibility page lists them: the evidence every visibility figure is computed from. Each row carries the answer's id, the prompt it answers (id and text), the platform, the UTC day it counts on, whether it names the brand, the brand's rank among tracked brands (null when not named), the brand's sentiment (null when not scored), the tracked competitors it names with their ranks, how many sources it cites, and a short plain-text excerpt. Filter by UTC day range (default the last 28 days, clamped to the day daily tracking began), platforms, prompts, market, tags, query type, the tracked competitors named, or to answers that name the brand. Use it for \"what is ChatGPT saying about us\", to find the answers behind a score that moved, or to pick answers to read in full with get_answer. Page with limit and cursor; a cursor only works with the filters it came from.","id":"list-answers","name":"List answers","tags":["heading","read-only","answers"]},{"description":"One collected AI answer in full, by the id list_answers returns: the full answer text exactly as the platform gave it (markdown, never shortened), the prompt it answers, the platform, the UTC day and time it was collected and how it was fetched, every source it cites (URL, domain, title where the platform gave one, and whether the domain is one of the brand's sites), and every tracked brand it names (the brand and its tracked competitors) with each one's rank among tracked brands and sentiment. Use it to quote an answer, to see who an answer recommends instead of the brand, or to check which pages it cites. An answer to a prompt this brand does not track answers not_found.","id":"get-answer","name":"Get answer","tags":["heading","read-only","answer"]},{"description":"What changed what the brand's scores measure, one entry per UTC day, newest day first: prompts added, tracked, reactivated, paused, removed, suggested or rejected (with counts and a sample of each), AI platforms added to or removed from the tracked set, and competitors added to or removed from the tracked set (by name). Each day is netted, so a change undone the same day is not listed, and states the active prompt count at the end of the day, which is the set that day's visibility is measured over. Visibility is measured over the active prompts and the tracked platforms, and every comparison over the tracked competitors, so a score that moves on one of these days may have moved because the measurement changed, not the brand's performance. Read it before explaining any movement in a score; the days line up with the change markers on the visibility chart. A competitor removed and added back on one day nets to nothing here, although the removal dropped its earlier mention history. Covers the last 30 days by…","id":"list-changes","name":"List changes","tags":["heading","read-only","changes"]},{"description":"The brand's prompt research list for one market: candidate questions that sources offered the brand (the index of AI answers, Search Console, questions generated from the brand profile, an uploaded list) before anyone tracks them. Each candidate carries its id, exact text, status, topic, the judge's relevance, its duplicate group (other wordings of the same question, led by the strongest), its flags, its query type, every source with the figures it gave and the UTC day it gave them, the candidates a converted question was written from, its target page and the team's note. A null figure means that source gave no figure, never zero. Omit view for the Inbox and the Shortlist together, the questions the team has not decided on; tracked lists the candidates already added. The answer also states every market's counts, the topics in use, how many candidates carry each flag, the market's recent pulls (a pending pull lands here when it finishes), and the team's AI & data credits with what each source costs. Order is…","id":"list-prompt-candidates","name":"List prompt candidates","tags":["heading","read-only","prompt","candidates"]},{"description":"What a pull_prompt_candidates call with these arguments would cost now, in credits from the team's AI & data credits, and whether the balance lets it start. Changes nothing and spends nothing. An ai_index pull reads the index of AI answers for about 30 credits (state fetch), or costs nothing when anyone searched that topic in the last 30 days (cached) or a read of it is already running (in_flight). A generate run is priced by how many it writes (priced: 2 for 10, 3 for 20, 6 for 40). search_console and your_list are free. Tell the person the cost, then pass credits as acceptQuote to pull_prompt_candidates. A quote is not held: the pull checks the price again and refuses as conflict if it went up.","id":"get-pull-quote","name":"Get pull quote","tags":["heading","read-only","pull","quote"]},{"description":"The brand's Context tree: the folders and markdown documents the team keeps about the business, which Heading's own prompt generation, perception and setup read for brand facts. Each row carries the item's id, title, kind (folder or document), the folder it sits in, its position among that folder's items (the order the Context page shows, and the index move_context_docs takes), its depth, its version, when it last changed and a document's length; rows come in tree order, each folder followed by what it holds. Bodies are not included: get_context_doc reads one in full. The answer also carries Confidence, how well Heading understands the business as last assessed from these documents: a score and band, and per dimension (what they sell, audience, positioning, competitors, geography, recognition) the coverage grade with the questions and sections that would deepen it, weakest first. Confidence is read from the last assessment and never computed here, so it is null with a reason when nothing is assessed, and a…","id":"list-context-docs","name":"List context docs","tags":["heading","read-only","context","docs"]},{"description":"One context document in full: its title, its whole markdown body with no cap, its version, when it was created and last changed, and its path (the folders it sits in, top level first). Take the id from list_context_docs. Send the version it answers with update_context_docs, so an edit someone else made since is never overwritten. A folder id answers invalid_input, since a folder has no body; list_context_docs lists what it holds.","id":"get-context-doc","name":"Get context doc","tags":["heading","read-only","context","doc"]},{"description":"The brand's task board and its live plans, with the ids the task, plan and comment tools take. Each task row carries its id, title, full description, status (backlog, todo, in_progress, done, canceled), priority, assignee (name and email), due day, plan, labels and when it was created, changed and completed. The board's own scope: every review-accepted task on a live plan or with no plan, as the Tasks page shows it. The answer also states how many tasks the board holds in each status and lists every plan that is not archived, with its status, the objective it serves and its open and total task counts, whatever the filters. Filter tasks by status, plan, objective (tasks on plans serving it), assignee or title; page with limit and cursor. Read it before creating work, so an open task that already covers a fix is updated with update_tasks rather than created again.","id":"list-tasks","name":"List tasks","tags":["heading","read-only","tasks"]},{"description":"The brand's objectives: the directions the team has committed to, each proven by one to four key results. Each objective carries its id, title, description, status (active, achieved, not_achieved, abandoned), target day, when it was set and closed, the live plans serving it, and its key results in order. Each key result carries its id, its exact statement, how it can be proven (metric, web or unverifiable, with the reason), its stored measure config with its scope (market, tags, query type), baseline and target, how many verdicts it holds and its newest verdict. Read it before setting or changing an objective, and before recording a verdict, which takes the key result's id and exact statement. Filter by status; page with limit and cursor.","id":"list-objectives","name":"List objectives","tags":["heading","read-only","objectives"]},{"description":"The brand's latest Agent readiness Run: whether the brand's own public website can be found, read and used by the machines that produce AI answers. Answers the 0 to 100 score and its grade (A+ to F), the four weighted Layers (Discovery 20, Access 30, Usability 40, Payments 10) with the points each earned, the fixes ranked by the points a full pass would add, and every Probe with its outcome, the URL it fetched, what it observed and what to change. These are the figures the brand's Agent readiness page shows. Each Probe is one HTTP observation a person can repeat; none states a cause or a forecast, and nothing here joins visibility data. A brand never measured answers run null; a Run that could not reach the site answers no Probes and a null score, never a clean result; a Layer nothing applied to has null points, never zero. Use it when someone asks whether their site is ready for AI agents, or before proposing site-side work: it is the only tool that measures the brand's own site. Filter the Probes by…","id":"get-agent-readiness","name":"Get agent readiness","tags":["heading","read-only","agent","readiness"]},{"description":"The brand's Traffic page as data, for one UTC day range: what AI visibility led to, and which AI crawlers fetched the brand's site. Answers Google Analytics figures (AI-referred sessions, leads, revenue, conversion rate, each with its change against the equal-length range before), leads from every connected source and each source's own count, the lead webhook's state and recent leads, Google Search figures from Search Console (clicks, impressions, CTR, position, top queries and pages), a daily series of visibility beside AI sessions and search crawls, and crawl activity from the brand's own server logs: requests by category (Search, Retrieval, Training, never added into one measure), the verified share, what the site answered, each crawler, the most fetched URLs, pages people use that no search crawler fetched, and AI arrivals in the logs beside Analytics sessions. A source that is not connected answers null with a reason, never 0. Log entries and Analytics sessions are different units and are never added…","id":"get-traffic-report","name":"Get traffic report","tags":["heading","read-only","traffic","report"]}],"supportedInterfaces":[{"protocolBinding":"MCP","protocolVersion":"1.0","url":"https://mcp.useheading.com/mcp"},{"protocolBinding":"REST","protocolVersion":"1.0","url":"https://api.useheading.com/v1"}],"url":"https://mcp.useheading.com/mcp","version":"1.0.0"}