MCP Tools

Article Pipeline Tools

7 MCP tools for block-based article generation. Create articles from templates, write individual blocks, rewrite, add/remove blocks, and manage the review workflow.

The typical article workflow is: aeo_create_article (select template and get block list) - aeo_write_block (write each block in generation order) - aeo_review_article (send for review). Use aeo_rewrite_block, aeo_add_block, and aeo_remove_block to refine the article before submitting.

aeo_create_article

Create a new block-based article from a recipe template. Returns an execution ID and the full list of blocks with their generation order. Each block has an instance_id (e.g., "B-07-0") that uniquely identifies it within the execution, and a generation_order indicating the recommended sequence for writing blocks.

Parameters

Name	Type	Required	Description
`domain`	string	Required	Client domain (e.g., "understoodcare.com")
`article_type`	enum	Required	Template type: blog-post, knowledge-article, how-to-guide, listicle, comparison-post, beginners-guide, case-study, landing-page, glossary, product-review, ultimate-guide
`topic_title`	string	Required	The article topic or headline
`topic_description`	string	Optional	Brief description of the article scope and angle
`target_word_count`	number	Optional	Desired word count for the finished article
`audience`	string	Optional	Target audience description
`goal`	string	Optional	Business goal for this article (e.g., "Generate qualified leads")
`folder_id`	string	Optional	Folder ID to organize the article in
`scope`	enum	Optional	Content depth: quick (fewer blocks), standard, or deep (more blocks, more detail)Default: `standard`
`brief`	object	Optional	Article brief with h1, directAnswer, ctaType, and intentStage fields
`internal_links`	array	Optional	Array of internal URLs to link to within the article
`author_preset_id`	string	Optional	Author preset ID for voice/tone configuration

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_create_article({
  domain: class="code-string">"understoodcare.com",
  article_type: class="code-string">"how-to-guide",
  topic_title: class="code-string">"How to Choose the Right Home Health Aide for Elderly Parents",
  topic_description: class="code-string">"Step-by-step guide covering qualifications, interview questions, red flags, and cost expectations for hiring home health aides.",
  target_word_count: 3500,
  audience: class="code-string">"Adult children caring for aging parents",
  goal: class="code-string">"Generate qualified leads for home care consultation",
  scope: class="code-string">"deep",
  brief: {
    h1: class="code-string">"How to Choose the Right Home Health Aide for Elderly Parents",
    directAnswer: class="code-string">"Start by assessing your parent's care needs, then verify aide certifications, run background checks, and conduct in-home trial visits before committing.",
    ctaType: class="code-string">"consultation",
    intentStage: class="code-string">"consideration"
  }
})

Response

json

