Read Media

Read Media — Critical-First Analysis

Analyze media files using read_media from the media-tools MCP server. This is the primary tool for output-first verification — experiencing your work as a user would, not just reading code.

Critical-First Philosophy

The vision model is instructed to be a critical reviewer by default:

"You are reviewing this work critically. Be honest about what you see — name specific problems, explain their impact, and distinguish between issues that need a fundamental rethink vs issues that are easy fixes. Don't sugarcoat."

When no prompt is provided, the default is:

"Analyze this {media_type}. What works, what's broken, and what would a demanding user complain about? Be specific and critical."

Responses include a foundation_sound assessment that flags when the approach itself needs rethinking vs. when incremental fixes are sufficient. When foundation_sound: false, treat this as a signal to consider TRANSFORMATIVE changes rather than more polish.

You don't need to add "be critical" to your prompts — it's the default. Focus your prompt on what to look at.

Quick Start

# Analyze a screenshot
read_media(prompt="What flaws or layout issues do you see?", file_paths=["screenshot.png"])

# Compare before and after
read_media(prompt="Compare these two versions — what improved and what regressed?",
           file_paths=["v1.png", "v2.png"])

# Check a video
read_media(prompt="Is the animation smooth? Any glitches?", file_paths=["recording.mp4"])

# Verify audio output
read_media(prompt="Is the speech clear and natural?", file_paths=["output.mp3"])

Parameters

Before/After Comparison

All files are sent to the model in a SINGLE call — the model sees them side-by-side. This is critical for comparison: if you send files in separate calls, the model cannot compare them.

# CORRECT: both files in one call — model sees both
read_media(prompt="Compare before and after — what improved, what regressed?",
           file_paths=["v1.png", "v2.png"])

# WRONG: separate calls — model has no memory of the first
read_media(prompt="Analyze this", file_paths=["v1.png"])
read_media(prompt="Now compare to previous", file_paths=["v2.png"])  # can't compare!

For follow-up questions on the same media, use continue_from:

# First call
result = read_media(prompt="Evaluate the design", file_paths=["page.png"])
# result contains conversation_id

# Follow-up (model remembers the image)
read_media(prompt="Now focus on the typography — is the hierarchy clear?",
           continue_from="conv_abc123")

Supported Formats and Backends

Images

Formats: png, jpg, jpeg, gif, webp, bmp

Video

Formats: mp4, mov, avi, mkv, webm, gif, flv, wmv

Audio

Formats: mp3, wav, m4a, ogg, flac, aac

Backend auto-selects based on available API keys (first available in priority order).

Verification by Deliverable Type

Match evidence to how the output is experienced. Classify by what happens when a user opens it, not by file extension:

Coverage Check Before Diagnosis

Before concluding something is broken:

1. Capture the full artifact — all pages, sections, states (not just one viewport)
2. Scroll through long pages and multi-state flows
3. Check for capture artifacts: blank regions may be timing/iframe/canvas issues
4. If code suggests more output than captured, fix capture first

Prompts by Domain

Focus on what to look at — the critical lens is automatic:

Capturing Screenshots for Verification

# Playwright (recommended)
npx -y playwright@latest screenshot http://localhost:8765 screenshot.png --full-page

# Multiple viewports
npx -y playwright@latest screenshot http://localhost:8765 desktop.png --viewport-size=1440,900
npx -y playwright@latest screenshot http://localhost:8765 mobile.png --viewport-size=375,812

Then: read_media(prompt="Evaluate at desktop and mobile sizes", file_paths=["desktop.png", "mobile.png"])

API Key Check

On session start, .massgen-quality/environment.json is written with availability status. Check capabilities.has_vision to confirm read_media will work before attempting calls.