Cluster Tools

7 MCP tools for content cluster management. Design topic clusters from audit gaps, create interlinked article groups, and manage the cluster lifecycle.

aeo_get_cluster_context

Get audit gaps, MISS queries, existing content, voice profile, and CMS content for a domain. This is the starting point for designing a content cluster - it surfaces everything needed to identify which gaps the cluster should target.

Parameters

Name	Type	Required	Description
`domain`	string	Required	Domain to get cluster context for (e.g., "understoodcare.com")

Example

json

aeo_get_cluster_context({ domain: class="code-string">"understoodcare.com" })

Response

response

{
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"audit": {
    class="code-string">"overall_score": 82,
    class="code-string">"version": 5,
    class="code-string">"verdict": class="code-string">"Good AEO readiness"
  },
  class="code-string">"weak_criteria": [
    { class="code-string">"criterion": class="code-string">"Original Data & Research", class="code-string">"score": 7, class="code-string">"id": 8 },
    { class="code-string">"criterion": class="code-string">"Comparison Tables", class="code-string">"score": 6, class="code-string">"id": 15 },
    { class="code-string">"criterion": class="code-string">"Content Freshness Signals", class="code-string">"score": 5, class="code-string">"id": 22 }
  ],
  class="code-string">"visibility": {
    class="code-string">"engine": class="code-string">"chatgpt",
    class="code-string">"score": 72,
    class="code-string">"miss_queries": [
      class="code-string">"best home health care agencies in New York",
      class="code-string">"CDPAP vs traditional home care cost comparison"
    ],
    class="code-string">"partial_queries": [
      class="code-string">"what is CDPAP program"
    ]
  },
  class="code-string">"existing_articles": [
    { class="code-string">"slug": class="code-string">"what-is-cdpap", class="code-string">"title": class="code-string">"What Is CDPAP?", class="code-string">"word_count": 1850 },
    { class="code-string">"slug": class="code-string">"home-care-vs-nursing-home", class="code-string">"title": class="code-string">"Home Care vs Nursing Home", class="code-string">"word_count": 2200 }
  ],
  class="code-string">"voice_profile": {
    class="code-string">"name": class="code-string">"Care Team Voice",
    class="code-string">"tone": class="code-string">"conversational",
    class="code-string">"industry": class="code-string">"home health care"
  },
  class="code-string">"cms_content": [
    { class="code-string">"slug": class="code-string">"what-is-cdpap", class="code-string">"title": class="code-string">"What Is CDPAP?" },
    { class="code-string">"slug": class="code-string">"home-care-vs-nursing-home", class="code-string">"title": class="code-string">"Home Care vs Nursing Home" }
  ],
  class="code-string">"existing_clusters": [
    { class="code-string">"id": class="code-string">"cl_abc123", class="code-string">"name": class="code-string">"CDPAP Education", class="code-string">"status": class="code-string">"in_progress", class="code-string">"article_count": 5 }
  ]
}

Always call aeo_get_cluster_context before creating a cluster. The weak_criteria and visibility MISS queries tell you exactly which gaps the cluster should fill.

aeo_create_cluster

Create a content cluster with a hub article and child articles targeting specific audit gaps. Exactly one article must have role: "hub" and a minimum of two articles total is required. The cluster is created in planned status.

Parameters

Name	Type	Required	Description
`domain`	string	Required	Target domain for the cluster
`name`	string	Required	Cluster name (e.g., "CDPAP Education Cluster")
`gap_source`	string	Optional	Where the gap was identified (e.g., "audit_v5", "visibility_chatgpt")
`shared_context`	string	Optional	Context shared across all articles (brand voice, key data points)
`interlink_map`	object	Optional	Cross-linking rules between articles (slug-to-slug mapping)
`target_score_delta`	number	Optional	Expected AEO Site Rank improvement from this cluster
`articles`	array	Required	Article definitions (min 2, exactly 1 hub). Each: { title, slug, role, target_criteria, outline, word_count_target }

Example

json

