cluster_keywords
ChatGPTGroup 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, becau…
create_project
ChatGPTCreate a new project in the user's Answer Socrates team (owners/admins only, within the plan's project limit). Free to call. Confirm the name with the user first. Archiving or deleting projects happens in the app, not here.
get_keywords
ChatGPTThe full keyword pull for a seed term in ONE request — everything people actually search around it, from live Google Suggest data: grouped Questions (who/what/why/how…), Prepositions (for/with/near…), Comparisons (vs/or/and…), time-based groups, PLUS the raw a–z Autocomplete expansions. Usually 500-900 keywords total. Call when the user asks for keywords, questions or content ideas; after trend results, OFFER it — e.g. "Want me to pull the full keyword set for <term>? (1 request)" — rather than fanning out uninvited. Present results with the total first, then per-group counts by their proper names (Questions, Prepositions, Comparisons, Autocomplete), and expand any group the user asks about.
get_rising_topics
ChatGPTTopic discovery: Google Trends' related queries for a seed topic, split into RISING (breakouts and fast climbers — value is % growth, 5000 means Breakout) and TOP (established related searches). Use it on a broad topic to find sub-topics and related searches worth comparing with get_trends. Data defaults to the US; pass a 2-letter country code for another market. 1 request per call.
get_trends
ChatGPT12-month Google Trends interest-over-time for one keyword (weekly points, relative 0-100 index, per country). Use it when the user asks what is popular, rising, seasonal or fading, or wants to compare keywords or countries: call it once per keyword or country and compare the series. Data defaults to the US; pass a 2-letter country code for another market. 1 request per call.
get_usage
ChatGPTCurrent plan, API quota ceilings, usage so far this billing period. Free to call — answering pricing or quota questions never costs a request.
get_youtube_keywords
ChatGPTThe full keyword pull for a seed term from live YouTube search autocomplete, in ONE request: what people type into YouTube's search box. Same shape as get_keywords: grouped Questions (who/what/why/how...), Prepositions (for/with/near...), Comparisons (vs/or/and...), time-based groups, plus the raw a-z Autocomplete expansions. Use it when the user asks for YouTube keywords or is planning videos, a YouTube channel or Shorts. It complements get_keywords (Google) rather than replacing it. Returns no search volumes. Data defaults to the US; pass a 2-letter country code for another market. 1 request per call.
list_projects
ChatGPTThe user's Answer Socrates projects (client/site workspaces in the app). Free to call. Use before saving research so the user can pick a destination.
save_to_project
ChatGPTSave a keyword list into an Answer Socrates project so it appears in the app for the whole team. Free to call — it stores research the user already pulled (pass the keywords from earlier get_keywords results). Offer this after a keyword pull: "Want me to save these to one of your projects?"