Free Audit Let's Talk

Product

Topic Engine Content Engine Code-to-Docs AEO Rank Research-Driven Content Autopilot Visibility Tracking Website & Migration Content Factory Pricing

Resources

Browse all resources → Case Studies Blog FAQ Use Cases Knowledge Base Research Docs

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

NameTypeRequiredDescription
domainstringRequiredDomain to get cluster context for (e.g., "understoodcare.com")

Example

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

Response

audit.weak_criteria holds the entries of the latest audit scorecard that score 7 or lower out of 10, lowest score first. visibility.miss_queries holds the visibility queries from the latest report where the domain was not visible, as full query records. In existing_articles, status is the article's review status.

response
{
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"audit": {
    class="code-string">"overall_score": 82,
    class="code-string">"weak_criteria": [
      {
        class="code-string">"id": 27,
        class="code-string">"criterion": class="code-string">"Content Freshness Signals",
        class="code-string">"score": 5,
        class="code-string">"status": class="code-string">"PARTIAL",
        class="code-string">"keyFindings": class="code-string">"Most content pages show no published or updated date.",
        class="code-string">"pillar": class="code-string">"Trust & Authority",
        class="code-string">"clientName": class="code-string">"Content Freshness",
        class="code-string">"weight": 0.019,
        class="code-string">"confidence": 0.85,
        class="code-string">"googleRecommended": true
      },
      {
        class="code-string">"id": 5,
        class="code-string">"criterion": class="code-string">"Original Data & Expert Analysis",
        class="code-string">"score": 7,
        class="code-string">"status": class="code-string">"GOOD",
        class="code-string">"keyFindings": class="code-string">"Few pages cite first-party numbers or named experts.",
        class="code-string">"pillar": class="code-string">"Answer Readiness",
        class="code-string">"clientName": class="code-string">"Original Research & Data",
        class="code-string">"weight": 0.0699,
        class="code-string">"confidence": 0.75,
        class="code-string">"googleRecommended": true
      }
    ],
    class="code-string">"opportunities": null
  },
  class="code-string">"visibility": {
    class="code-string">"miss_queries": [
      {
        class="code-string">"query": class="code-string">"does medicaid cover home health aides",
        class="code-string">"intent": class="code-string">"informational",
        class="code-string">"what_llm_returns": class="code-string">"A general overview of Medicaid home care benefits citing government and nonprofit sites.",
        class="code-string">"target_visible": false,
        class="code-string">"competitor_visibility": { class="code-string">"competitor-one.com": true, class="code-string">"competitor-two.com": false },
        class="code-string">"content_needed": class="code-string">"A guide to Medicaid coverage for home health aides with eligibility steps."
      },
      {
        class="code-string">"query": class="code-string">"caregiver certification online",
        class="code-string">"intent": class="code-string">"informational",
        class="code-string">"what_llm_returns": class="code-string">"A list of online caregiver training programs.",
        class="code-string">"target_visible": false,
        class="code-string">"competitor_visibility": { class="code-string">"competitor-one.com": false, class="code-string">"competitor-two.com": true },
        class="code-string">"content_needed": class="code-string">"A comparison of online caregiver certification options and costs."
      }
    ]
  },
  class="code-string">"existing_articles": [
    {
      class="code-string">"execution_id": class="code-string">"a8f3c6d2-7e19-4b5a-9c04-3d6e2b1f8a57",
      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": 4350,
      class="code-string">"status": class="code-string">"published"
    },
    {
      class="code-string">"execution_id": class="code-string">"0b4e7a9c-5d21-4f63-a8e9-c7f2d1b6e035",
      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": 4620,
      class="code-string">"status": class="code-string">"published"
    }
  ],
  class="code-string">"voice_profile": {
    class="code-string">"target_criteria": [class="code-string">"original_data", class="code-string">"faq_section"],
    class="code-string">"tone": class="code-string">"conversational",
    class="code-string">"brand_stance": class="code-string">"Families deserve plain answers about care costs and coverage."
  },
  class="code-string">"cms_content": [
    { class="code-string">"title": class="code-string">"What Is CDPAP?", class="code-string">"slug": class="code-string">"what-is-cdpap" },
    { class="code-string">"title": class="code-string">"Home Care vs Nursing Home", class="code-string">"slug": class="code-string">"home-care-vs-nursing-home" }
  ],
  class="code-string">"existing_clusters": [
    {
      class="code-string">"id": class="code-string">"7e15c9a4-d3b8-4c62-9f0a-4b2d6e8a1c73",
      class="code-string">"name": class="code-string">"CDPAP Education",
      class="code-string">"status": class="code-string">"published",
      class="code-string">"total_articles": 5,
      class="code-string">"completed_articles": 5
    }
  ]
}
Always call aeo_get_cluster_context before creating a cluster. The audit.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 and every article are created in planned status. The hub gets sort_order 0 and the child articles 1, 2, 3 and so on, in the order you list them.