aeo_create_cluster({
  domain: class="code-string">"understoodcare.com",
  name: class="code-string">"Home Health Aide Hiring Cluster",
  gap_source: class="code-string">"audit_v5",
  target_score_delta: 8,
  shared_context: class="code-string">"Understood Care operates in NY/NJ. All articles should reference state-specific Medicaid programs.",
  interlink_map: {
    class="code-string">"how-to-hire-home-health-aide": [class="code-string">"hha-vs-pca-differences", class="code-string">"hha-certification-requirements"],
    class="code-string">"hha-vs-pca-differences": [class="code-string">"how-to-hire-home-health-aide"],
    class="code-string">"hha-certification-requirements": [class="code-string">"how-to-hire-home-health-aide", class="code-string">"hha-vs-pca-differences"]
  },
  articles: [
    {
      title: class="code-string">"How to Hire a Home Health Aide: Complete Guide",
      slug: class="code-string">"how-to-hire-home-health-aide",
      role: class="code-string">"hub",
      target_criteria: [class="code-string">"original-data", class="code-string">"qa-content", class="code-string">"comparison-tables"],
      outline: class="code-string">"Cover cost, qualifications, Medicaid coverage, interview questions",
      word_count_target: 6000
    },
    {
      title: class="code-string">"HHA vs PCA: Key Differences Explained",
      slug: class="code-string">"hha-vs-pca-differences",
      role: class="code-string">"child",
      target_criteria: [class="code-string">"comparison-tables", class="code-string">"qa-content"],
      outline: class="code-string">"Scope of work, certification, cost, when to choose each",
      word_count_target: 3000
    },
    {
      title: class="code-string">"Home Health Aide Certification Requirements by State",
      slug: class="code-string">"hha-certification-requirements",
      role: class="code-string">"child",
      target_criteria: [class="code-string">"original-data", class="code-string">"content-freshness"],
      outline: class="code-string">"NY, NJ, CT requirements, training hours, renewal process",
      word_count_target: 2800
    }
  ]
})

Response

response

{
  class="code-string">"cluster_id": class="code-string">"cl_7f3a2b1c",
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"name": class="code-string">"Home Health Aide Hiring Cluster",
  class="code-string">"articles": [
    {
      class="code-string">"id": class="code-string">"ca_a1b2c3d4",
      class="code-string">"title": class="code-string">"How to Hire a Home Health Aide: Complete Guide",
      class="code-string">"slug": class="code-string">"how-to-hire-home-health-aide",
      class="code-string">"role": class="code-string">"hub",
      class="code-string">"status": class="code-string">"planned"
    },
    {
      class="code-string">"id": class="code-string">"ca_e5f6g7h8",
      class="code-string">"title": class="code-string">"HHA vs PCA: Key Differences Explained",
      class="code-string">"slug": class="code-string">"hha-vs-pca-differences",
      class="code-string">"role": class="code-string">"child",
      class="code-string">"status": class="code-string">"planned"
    },
    {
      class="code-string">"id": class="code-string">"ca_i9j0k1l2",
      class="code-string">"title": class="code-string">"Home Health Aide Certification Requirements by State",
      class="code-string">"slug": class="code-string">"hha-certification-requirements",
      class="code-string">"role": class="code-string">"child",
      class="code-string">"status": class="code-string">"planned"
    }
  ],
  class="code-string">"status": class="code-string">"planned"
}

Exactly one article must have role: "hub". The hub is the comprehensive anchor article (5K-8K words) and child articles (2.5K-3.5K each) link back to it.

aeo_get_cluster

Get full cluster details including all articles, their execution status, and overall progress. Pass either cluster_id for a specific cluster, or domain to get the most recent cluster for that domain. At least one parameter is required.

Parameters

Name	Type	Required	Description
`cluster_id`	string	Optional	Cluster UUID. Returns this specific cluster.
`domain`	string	Optional	Domain name. Returns the most recent cluster for this domain.

Example

json

class=class="code-string">"code-comment">// By cluster ID
aeo_get_cluster({ cluster_id: class="code-string">"cl_7f3a2b1c" })

class=class="code-string">"code-comment">// By domain (returns latest)
aeo_get_cluster({ domain: class="code-string">"understoodcare.com" })

Response

response

{
  class="code-string">"cluster_id": class="code-string">"cl_7f3a2b1c",
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"name": class="code-string">"Home Health Aide Hiring Cluster",
  class="code-string">"articles": [
    {
      class="code-string">"id": class="code-string">"ca_a1b2c3d4",
      class="code-string">"title": class="code-string">"How to Hire a Home Health Aide: Complete Guide",
      class="code-string">"slug": class="code-string">"how-to-hire-home-health-aide",
      class="code-string">"role": class="code-string">"hub",
      class="code-string">"status": class="code-string">"writing",
      class="code-string">"word_count": 4200,
      class="code-string">"execution_id": class="code-string">"ex_abc123"
    },
    {
      class="code-string">"id": class="code-string">"ca_e5f6g7h8",
      class="code-string">"title": class="code-string">"HHA vs PCA: Key Differences Explained",
      class="code-string">"slug": class="code-string">"hha-vs-pca-differences",
      class="code-string">"role": class="code-string">"child",
      class="code-string">"status": class="code-string">"planned",
      class="code-string">"word_count": null,
      class="code-string">"execution_id": null
    },
    {
      class="code-string">"id": class="code-string">"ca_i9j0k1l2",
      class="code-string">"title": class="code-string">"Home Health Aide Certification Requirements by State",
      class="code-string">"slug": class="code-string">"hha-certification-requirements",
      class="code-string">"role": class="code-string">"child",
      class="code-string">"status": class="code-string">"planned",
      class="code-string">"word_count": null,
      class="code-string">"execution_id": null
    }
  ],
  class="code-string">"status": class="code-string">"in_progress",
  class="code-string">"progress": {
    class="code-string">"total": 3,
    class="code-string">"planned": 2,
    class="code-string">"writing": 1,
    class="code-string">"review": 0,
    class="code-string">"published": 0,
    class="code-string">"percent_complete": 33
  }
}