{
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"article_type": class="code-string">"how-to-guide",
  class="code-string">"recipe_name": class="code-string">"how-to-guide",
  class="code-string">"topic_title": class="code-string">"How to Choose the Right Home Health Aide for Elderly Parents",
  class="code-string">"slug": class="code-string">"how-to-choose-the-right-home-health-aide-for-elderly-parents",
  class="code-string">"target_word_count": 3500,
  class="code-string">"total_blocks": 14,
  class="code-string">"blocks": [
    { class="code-string">"instance_id": class="code-string">"B-01-0", class="code-string">"block_id": class="code-string">"B-01", class="code-string">"name": class="code-string">"SEO Meta", class="code-string">"generation_order": 13 },
    { class="code-string">"instance_id": class="code-string">"B-02-0", class="code-string">"block_id": class="code-string">"B-02", class="code-string">"name": class="code-string">"Hero / H1", class="code-string">"generation_order": 1 },
    { class="code-string">"instance_id": class="code-string">"B-03-0", class="code-string">"block_id": class="code-string">"B-03", class="code-string">"name": class="code-string">"Direct Answer", class="code-string">"generation_order": 2 },
    { class="code-string">"instance_id": class="code-string">"B-07-0", class="code-string">"block_id": class="code-string">"B-07", class="code-string">"name": class="code-string">"Step-by-Step Section", class="code-string">"generation_order": 3 },
    { class="code-string">"instance_id": class="code-string">"B-07-1", class="code-string">"block_id": class="code-string">"B-07", class="code-string">"name": class="code-string">"Step-by-Step Section", class="code-string">"generation_order": 4 },
    { class="code-string">"instance_id": class="code-string">"B-07-2", class="code-string">"block_id": class="code-string">"B-07", class="code-string">"name": class="code-string">"Step-by-Step Section", class="code-string">"generation_order": 5 },
    { class="code-string">"instance_id": class="code-string">"B-10-0", class="code-string">"block_id": class="code-string">"B-10", class="code-string">"name": class="code-string">"Comparison Table", class="code-string">"generation_order": 6 },
    { class="code-string">"instance_id": class="code-string">"B-14-0", class="code-string">"block_id": class="code-string">"B-14", class="code-string">"name": class="code-string">"Expert Quote", class="code-string">"generation_order": 7 },
    { class="code-string">"instance_id": class="code-string">"B-11-0", class="code-string">"block_id": class="code-string">"B-11", class="code-string">"name": class="code-string">"Callout / Tip Box", class="code-string">"generation_order": 8 },
    { class="code-string">"instance_id": class="code-string">"B-20-0", class="code-string">"block_id": class="code-string">"B-20", class="code-string">"name": class="code-string">"In-Body CTA", class="code-string">"generation_order": 9 },
    { class="code-string">"instance_id": class="code-string">"B-30-0", class="code-string">"block_id": class="code-string">"B-30", class="code-string">"name": class="code-string">"FAQ Accordion", class="code-string">"generation_order": 10 },
    { class="code-string">"instance_id": class="code-string">"B-31-0", class="code-string">"block_id": class="code-string">"B-31", class="code-string">"name": class="code-string">"References", class="code-string">"generation_order": 11 },
    { class="code-string">"instance_id": class="code-string">"B-32-0", class="code-string">"block_id": class="code-string">"B-32", class="code-string">"name": class="code-string">"Related Articles", class="code-string">"generation_order": 12 },
    { class="code-string">"instance_id": class="code-string">"B-33-0", class="code-string">"block_id": class="code-string">"B-33", class="code-string">"name": class="code-string">"JSON-LD Schema", class="code-string">"generation_order": 14 }
  ]
}

aeo_write_block

Write content for a single block in an article execution. Each block is identified by its instance_id (e.g., "B-07-0"). Provide HTML for rendered output and plain text for word counting. The running total_word_count across all blocks is returned so you can track progress toward the target.

Parameters

Name	Type	Required	Description
`execution_id`	string	Required	The execution ID returned by aeo_create_article
`instance_id`	string	Required	Block instance ID (e.g., "B-07-0")
`block_id`	string	Required	Block type ID (e.g., "B-07")
`html`	string	Optional	HTML content for the block
`text`	string	Optional	Plain text content (used for word count tracking)
`output`	JSON	Optional	Structured JSON output for blocks that produce data (e.g., schema blocks)
`word_count`	number	Optional	Explicit word count override
`metadata`	object	Optional	Additional metadata to store with the block

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_write_block({
  execution_id: class="code-string">"exec_a1b2c3d4",
  instance_id: class="code-string">"B-07-0",
  block_id: class="code-string">"B-07",
  html: class="code-string">"<h2>Step 1: Assess Your Parent's Care Needs</h2>\n<p>Before you start interviewing candidates, document exactly what level of care your parent requires. This assessment drives every hiring decision that follows.</p>\n<ul>\n<li><strong>Activities of Daily Living (ADLs):</strong> Bathing, dressing, toileting, transferring, eating</li>\n<li><strong>Instrumental ADLs:</strong> Medication management, meal prep, transportation, housekeeping</li>\n<li><strong>Medical needs:</strong> Wound care, vital sign monitoring, physical therapy exercises</li>\n</ul>\n<p>Our data from 340 home care placements shows that families who complete a formal needs assessment before hiring report 73% higher satisfaction at the 90-day mark.</p>",
  text: class="code-string">"Step 1: Assess Your Parent's Care Needs. Before you start interviewing candidates, document exactly what level of care your parent requires...",
  word_count: 127
})

