Group a keyword list into topics and score each keyword's search intent and funnel stage, in one call. For every keyword you get: intent (informational/navigational/commercial/transactional), funnel stage (TOFU/MOFU/BOFU), calibrated branded and local probabilities, and its topic cluster. Use it to turn a raw keyword pull into a content plan: which topics exist, and which stage of the funnel each one serves. Pass keywords from an earlier get_keywords call, or any list the user supplies. Takes 10-1000 keywords and runs for roughly 25 seconds on a full batch, so tell the user it is running before you call it.
This tool returns NO search volumes and takes no country — it is a classification and grouping tool, nothing more. If the user wants volumes, say plainly that this connection does not provide them rather than implying a number is missing.
NAME THE TOPICS YOURSELF — this is the single biggest thing you control. Pass a `topics` list of the groups you want the keywords sorted into. You have read the keywords; the fallback derives topic names by counting words in them, which cannot tell a subject from the subject area. On the seed "link building" that fallback offered "seo" as a topic and 59% of the keywords landed in it, because link building IS seo — a mistake you would not make. Read the keywords, decide the 5-20 real groups (specific sub-topics, product facets, buyer stages, audiences), and pass them. Then the labelling is your judgement and the per-keyword sorting is calibrated and consistent.
PROPOSE any exclusions, never make them silently. What decides the quality of a run is whether the list covers ONE subject, and a search term with a second meaning drags in another: "link building" returned property-management software ("building link login") and video games ("link build zelda"); "austin real estate" returned realtors surnamed Austin in other cities, Austin in Minnesota and Nevada, and a law firm. Dropping those costs fewer credits and groups better — but WHICH keywords count as off-topic is the user's call, not yours. They may genuinely want the other Austin. So in the same message where you confirm the credit cost, list what you would exclude, say why, give the count and the credits it saves, and let them decide. Do NOT tell the user that sending everything is equally safe. It is not. Measured on the full "austin real estate" pull: of 273 keywords that were about a different subject, only 44 (16%) ended up unclustered — the other 229 were absorbed into real topics, and "real estate agents and realtors" came back as the biggest group in the dataset at 156 keywords of which 130 were realtors named Austin working in other cities. A polluted group looks like the best opportunity on the page. So the unclustered bucket is NOT a safety net for off-topic keywords, and deciding what belongs is work that has to be done before the call, by the user, with you showing them the list.
The `seed` argument is optional and makes little difference — measured, the same keywords and topics scored 25% unclustered without it and 26% with it. It is light context for the intent classification, not a lever. The levers are the keyword list and the topic names.
Getting the topics right FIRST TIME matters, because a re-run is a new run: re-grouping the same keywords against different topic names charges the cluster credits again, exactly like any other call. Only a truly identical repeat (same keywords, same seed, same topics) is free. So think about the topic list before you call, and tell the user the credit cost before you spend it — do not treat this as something to iterate on cheaply.
Reading the result: `topics_source` tells you whether the names were yours or derived. `topics` is the answer — each one has EVERY keyword in it listed, a `funnel` split and a `dominant_intent`, and `unclustered` lists what had no confident home, in full. Nothing is ever truncated, so you can always show the user any cluster completely without another call or another credit. Present the groups WITH their keywords, not just topic names and counts, because the grouping is what the user paid for; lead with the biggest or most commercial clusters and name the keywords in each. Read `warnings` and relay them — one flags when a topic is so large it is really a catch-all rather than a genuine cluster.
`include_keywords: true` adds a flat row per keyword carrying its OWN intent, funnel stage and branded/local probabilities, rather than its group's. Leave it off unless the user wants per-keyword detail: it is 86% of the response, it repeats strings the groups already give you, and on a large run it can exceed the limit your own client places on a tool result — a 299-keyword run is 77,000 characters with it and about 11,000 without. The credits are charged before the response is sent, so a result too big for you to read has still been paid for. `include_csv` already contains all of that detail, so never set both.
SHOWING THE CLUSTERS. Every keyword of every group is already in the response, so none of this needs another call or another credit. Lead with a summary table — topic, count, funnel split — then offer the detail rather than dumping hundreds of keywords: "say which cluster you want and I'll list it". Expand any group in full the moment they ask. If they want a file, set `include_csv: true` and the result carries a ready CSV — one row per keyword, sorted by cluster, quoting handled — so hand that over rather than reformatting rows yourself. It is off by default because it repeats every keyword again. Setting it on a later call costs the credits again, so if the user is likely to want a file, ask before the run rather than after. The run is also saved into the user's Answer Socrates history, so the clusters can be opened in the app.
PRICING — THIS TOOL IS METERED DIFFERENTLY FROM EVERY OTHER TOOL HERE. It is priced in CLUSTER CREDITS, a separate monthly allowance from the request quota, and it spends NO requests at all: **1 cluster credit per KEYWORD**. 40 keywords = 40 cluster credits. 500 keywords = 500 cluster credits. Every other tool is the opposite — 1 request, no cluster credits — and the two pools never substitute for each other.
So clustering 500 keywords costs 500 cluster credits and nothing from the request quota. Never quote this tool as costing "1 request": it costs none, and quoting a request hides the real price. ALWAYS state the keyword count and therefore the cluster-credit cost, and get the user's agreement, BEFORE calling it. get_usage reports both balances. Assume every call costs the full amount: do NOT tell the user a re-run might be free. Changing the topics, adding or removing a keyword, or asking for the CSV afterwards is all new work at the full cluster-credit price.
View in the ChatGPT registry
AgentDiscoChatGPT Plugin Discovery Score