aeo_list_clusters

List all content clusters for a domain with article counts and status summaries. Clusters are returned in reverse chronological order (newest first).

Parameters

Name	Type	Required	Description
`domain`	string	Required	Domain to list clusters for

Example

json

aeo_list_clusters({ domain: class="code-string">"understoodcare.com" })

Response

response

{
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"count": 2,
  class="code-string">"clusters": [
    {
      class="code-string">"id": class="code-string">"cl_7f3a2b1c",
      class="code-string">"name": class="code-string">"Home Health Aide Hiring Cluster",
      class="code-string">"status": class="code-string">"in_progress",
      class="code-string">"article_count": 3,
      class="code-string">"published_count": 0,
      class="code-string">"created_at": class="code-string">"2026-03-15T10:00:00Z"
    },
    {
      class="code-string">"id": class="code-string">"cl_abc123",
      class="code-string">"name": class="code-string">"CDPAP Education",
      class="code-string">"status": class="code-string">"complete",
      class="code-string">"article_count": 5,
      class="code-string">"published_count": 5,
      class="code-string">"created_at": class="code-string">"2026-02-20T14:30:00Z"
    }
  ]
}

aeo_suggest_clusters

Analyze a domain's audit gaps and visibility MISS queries to suggest content cluster opportunities. Returns severity-ranked criteria, uncovered queries, and ready-to-use cluster seeds. Each suggestion includes a rationale explaining why this cluster would improve the domain's AEO Site Rank.

Parameters

Name	Type	Required	Description
`domain`	string	Required	Domain to analyze for cluster opportunities
`max_clusters`	number	Optional	Maximum number of cluster suggestions to returnDefault: `3`

Example

json

aeo_suggest_clusters({ domain: class="code-string">"understoodcare.com", max_clusters: 2 })

Response

response

{
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"suggestions": [
    {
      class="code-string">"name": class="code-string">"Medicaid Home Care Coverage Cluster",
      class="code-string">"rationale": class="code-string">"3 visibility MISS queries relate to Medicaid coverage. Original Data score is 7/10 - proprietary cost data would lift this.",
      class="code-string">"severity": class="code-string">"high",
      class="code-string">"target_criteria": [class="code-string">"original-data", class="code-string">"qa-content", class="code-string">"comparison-tables"],
      class="code-string">"uncovered_queries": [
        class="code-string">"does medicaid cover home health aides",
        class="code-string">"medicaid home care hours per week",
        class="code-string">"medicaid vs medicare home care coverage"
      ],
      class="code-string">"seed_articles": [
        { class="code-string">"title": class="code-string">"Does Medicaid Cover Home Health Aides?", class="code-string">"role": class="code-string">"hub", class="code-string">"word_count_target": 6000 },
        { class="code-string">"title": class="code-string">"Medicaid vs Medicare Home Care: What Is Covered", class="code-string">"role": class="code-string">"child", class="code-string">"word_count_target": 3000 },
        { class="code-string">"title": class="code-string">"How Many Hours of Home Care Does Medicaid Cover?", class="code-string">"role": class="code-string">"child", class="code-string">"word_count_target": 2800 }
      ],
      class="code-string">"estimated_score_delta": 6
    },
    {
      class="code-string">"name": class="code-string">"Caregiver Training & Certification Cluster",
      class="code-string">"rationale": class="code-string">"Content Freshness score is 5/10. State-specific certification data with 2026 updates would address both freshness and original data gaps.",
      class="code-string">"severity": class="code-string">"medium",
      class="code-string">"target_criteria": [class="code-string">"content-freshness", class="code-string">"original-data"],
      class="code-string">"uncovered_queries": [
        class="code-string">"home health aide training requirements",
        class="code-string">"caregiver certification online"
      ],
      class="code-string">"seed_articles": [
        { class="code-string">"title": class="code-string">"Caregiver Training Programs: Complete 2026 Guide", class="code-string">"role": class="code-string">"hub", class="code-string">"word_count_target": 5500 },
        { class="code-string">"title": class="code-string">"Online Caregiver Certification: Costs and Options", class="code-string">"role": class="code-string">"child", class="code-string">"word_count_target": 2500 }
      ],
      class="code-string">"estimated_score_delta": 4
    }
  ]
}