Response

json

{
  class="code-string">"message": class="code-string">"Block B-07-0 written successfully",
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"instance_id": class="code-string">"B-07-0",
  class="code-string">"total_word_count": 458
}

aeo_get_article_blocks

Retrieve all blocks and their content for an article. Pass an execution_id for a specific article, or a domain to fetch the latest execution for that domain. Use include_content to control whether block content is returned as HTML or plain text.

Parameters

Name	Type	Required	Description
`execution_id`	string	Optional	Execution ID of a specific article
`domain`	string	Optional	Client domain - fetches the latest execution for this domain
`include_content`	enum	Optional	Content format to include: "text" or "html"

Provide either execution_id or domain, not both. If neither is provided, the tool returns an error.

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_get_article_blocks({
  execution_id: class="code-string">"exec_a1b2c3d4",
  include_content: class="code-string">"html"
})

Response

json

{
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"blocks": [
    {
      class="code-string">"instance_id": class="code-string">"B-01-0",
      class="code-string">"block_id": class="code-string">"B-01",
      class="code-string">"name": class="code-string">"SEO Meta",
      class="code-string">"display_order": 0,
      class="code-string">"generation_order": 13,
      class="code-string">"html": class="code-string">"<title>How to Choose the Right Home Health Aide | Understood Care</title>\n<meta name=\"description\" content=\"Step-by-step guide to hiring...\" />",
      class="code-string">"word_count": 32
    },
    {
      class="code-string">"instance_id": class="code-string">"B-02-0",
      class="code-string">"block_id": class="code-string">"B-02",
      class="code-string">"name": class="code-string">"Hero / H1",
      class="code-string">"display_order": 1,
      class="code-string">"generation_order": 1,
      class="code-string">"html": class="code-string">"<h1>How to Choose the Right Home Health Aide for Elderly Parents</h1>\n<p class=\"subtitle\">A data-backed guide from 340 placements</p>",
      class="code-string">"word_count": 24
    },
    {
      class="code-string">"instance_id": class="code-string">"B-07-0",
      class="code-string">"block_id": class="code-string">"B-07",
      class="code-string">"name": class="code-string">"Step-by-Step Section",
      class="code-string">"display_order": 3,
      class="code-string">"generation_order": 3,
      class="code-string">"html": class="code-string">"<h2>Step 1: Assess Your Parent's Care Needs</h2>...",
      class="code-string">"word_count": 127
    }
  ],
  class="code-string">"total_word_count": 2845,
  class="code-string">"review_status": class="code-string">"draft"
}

aeo_rewrite_block

Rewrite an existing block with new content. Use this after reviewing a block that needs revision - for example, to add more original data, improve the CTA, or adjust tone to match the client voice profile. The previous version is replaced and the running total_word_count is recalculated.

Parameters

Name	Type	Required	Description
`execution_id`	string	Required	The execution ID of the article
`instance_id`	string	Required	Block instance ID to rewrite (e.g., "B-07-0")
`html`	string	Optional	New HTML content for the block
`text`	string	Optional	New plain text content
`output`	JSON	Optional	New structured JSON output
`word_count`	number	Optional	Explicit word count override for the rewritten block

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_rewrite_block({
  execution_id: class="code-string">"exec_a1b2c3d4",
  instance_id: class="code-string">"B-07-0",
  html: class="code-string">"<h2>Step 1: Assess Your Parent's Specific Care Needs</h2>\n<p>Before interviewing a single candidate, create a written care needs assessment. Families who skip this step are 3x more likely to churn through aides in the first 60 days.</p>\n<ul>\n<li><strong>Physical ADLs:</strong> Bathing, dressing, toileting, mobility transfers, feeding assistance</li>\n<li><strong>Cognitive support:</strong> Medication reminders, appointment scheduling, safety supervision</li>\n<li><strong>Household tasks:</strong> Meal preparation, light housekeeping, laundry, grocery shopping</li>\n</ul>\n<p>Download our free <a href=\"/care-needs-checklist\">Care Needs Checklist</a> - the same tool our care coordinators use during initial consultations.</p>",
  text: class="code-string">"Step 1: Assess Your Parent's Specific Care Needs. Before interviewing a single candidate, create a written care needs assessment...",
  word_count: 142
})