Parameters

NameTypeRequiredDescription
domainstringRequiredTarget domain for the cluster
namestringRequiredCluster name (e.g., "CDPAP Education Cluster")
gap_sourceobjectOptionalFree-form object recording the weak criteria and MISS queries that motivated this cluster
shared_contextobjectOptionalFree-form object with research, terminology and facts shared by every article in the cluster. Returned with each aeo_start_cluster_article call.
interlink_mapobjectOptionalPlanned cross-links: each article slug maps to an array of the slugs it should link to ({ "slug": ["target-slug-1", ...] })
target_score_deltanumberOptionalExpected AEO Site Rank improvement from this cluster (a whole number)
articlesarrayRequiredArticle definitions (min 2, exactly 1 hub). Fields of each article are listed below.

Article fields

NameTypeRequiredDescription
rolestringRequired"hub" (the anchor article) or "child" (a supporting article)
titlestringRequiredArticle title
slugstringRequiredURL slug. The keys and values of interlink_map refer to these slugs.
article_typestringOptionalRecipe template type (e.g., "blog-post", "how-to-guide"). When omitted, the article is written as a "signature-article".
word_targetnumberOptionalTarget word count. Articles have a 4,000-word minimum, so a lower target is raised to 4,000.
key_queriesstring[]OptionalAI queries this article targets
criteria_targetedstring[]OptionalAEO criteria slugs this article targets (e.g., "original_data")
briefobjectOptionalPer-article generation brief, passed to the writer as is. Its angle field becomes the article's topic description.

Example

json
aeo_create_cluster({
  domain: class="code-string">"understoodcare.com",
  name: class="code-string">"Home Health Aide Hiring Cluster",
  gap_source: {
    weak_criteria: [class="code-string">"content_freshness", class="code-string">"original_data"],
    miss_queries: [class="code-string">"does medicaid cover home health aides", class="code-string">"how to hire a home health aide"]
  },
  target_score_delta: 8,
  shared_context: {
    audience: class="code-string">"Families arranging in-home care for a parent",
    terminology: { HHA: class="code-string">"home health aide", PCA: class="code-string">"personal care aide" },
    notes: class="code-string">"Explain Medicaid and Medicare coverage wherever cost comes up."
  },
  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: [
    {
      role: class="code-string">"hub",
      title: class="code-string">"How to Hire a Home Health Aide: Complete Guide",
      slug: class="code-string">"how-to-hire-home-health-aide",
      word_target: 6000,
      key_queries: [class="code-string">"how to hire a home health aide", class="code-string">"home health aide cost per hour"],
      criteria_targeted: [class="code-string">"original_data", class="code-string">"qa_content_format", class="code-string">"table_list_extractability"],
      brief: { angle: class="code-string">"Cover cost, qualifications, Medicaid coverage, interview questions" }
    },
    {
      role: class="code-string">"child",
      title: class="code-string">"HHA vs PCA: Key Differences Explained",
      slug: class="code-string">"hha-vs-pca-differences",
      word_target: 4000,
      key_queries: [class="code-string">"hha vs pca", class="code-string">"difference between home health aide and personal care aide"],
      criteria_targeted: [class="code-string">"table_list_extractability", class="code-string">"qa_content_format"],
      brief: { angle: class="code-string">"Scope of work, certification, cost, when to choose each" }
    },
    {
      role: class="code-string">"child",
      title: class="code-string">"Home Health Aide Certification Requirements by State",
      slug: class="code-string">"hha-certification-requirements",
      word_target: 4000,
      key_queries: [class="code-string">"home health aide certification requirements"],
      criteria_targeted: [class="code-string">"original_data", class="code-string">"content_freshness"],
      brief: { angle: class="code-string">"NY, NJ, CT requirements, training hours, renewal process" }
    }
  ]
})

Response

