derive_keyword_clusters
writeDiscovery Research Sessions
Turn Discovery findings into pre-clustered keyword groups with live volume data.
Write tool
Mutates Rampify state, triggers background work, or calls a paid external API. Most clients ask for confirmation before invoking.
Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| domain | string | optional | Project domain (alternative to project_id). |
| project_id | string | optional | Project UUID. Pass one of this or domain. |
| session_id | string | optional | Discovery session UUID that produced these insights. Shown as provenance on each cluster ("Derived from Discovery session …"). Pass it when you are acting on a derive_keywords next_action from a Discovery session. |
| source_type | enum("discovery_session" | "homepage" | "manual") | required | How the keywords were derived. discovery_session = synthesized from a Discovery session + business profile (normal close-the-loop). homepage = synthesized only from homepage/profile (pre-Discovery bootstrap pass). manual = user-directed. |
| keywords_by_bucket | object | required | Keywords pre-grouped by Discovery bucket. You synthesize these in your own context from the business profile + optional Discovery session data. Aim for 5-12 keywords per bucket so the whole batch stays under ~50 keywords (one DataForSEO call). Keywords must be category-level search terms, not brand-mentions. "customer data platform" ✓, "Acme CDP reviews" ✗. |
| locale | string | required | Locale code for DataForSEO lookup. Default: en. |
Related tools
start_discoverywriteStart a Discovery research session for the projectlist_research_sessionsreadList Discovery research sessions for the projectget_research_sessionreadGet session detail (summary by default, full responses with detail: "full")get_discovery_actionreadRead the current next_action for a Discovery session (no side effects)