Response

json

{
  class="code-string">"message": class="code-string">"Block B-07-0 rewritten successfully",
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"instance_id": class="code-string">"B-07-0",
  class="code-string">"total_word_count": 2860
}

aeo_add_block

Add a new block to an existing article. Specify the block type via block_id and optionally position it after an existing block. If no after_instance_id is provided, the block is appended to the end. The new block gets a unique instance_id with an incremented suffix (e.g., if "B-14-0" exists, the new one becomes "B-14-1").

Parameters

Name	Type	Required	Description
`execution_id`	string	Required	The execution ID of the article
`block_id`	string	Required	Block type to add (e.g., "B-14" for Expert Quote, "B-11" for Callout)
`after_instance_id`	string	Optional	Insert after this block instance. Defaults to appending at end.

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_add_block({
  execution_id: class="code-string">"exec_a1b2c3d4",
  block_id: class="code-string">"B-14",
  after_instance_id: class="code-string">"B-07-2"
})

Response

json

{
  class="code-string">"message": class="code-string">"Block B-14 added as B-14-1",
  class="code-string">"instance_id": class="code-string">"B-14-1",
  class="code-string">"display_order": 7
}

After adding a block, use aeo_write_block with the returned instance_id to populate it with content.

aeo_remove_block

Remove a block from an article. The remaining blocks are reordered automatically. Use this to trim unnecessary sections - for example, removing a second comparison table if the article already has enough data density, or dropping a callout box that feels redundant.

Parameters

Name	Type	Required	Description
`execution_id`	string	Required	The execution ID of the article
`instance_id`	string	Required	Block instance ID to remove (e.g., "B-14-1")

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_remove_block({
  execution_id: class="code-string">"exec_a1b2c3d4",
  instance_id: class="code-string">"B-14-1"
})

Response

json

{
  class="code-string">"message": class="code-string">"Block B-14-1 removed",
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"remaining_blocks": 13
}

aeo_review_article

Manage the article review workflow. Actions transition the article through statuses: draft - in_review - approved or revision_requested - published. When requesting revision, include notes explaining what needs to change.

Parameters

Name	Type	Required	Description
`execution_id`	string	Required	The execution ID of the article
`action`	enum	Required	Workflow action: send_for_review, approve, request_revision, publish
`notes`	string	Optional	Review notes. Required when action is request_revision.
`categories`	array	Optional	Category tags for the article (e.g., ["home-health", "hiring-guide"])

Send for review

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_review_article({
  execution_id: class="code-string">"exec_a1b2c3d4",
  action: class="code-string">"send_for_review",
  notes: class="code-string">"All 14 blocks written. Total word count 3,480. Ready for client review.",
  categories: [class="code-string">"home-health", class="code-string">"hiring-guide"]
})

Response

json

{
  class="code-string">"message": class="code-string">"Article sent for review",
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"new_status": class="code-string">"in_review"
}

Approve article

Example

json

class=class="code-string">"code-comment">// Agent calls:
aeo_review_article({
  execution_id: class="code-string">"exec_a1b2c3d4",
  action: class="code-string">"approve"
})

Response

json

{
  class="code-string">"message": class="code-string">"Article approved",
  class="code-string">"execution_id": class="code-string">"exec_a1b2c3d4",
  class="code-string">"new_status": class="code-string">"approved"
}

After approval, use aeo_review_article with action: "publish" to mark the article as published. To push content to a CMS, use the separate aeo_publish_to_cms tool.