response
{
  class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"name": class="code-string">"Home Health Aide Hiring Cluster",
  class="code-string">"total_articles": 3,
  class="code-string">"articles": [
    {
      class="code-string">"id": class="code-string">"9d2e4b17-5c3a-4f86-b0e1-7a4c9f3d2e58",
      class="code-string">"role": class="code-string">"hub",
      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">"sort_order": 0
    },
    {
      class="code-string">"id": class="code-string">"c41f8a62-0b7d-4e93-a5c2-6d18e7f04b39",
      class="code-string">"role": class="code-string">"child",
      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">"sort_order": 1
    },
    {
      class="code-string">"id": class="code-string">"5b8e3d0c-2f64-4a1b-8e7d-91c5a2f6b0e4",
      class="code-string">"role": class="code-string">"child",
      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">"sort_order": 2
    }
  ]
}
Exactly one article must have role: "hub". The hub is the comprehensive anchor article (5K-8K words) and child articles (4,000 words or more each) link back to it. With no hub or more than one, the tool saves nothing and returns { "error": "Cluster must have exactly 1 hub article, got 0" }.

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

NameTypeRequiredDescription
cluster_idstringOptionalCluster UUID. Returns this specific cluster.
domainstringOptionalDomain 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">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81" })

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

Response

The cluster and its articles come back as stored, so a response can carry more fields than shown here. Articles are ordered by sort_order, and each one adds execution_review_status and execution_word_count from its pipeline execution (null before writing starts). progress counts articles by status. If nothing matches, the tool returns { "error": "Cluster not found" }.

response
{
  class="code-string">"id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"name": class="code-string">"Home Health Aide Hiring Cluster",
  class="code-string">"status": class="code-string">"writing",
  class="code-string">"gap_source": { class="code-string">"weak_criteria": [class="code-string">"content_freshness", class="code-string">"original_data"], class="code-string">"miss_queries": [class="code-string">"does medicaid cover home health aides", class="code-string">"how to hire a home health aide"] },
  class="code-string">"shared_context": { class="code-string">"audience": class="code-string">"Families arranging in-home care for a parent", class="code-string">"terminology": { class="code-string">"HHA": class="code-string">"home health aide", class="code-string">"PCA": class="code-string">"personal care aide" }, class="code-string">"notes": class="code-string">"Explain Medicaid and Medicare coverage wherever cost comes up." },
  class="code-string">"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"] },
  class="code-string">"total_articles": 3,
  class="code-string">"completed_articles": 0,
  class="code-string">"target_score_delta": 8,
  class="code-string">"created_at": class="code-string">"2026-10-05T14:02:11.418Z",
  class="code-string">"updated_at": class="code-string">"2026-10-06T09:30:42.007Z",
  class="code-string">"articles": [
    {
      class="code-string">"id": class="code-string">"9d2e4b17-5c3a-4f86-b0e1-7a4c9f3d2e58",
      class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
      class="code-string">"role": class="code-string">"hub",
      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">"article_type": null,
      class="code-string">"word_target": 6000,
      class="code-string">"key_queries": [class="code-string">"how to hire a home health aide", class="code-string">"home health aide cost per hour"],
      class="code-string">"criteria_targeted": [class="code-string">"original_data", class="code-string">"qa_content_format", class="code-string">"table_list_extractability"],
      class="code-string">"brief": { class="code-string">"angle": class="code-string">"Cover cost, qualifications, Medicaid coverage, interview questions" },
      class="code-string">"status": class="code-string">"draft",
      class="code-string">"execution_id": class="code-string">"e6a90f3b-41d2-4c8e-b75a-0f2c8d3e9a16",
      class="code-string">"sort_order": 0,
      class="code-string">"execution_review_status": class="code-string">"draft",
      class="code-string">"execution_word_count": 6240
    },
    {
      class="code-string">"id": class="code-string">"c41f8a62-0b7d-4e93-a5c2-6d18e7f04b39",
      class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
      class="code-string">"role": class="code-string">"child",
      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">"article_type": null,
      class="code-string">"word_target": 4000,
      class="code-string">"key_queries": [class="code-string">"hha vs pca", class="code-string">"difference between home health aide and personal care aide"],
      class="code-string">"criteria_targeted": [class="code-string">"table_list_extractability", class="code-string">"qa_content_format"],
      class="code-string">"brief": { class="code-string">"angle": class="code-string">"Scope of work, certification, cost, when to choose each" },
      class="code-string">"status": class="code-string">"planned",
      class="code-string">"execution_id": null,
      class="code-string">"sort_order": 1,
      class="code-string">"execution_review_status": null,
      class="code-string">"execution_word_count": null
    },
    {
      class="code-string">"id": class="code-string">"5b8e3d0c-2f64-4a1b-8e7d-91c5a2f6b0e4",
      class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
      class="code-string">"role": class="code-string">"child",
      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">"article_type": null,
      class="code-string">"word_target": 4000,
      class="code-string">"key_queries": [class="code-string">"home health aide certification requirements"],
      class="code-string">"criteria_targeted": [class="code-string">"original_data", class="code-string">"content_freshness"],
      class="code-string">"brief": { class="code-string">"angle": class="code-string">"NY, NJ, CT requirements, training hours, renewal process" },
      class="code-string">"status": class="code-string">"planned",
      class="code-string">"execution_id": null,
      class="code-string">"sort_order": 2,
      class="code-string">"execution_review_status": null,
      class="code-string">"execution_word_count": null
    }
  ],
  class="code-string">"progress": {
    class="code-string">"total": 3,
    class="code-string">"planned": 2,
    class="code-string">"writing": 0,
    class="code-string">"draft": 1,
    class="code-string">"published": 0
  }
}

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). The response is an array, and article_status_summary counts each cluster's articles by status.

