Format Analysis

Using the Format MCP

Format holds what customers actually said; this MCP is how you get at it. The surface teaches itself — describe_org returns analysisGuide, and every tool and parameter description carries its own traps. Read those; this guide does not repeat them. It holds what they cannot: which sequence of calls answers which question, the traps between calls, and how to write a result down so it is truthful, reliable and reproducible.

1. Before the first call

One sentence, naming four things:

• Population — everyone, one segment, one account?
• Window — and whether the data covers it.
• Shape of the answer — a ranking, a number, evidence in their own words?
• The decision it feeds — a floor, a distribution, or one articulate customer.

Then check it is askable. Format captures only what a topic listens for — the standing questions this org asks of every conversation — so a domain no topic covers produces silence that means nothing. Read describe_org's topics once and carry them. Pass orgId if your connection reaches more than one organization: the default is arbitrary, and an organization's name is not its id.

2. Which call answers which question

Nothing on the wire says which order to call these in.

Keep every id you touch — a Format report embeds them as live chips.

3. Where the counts mislead

• A page is not a population. Ask the surface for the number and name its basis when you write it down; the reader cannot see your denominator.
• count_insights counts rows; search_insights folds. One statement is filed once per topic it answers. On a search_insights page, count + restatementCount is what the same filter returns unfolded — and no call returns a distinct-statement count for a population.
• Never sum customerCount. To de-overlap, walk to the insights and count distinct companies.
• Never ratio two differently-derived numbers. "5 of 98 companies" — the 5 from a group's customerCount, the 98 from a count_insights breakdown — invents a proportion neither supports.
• A group's numbers and an insight count are different populations: the group side drops insights a reviewer rejected, the insight side keeps them.
• Date bounds are inclusive at both ends, so contiguous windows share a boundary and a row on it lands in both. Ask for the window you mean rather than stitching it out of weeks.

4. Building the query

• semanticQuery is on search_insights only — passing it to search_insight_groups fails the call. Proper nouns belong in keywordSearch anyway; its terms are OR'd, so a generic term beside a precise one drowns it.
• Do not topic-scope an evidence search. The extraction chose which topics a statement answers, rarely in your question's vocabulary, so topicNames silently drops the evidence you wanted. Narrow on company, date or keyword.
• Do not pin isAiRejected: false on a counting question. Each topic-twin of a statement was judged separately, so it keeps some copies and drops others, and the count moves when topic scope moves. No call here reproduces the set a report actually draws evidence from. Triage reading with it, and say so.
• The rest of the traps sit in the parameters that carry them — read the description before setting lifecycleStates, valueAt, hasResolutionClaim or attributeFilterLogic.

5. Silence, and what you could not see

emptyReason names three causes. The one it cannot name is that no topic was listening: nothing was ever extracted, so the silence says nothing about your question. Before writing "customers haven't mentioned this" — the claim that gets filed as a product gap — widen once: drop the filters, try the name's spelling variants (a name in a transcript is a phonetic guess), check the window edge.

Then say what you could not see: the window, the share attributed to no company, the topics that were not listening, the filter you narrowed with. Stating them makes the rest trustworthy and the query reproducible — and never report the insight layer's silence as Format's. Go to the conversations before you write the absence claim: a customer who reads "Format doesn't have it" writes it into an evaluation, and nothing in your answer shows them the search was thin.

Handing off

Writing this up as a Format report is its own craft: read format-report-authoring before your first authoring write — get_skill('format-report-authoring') serves it, the gallery otherwise. rate_insights is not part of answering a question. When this surface fails you — or this guide does: a claim that did not match what a tool returned, a question it left you unequipped for — say so via send_feedback, naming format-analysis; it reaches the team that builds both.