Action Report

Action Report

Render prioritized action reports in the artifact panel via preview_action_report. The agent writes a YAML file defining an executive summary and a list of action items; the MCP App renders them as visual cards sorted by priority.

Building the Report Incrementally

CRITICAL: Large reports (6+ actions) MUST be built in batches to avoid output truncation. Do NOT attempt to write the entire YAML in a single tool call.

1. Write the file with title, subtitle, summary, and the first 2–3 actions
2. Edit the file to append the next 2–3 actions at the end of the actions array
3. Repeat step 2 until all actions are written
4. Call preview_action_report once at the end — never mid-build

Each Edit call should add at most 3 action items. This keeps individual tool call output small and prevents mid-generation truncation.

YAML Structure

title: "SEO Action Report: example.com"
subtitle: "Analyzed 2026-02-18 (28-day window)"    # optional
summary: |
  AEO Score: 58/100 (C). 12 quick wins identified.
  Estimated total impact: +190-270 clicks/month.

actions:
  - title: "Rewrite H1 to include primary keyword"
    priority: high              # high | medium | low
    category: "Content Structure"  # optional — shown as badge
    as_is: |
      ```html
      <h1>Making Marketers Superhuman</h1>
      ```
    to_be: |
      ```html
      <h1>Treasure Data CDP | AI-Native Customer Data Platform</h1>
      ```
    reason: |
      Current H1 has no keyword signals. Top 5 competitors
      all include "CDP" in H1. Expected: +15-20% CTR.
    impact: "+35-40 clicks/month"  # optional — shown at bottom of card

  - title: "Add FAQPage JSON-LD schema"
    priority: high
    category: "Structured Data"
    as_is: |
      Only Article schema present
    to_be: |
      ```json
      {
        "@type": "FAQPage",
        "mainEntity": [
          {"@type": "Question", "name": "How does a CDP work?", "acceptedAnswer": {"@type": "Answer", "text": "..."}},
          {"@type": "Question", "name": "CDP vs DMP?", "acceptedAnswer": {"@type": "Answer", "text": "..."}}
        ]
      }
      ```
    reason: |
      4/5 competitors have FAQPage schema. Sites with 3+ schema types
      show ~13% higher AI citation rate.
    impact: "+50-80 clicks/month"

Fields

Action Item Fields

Rendering

The dashboard renders actions sorted by priority (high → medium → low) as flat cards with no expand/collapse. Each card shows:

• Header: number badge, title, priority badge, category badge
• Diff area: As-Is (red card) / To-Be (green card) stacked vertically
• Reason: explanation text below the diff
• Impact: metric at bottom of card (if provided)

Copy as Markdown

A Copy as Markdown button in the header copies the entire report as formatted markdown to the clipboard. This allows users to paste into docs, tickets, or share with team members.

Calling the tool

Write the YAML file and call:

preview_action_report({ file_path: "/absolute/path/to/action-report.yaml" })

Writing Guidelines

• as_is and to_be: Include actual current content and complete replacement — not vague descriptions. Use code blocks for HTML, JSON-LD, config snippets.
• reason: Cite specific data — competitor patterns, SERP features, score dimensions, metrics. Not just "this is better."
• priority: Based on effort-to-impact ratio. High = low effort + high impact. Low = high effort or low impact.
• summary: Lead with the most important finding. Include key scores and total expected impact.

Fallback (No Artifact Panel)

When preview_action_report is not available (CLI mode), output the same information as formatted markdown directly in the conversation.