Parameters

NameTypeRequiredDescription
domainstringRequiredDomain to list clusters for

Example

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

Response

response
[
  {
    class="code-string">"id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
    class="code-string">"domain": class="code-string">"understoodcare.com",
    class="code-string">"name": class="code-string">"Home Health Aide Hiring Cluster",
    class="code-string">"status": class="code-string">"writing",
    class="code-string">"total_articles": 3,
    class="code-string">"completed_articles": 0,
    class="code-string">"target_score_delta": 8,
    class="code-string">"created_at": class="code-string">"2026-10-05T14:02:11.418Z",
    class="code-string">"updated_at": class="code-string">"2026-10-06T09:30:42.007Z",
    class="code-string">"article_status_summary": { class="code-string">"draft": 1, class="code-string">"planned": 2 }
  },
  {
    class="code-string">"id": class="code-string">"7e15c9a4-d3b8-4c62-9f0a-4b2d6e8a1c73",
    class="code-string">"domain": class="code-string">"understoodcare.com",
    class="code-string">"name": class="code-string">"CDPAP Education",
    class="code-string">"status": class="code-string">"published",
    class="code-string">"total_articles": 5,
    class="code-string">"completed_articles": 5,
    class="code-string">"target_score_delta": null,
    class="code-string">"created_at": class="code-string">"2026-02-20T14:30:00.000Z",
    class="code-string">"updated_at": class="code-string">"2026-04-02T11:15:27.311Z",
    class="code-string">"article_status_summary": { class="code-string">"published": 5 }
  }
]

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. The analysis is rule based, not AI generated. Criteria scoring 7 or lower are ranked by gap_severity (10 minus the score), most severe first; criteria the engine could not measure are left out. A MISS query counts as covered when it shares at least two keywords with the title of an existing pipeline article or CMS page. Uncovered queries that share at least two keywords are grouped, and every group of three or more queries becomes a cluster seed. Seeds are returned largest first, up to max_clusters.

Parameters

NameTypeRequiredDescription
domainstringRequiredDomain to analyze for cluster opportunities
max_clustersnumberOptionalMost cluster seeds to return, largest groups first (default 3, minimum 1)

Example

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

Response

Each criteria_by_severity entry carries the criterion's name, pillar (null on older audits), score and gap_severity; its id is the criterion's position in the audit scorecard. cluster_seeds_total counts every seed found before the max_clusters cut. existing_clusters and voice_profile have the same shape as in aeo_get_cluster_context.