Use suggestions as a starting point, then call aeo_create_cluster with the seed articles. You can customize titles, add more child articles, and refine the interlink map before creating.

aeo_start_cluster_article

Start writing a planned or approved cluster article. Transitions the article from planned or approved to writing status and returns the block structure, shared context, and interlink targets needed to begin content generation.

Parameters

Name	Type	Required	Description
`cluster_article_id`	string	Required	UUID of the cluster article to start writing

Example

json

aeo_start_cluster_article({ cluster_article_id: class="code-string">"ca_e5f6g7h8" })

Response

response

{
  class="code-string">"execution_id": class="code-string">"ex_def456",
  class="code-string">"blocks": [
    { class="code-string">"type": class="code-string">"hero", class="code-string">"status": class="code-string">"pending" },
    { class="code-string">"type": class="code-string">"short_answer", class="code-string">"status": class="code-string">"pending" },
    { class="code-string">"type": class="code-string">"body", class="code-string">"status": class="code-string">"pending" },
    { class="code-string">"type": class="code-string">"comparison_table", class="code-string">"status": class="code-string">"pending" },
    { class="code-string">"type": class="code-string">"faq", class="code-string">"status": class="code-string">"pending" },
    { class="code-string">"type": class="code-string">"references", class="code-string">"status": class="code-string">"pending" }
  ],
  class="code-string">"context": {
    class="code-string">"cluster_name": class="code-string">"Home Health Aide Hiring Cluster",
    class="code-string">"shared_context": class="code-string">"Understood Care operates in NY/NJ. All articles should reference state-specific Medicaid programs.",
    class="code-string">"target_criteria": [class="code-string">"comparison-tables", class="code-string">"qa-content"],
    class="code-string">"voice_profile": {
      class="code-string">"tone": class="code-string">"conversational",
      class="code-string">"industry": class="code-string">"home health care"
    },
    class="code-string">"interlink_targets": [
      { class="code-string">"slug": class="code-string">"how-to-hire-home-health-aide", class="code-string">"title": class="code-string">"How to Hire a Home Health Aide: Complete Guide" }
    ],
    class="code-string">"hub_summary": class="code-string">"Comprehensive guide covering cost, qualifications, Medicaid coverage, interview questions for hiring HHAs."
  }
}

The context object includes the hub summary and interlink targets so child articles can reference the hub naturally and link back to it.

aeo_update_cluster_status

Manage the cluster lifecycle. Supports three actions: start_writing to begin the cluster, sync_statuses to update the cluster status based on article progress, and complete to mark the cluster as done.

Parameters

Name	Type	Required	Description
`cluster_id`	string	Required	Cluster UUID
`action`	string	Required	"start_writing", "sync_statuses", or "complete"

Examples

json

class=class="code-string">"code-comment">// Begin writing phase
aeo_update_cluster_status({
  cluster_id: class="code-string">"cl_7f3a2b1c",
  action: class="code-string">"start_writing"
})

class=class="code-string">"code-comment">// Sync article statuses into cluster progress
aeo_update_cluster_status({
  cluster_id: class="code-string">"cl_7f3a2b1c",
  action: class="code-string">"sync_statuses"
})

class=class="code-string">"code-comment">// Mark cluster as complete
aeo_update_cluster_status({
  cluster_id: class="code-string">"cl_7f3a2b1c",
  action: class="code-string">"complete"
})

Response

response

{
  class="code-string">"message": class="code-string">"Cluster status updated to in_progress",
  class="code-string">"cluster_id": class="code-string">"cl_7f3a2b1c",
  class="code-string">"status": class="code-string">"in_progress"
}

Cluster Workflow

A typical content cluster workflow uses these tools in sequence. Start by analyzing gaps, create the cluster plan, write articles one by one, and complete when all articles are published.

Analyze gaps

aeo_get_cluster_context({ domain: "understoodcare.com" })

Get audit gaps, MISS queries, existing content.

Get suggestions

aeo_suggest_clusters({ domain: "understoodcare.com" })

AI-generated cluster opportunities ranked by severity.

Create cluster

aeo_create_cluster({ domain: "understoodcare.com", ... })

Define hub + child articles with interlink map.

Start writing

aeo_update_cluster_status({ cluster_id: "...", action: "start_writing" })

Transition cluster to in_progress.

Write each article

aeo_start_cluster_article({ cluster_article_id: "..." })

Get blocks and context, then write using content tools.

Complete cluster

aeo_update_cluster_status({ cluster_id: "...", action: "complete" })

Mark cluster done after all articles are published.

Write the hub article first. Child articles use hub_summary from the context to maintain coherence and link back naturally.