response
{
  class="code-string">"domain": class="code-string">"understoodcare.com",
  class="code-string">"overall_score": 82,
  class="code-string">"criteria_by_severity": [
    { class="code-string">"id": 8, class="code-string">"name": class="code-string">"Original Data & Expert Analysis", class="code-string">"pillar": class="code-string">"Answer Readiness", class="code-string">"score": 5, class="code-string">"gap_severity": 5 },
    { class="code-string">"id": 7, class="code-string">"name": class="code-string">"Comprehensive FAQ Section", class="code-string">"pillar": class="code-string">"Content Structure", class="code-string">"score": 7, class="code-string">"gap_severity": 3 }
  ],
  class="code-string">"uncovered_queries": [
    class="code-string">"does medicaid cover home health aides",
    class="code-string">"how many hours a week medicaid pays for a home health aide",
    class="code-string">"medicaid vs medicare coverage for home health aides",
    class="code-string">"caregiver certification online"
  ],
  class="code-string">"covered_queries": [
    { class="code-string">"query": class="code-string">"home care vs nursing home cost", class="code-string">"matched_by": class="code-string">"home care vs nursing home" }
  ],
  class="code-string">"cluster_seeds": [
    {
      class="code-string">"seed_keywords": [class="code-string">"medicaid", class="code-string">"cover", class="code-string">"home", class="code-string">"health", class="code-string">"aides", class="code-string">"many", class="code-string">"hours", class="code-string">"week", class="code-string">"pays", class="code-string">"aide"],
      class="code-string">"queries": [
        class="code-string">"does medicaid cover home health aides",
        class="code-string">"how many hours a week medicaid pays for a home health aide",
        class="code-string">"medicaid vs medicare coverage for home health aides"
      ]
    }
  ],
  class="code-string">"cluster_seeds_total": 1,
  class="code-string">"existing_coverage": {
    class="code-string">"pipeline_articles": 2,
    class="code-string">"cms_articles": 2
  },
  class="code-string">"existing_clusters": [
    {
      class="code-string">"id": class="code-string">"7e15c9a4-d3b8-4c62-9f0a-4b2d6e8a1c73",
      class="code-string">"name": class="code-string">"CDPAP Education",
      class="code-string">"status": class="code-string">"published",
      class="code-string">"total_articles": 5,
      class="code-string">"completed_articles": 5
    }
  ],
  class="code-string">"voice_profile": {
    class="code-string">"target_criteria": [class="code-string">"original_data", class="code-string">"faq_section"],
    class="code-string">"tone": class="code-string">"conversational",
    class="code-string">"brand_stance": class="code-string">"Families deserve plain answers about care costs and coverage."
  }
}
Use the cluster seeds as a starting point: turn each seed's queries into a hub and child articles (their key_queries), then call aeo_create_cluster. You choose the titles, add more child articles, and refine the interlink map before creating.

aeo_start_cluster_article

Start writing a planned or approved cluster article. Creates a pipeline execution for the article, links it to the 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. A cluster still in planned status moves to writing. An article already marked writing that has no execution yet is accepted too; an article that already has an execution is refused with an error.

Parameters

NameTypeRequiredDescription
cluster_article_idstringRequiredUUID of the cluster article to start writing

Example

json
aeo_start_cluster_article({ cluster_article_id: class="code-string">"c41f8a62-0b7d-4e93-a5c2-6d18e7f04b39" })

Response

The blocks list is shortened here. slug is the new execution's slug, made from the title; the cluster article keeps its own slug, which is the one the interlink map uses.

response
{
  class="code-string">"execution_id": class="code-string">"2c7d5e1a-9b3f-4a08-8d64-e5f1b0c7a293",
  class="code-string">"article_type": class="code-string">"signature-article",
  class="code-string">"recipe_name": class="code-string">"Signature Article",
  class="code-string">"topic_title": class="code-string">"HHA vs PCA: Key Differences Explained",
  class="code-string">"slug": class="code-string">"hha-vs-pca-key-differences-explained",
  class="code-string">"target_word_count": 4000,
  class="code-string">"total_blocks": 14,
  class="code-string">"blocks": [
    { class="code-string">"instance_id": class="code-string">"B-23-0", class="code-string">"block_id": class="code-string">"B-23", class="code-string">"displayName": class="code-string">"Quick Answer", class="code-string">"generationOrder": 1, class="code-string">"displayOrder": 0, class="code-string">"wordCountTarget": 60, class="code-string">"isVisible": true },
    { class="code-string">"instance_id": class="code-string">"B-58-0", class="code-string">"block_id": class="code-string">"B-58", class="code-string">"displayName": class="code-string">"Key Points", class="code-string">"generationOrder": 2, class="code-string">"displayOrder": 1, class="code-string">"wordCountTarget": 120, class="code-string">"isVisible": true },
    { class="code-string">"instance_id": class="code-string">"B-07-0", class="code-string">"block_id": class="code-string">"B-07", class="code-string">"displayName": class="code-string">"Body", class="code-string">"generationOrder": 3, class="code-string">"displayOrder": 2, class="code-string">"wordCountTarget": 650, class="code-string">"isVisible": true },
    { class="code-string">"instance_id": class="code-string">"B-07-1", class="code-string">"block_id": class="code-string">"B-07", class="code-string">"displayName": class="code-string">"Body", class="code-string">"generationOrder": 4, class="code-string">"displayOrder": 3, class="code-string">"wordCountTarget": 650, class="code-string">"isVisible": true },
    { class="code-string">"instance_id": class="code-string">"B-24-0", class="code-string">"block_id": class="code-string">"B-24", class="code-string">"displayName": class="code-string">"FAQ", class="code-string">"generationOrder": 12, class="code-string">"displayOrder": 12, class="code-string">"wordCountTarget": 450, class="code-string">"isVisible": true },
    { class="code-string">"instance_id": class="code-string">"B-38-0", class="code-string">"block_id": class="code-string">"B-38", class="code-string">"displayName": class="code-string">"References", class="code-string">"generationOrder": 13, class="code-string">"displayOrder": 13, class="code-string">"wordCountTarget": 120, class="code-string">"isVisible": true }
  ],
  class="code-string">"brief": { class="code-string">"angle": class="code-string">"Scope of work, certification, cost, when to choose each" },
  class="code-string">"shared_context": {
    class="code-string">"audience": class="code-string">"Families arranging in-home care for a parent",
    class="code-string">"terminology": { class="code-string">"HHA": class="code-string">"home health aide", class="code-string">"PCA": class="code-string">"personal care aide" },
    class="code-string">"notes": class="code-string">"Explain Medicaid and Medicare coverage wherever cost comes up."
  },
  class="code-string">"interlink_targets": [class="code-string">"how-to-hire-home-health-aide"],
  class="code-string">"key_queries": [class="code-string">"hha vs pca", class="code-string">"difference between home health aide and personal care aide"],
  class="code-string">"criteria_targeted": [class="code-string">"table_list_extractability", class="code-string">"qa_content_format"],
  class="code-string">"voice_profile": {
    class="code-string">"target_criteria": [class="code-string">"original_data", class="code-string">"faq_section"],
    class="code-string">"tone": class="code-string">"conversational",
    class="code-string">"brand_stance": class="code-string">"Families deserve plain answers about care costs and coverage."
  }
}
interlink_targets lists the slugs this article should link to, read from the cluster's interlink_map under the article's slug. shared_context and brief come back exactly as they were saved on the cluster and the article. Together they let child articles reference the hub naturally and link back to it.

aeo_update_cluster_status

Manage the cluster lifecycle. Supports three actions: start_writing moves a cluster from planned to writing and refuses any other starting status. sync_statuses copies each article's review status from its pipeline execution onto the cluster article (rejected becomes draft, archived articles are skipped) and recounts completed_articles as the articles that are approved or published; it does not change the cluster's own status. complete sets the cluster to published once every article that is not archived is published. When an action is refused, the call fails with an error that names the reason.

Parameters

NameTypeRequiredDescription
cluster_idstringRequiredCluster UUID
actionstringRequired"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">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  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">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  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">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  action: class="code-string">"complete"
})

Response

response
class=class="code-string">"code-comment">// start_writing
{
  class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  class="code-string">"action": class="code-string">"start_writing",
  class="code-string">"new_status": class="code-string">"writing"
}

class=class="code-string">"code-comment">// sync_statuses
{
  class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  class="code-string">"action": class="code-string">"sync_statuses",
  class="code-string">"synced": 2,
  class="code-string">"completed_articles": 1,
  class="code-string">"total_articles": 3
}

class=class="code-string">"code-comment">// complete
{
  class="code-string">"cluster_id": class="code-string">"3f6c2a9e-8b41-4d7a-9c15-2e0b7d4a6f81",
  class="code-string">"action": class="code-string">"complete",
  class="code-string">"new_status": class="code-string">"published",
  class="code-string">"total_articles": 3
}

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.

1

Analyze gaps

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

Get audit gaps, MISS queries, existing content.

2

Get suggestions

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

Weak criteria ranked by severity and uncovered MISS queries grouped into cluster seeds.

3

Create cluster

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

Define hub + child articles with interlink map.

4

Start writing

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

Transition cluster from planned to writing. Optional: the first aeo_start_cluster_article call does this too.

5

Write each article

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

Get blocks and context, then write using content tools.

6

Sync statuses

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

Copy each article's review status from its execution and recount completed articles.

7

Complete cluster

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

Mark cluster done after all articles are published.

Write the hub article first. The tools do not pass a hub summary to child articles, so put what every article should know about the hub into shared_context when you create the cluster: aeo_start_cluster_article returns it with every article, which keeps child articles coherent with the hub.