MCP Tools Reference

Complete reference for all Aether MCP tools available in Cursor, Claude Code, and other MCP clients.

🤖Your Agent Knows All This

Once your Cursor MCP is connected, your agent has full access to every tool below. You don't need to memorize these — just ask your question and let the agent handle it.

Core Tools

These 6 tools cover 90% of debugging workflows. Your agent will reach for these first.

| Tool | What it does | |------|-------------| | aether_triage | Start here. One command → last run metadata, top suspects, 3 receipts, capsule path, next-step hints. | | aether_snapshot | Point-in-time game state: objects, scene, events, console. | | aether_console | Search and filter Unity logs by text, level, and time window. | | aether_observe | Rich "what happened" summary: keyframes + deltas + logs + narration. | | aether_recon | When core tools aren't enough: generates a probe plan for two-run debugging. | | aether_package | Create shareable Evidence Pack (Pro). Use last_error for quick share. |

20-Second Ritual

Run game once
aether_triage
aether_package last_error
Optional: aether_recon → aether_probe plan_id → rerun

aether_triage

Free

Start here. One command → last run metadata, top suspects, 3 receipts, capsule path, next-step hints. Use for the 20-second ritual.

Parameters

window_seconds(number)

Time window in seconds (default: 10, max: 60)

Example

cursor-chat

@aether triage

ℹ️When to Use

This is the primary tool. Use it whenever the human asks "what happened?", "did you see that?", or describes a gameplay issue. It returns last run metadata, top suspects, receipts, capsule path, and exactly two next-command hints.

aether_last_run_answer

Free

Power-user primitive: ranked suspects, receipts, next actions. Use when aether_triage isn't enough. Returns full answer with configurable limits.

Parameters

window_seconds(number)

Time window in seconds (default: 10, max: 60)

include_errors(boolean)

Include errors in the answer payload (default: true)

include_events(boolean)

Include non-delta events in timeline if needed (default: true)

include_semantic_deltas(boolean)

Include semantic delta events (default: true)

baseline_id(string)

Optional baseline clip ID to compare against (Pro/Studio)

max_deltas(integer)

Hard cap override for deltas (bounded by tier)

max_receipts(integer)

Maximum receipts to return (default: 3 Free / 7 Pro)

Example

cursor-chat

@aether last_run_answer

ℹ️When to Use

Pro. Use when aether_triage isn't sufficient — e.g. need more receipts, baseline comparison, or custom window.

aether_snapshot

Free

Get current Unity state: selected object snapshot (if any), current scene/frame/time, last N events, last N console entries, optional UI focus summary. Returns surgical GTML snapshots for suspect objects.

Parameters

include_ui(boolean)

Include UI snapshot summary (default: true)

event_count(integer)

Number of recent events to include (default: 10, max: 50)

console_count(integer)

Number of recent console entries to include (default: 10, max: 50)

Example

cursor-chat

@aether snapshot

ℹ️When to Use

Use for a point-in-time view of the game. Perfect for "What's the current game state?", "What objects are active?", "What's happening right now?"

aether_console

Free

Query Unity console logs with text, level, and time filters. The primary tool for searching and filtering Unity stdout output.

Parameters

text(string)

Case-insensitive substring match against message or stack trace

levels(array)

Filter by Unity log level(s): Log, Warning, Error, Exception, Assert

seconds(number)

Time window ending now in seconds (default: 60, max: 600)

since_ms(integer)

Explicit window start timestamp (ms)

until_ms(integer)

Explicit window end timestamp (ms)

run_id(string)

Filter by run_id (default: last seen run)

limit(integer)

Maximum entries to return (default: 200, max: 1000)

include_stack(boolean)

Include full stack traces (default: false)

order(string)

Sort order by timestamp (default: desc)

Example

cursor-chat

@aether console "NullReference"

ℹ️When to Use

Use when you need to search or filter Unity logs:

"Show me errors from the last minute"
"Find logs containing 'MissingReference'"
"Filter warnings only"

aether_observe

Free

Primary tool for understanding runtime behavior. Returns keyframe captions + state deltas + relevant logs + compact narration within a time window. Pro tier includes visual morph detection and richer evidence.

Parameters

window_seconds(number)

Time window in seconds (default: 10, max: 60)

budget_tokens(integer)

Target token budget for response (default: 2000). Lower = more aggressive compression.

include_keyframes(boolean)

Include keyframe captions (Pro only, default: true)

include_deltas(boolean)

Include semantic state deltas (default: true)

include_logs(boolean)

Include grouped/filtered logs (default: true)

morph_only(boolean)

Only return morph-triggered keyframes (Pro only, default: false)

include_vision(boolean)

Include VLM analysis (Pro only, default: false)

vision_focus(string)

Optional focus hint for vision analysis (e.g., 'terrain morphing', 'AI behavior')

Example

cursor-chat

@aether observe 15

ℹ️When to Use

Use for a rich summary of recent runtime behavior. Combines keyframes, state deltas, logs, and narration into one compact response. Preferred over aether_tail for most use cases.

aether_recon

Free

Use when core tools aren't enough. Analyzes symptoms, forms hypotheses, and generates an instrumentation plan with 3-5 targeted probes for two-run debugging.

Parameters

goal(string)

What are you trying to understand or fix? E.g., 'card vanished from hand', 'AI made wrong decision'

mark_id(string)

Optional mark/clip ID to anchor the investigation

window_before_s(number)

Seconds before the symptom to analyze (default: 2.0)

window_after_s(number)

Seconds after the symptom to analyze (default: 0.5)

baseline_id(string)

Optional baseline run ID to compare against (Pro/Studio)

Example

cursor-chat

@aether recon "card vanished from hand"

ℹ️When to Use

Use when the standard tools (last_run_answer, observe, console) can't explain the issue. Generates a surgical probe plan for a second run to collect the exact data needed.

Advanced Tools

These tools are available to your agent but are used in specialized workflows. You don't need to know about these — your agent will use them when appropriate.

Event Streaming

aether_tail

Free

Lightweight alternative to aether_observe. Returns events + console in a time window with top state changes. Use when you need a quick summary with minimal tokens.

Parameters

seconds(number)

Time window in seconds (default: 10, max: 60)

include_changes(boolean)

Include top state changes summary (default: true)

max_events(integer)

Maximum events to return (default: 50, max: 200)

Example

cursor-chat

@aether tail 30

ℹ️When to Use

Lightweight alternative to aether_observe. Use when you need a fast, low-token summary of recent events without keyframes or narration.

Deep Inspection

aether_inspect

Free

Deep-inspect a specific GameObject or component. Returns reflection state in diff-friendly format with resolved references and metrics.

Parameters

target(string)

Target to inspect: GameObject path, component type, or 'selection'

depth(integer)

Reflection depth limit (default: 4, max: 8)

include_private(boolean)

Include private fields (default: true)

diff_format(boolean)

Output in diff-friendly format (default: true)

include_metrics(boolean)

Include component-specific metrics (default: true)

Example

cursor-chat

@aether inspect "/World/Player"

ℹ️When to Use

Use when you need granular object/component state beyond what aether_snapshot provides. Targets specific GameObjects by path, component type, or Editor selection.

Clips and Marks

aether_mark

Free

Save this moment for later replay or packaging. Persists last context_seconds. Returns clip_id.

Parameters

label(string)

Optional label for the clip

context_seconds(number)

Seconds of context to capture before this moment (default: 10)

post_seconds(number)

Seconds to capture after this moment if arming (default: 0, no arming)

arm_until_trigger(boolean)

If true, arm capture until next exception/probe failure (default: false)

include_screenshot(boolean)

Include screenshot in clip (default: false)

Example

cursor-chat

@aether mark "Before applying fix"

ℹ️When to Use

Save important moments for later replay (aether_getClip) or packaging (aether_package). Use before attempting fixes so you can verify or share later.

aether_clip

Free

Create a time-window clip with explicit before/after control. Similar to aether_mark. Returns clip_id.

Parameters

seconds_before(number)

Seconds of history to capture (default: 10)

seconds_after(number)

Seconds to capture after current moment (default: 5)

Example

cursor-chat

@aether clip 20 5

ℹ️When to Use

Similar to aether_mark but with explicit before/after window control. Use to capture a specific time range around the current moment.

aether_getClip

Free

Replay evidence from a previously saved clip. Returns events, console, and state changes for the clip window.

Parameters

clip_id(string)

Required

The clip ID (e.g. 'clip_a1b2c3d4')

include_changes(boolean)

Include top state changes summary (default: true)

Example

cursor-chat

@aether getClip clip_a1b2c3d4

ℹ️When to Use

Retrieve a previously marked/clipped moment for replay and analysis.

Two-Run Debugging

aether_instrument

Free

Follows aether_recon. Returns execution instructions, code templates, and agent guidance for inserting probes. Stateless.

Parameters

plan(object)

Required

InstrumentationPlanV1 from aether_recon

plan_id(string)

Optional plan_id to verify against plan content

Example

cursor-chat

@aether instrument <plan>

ℹ️When to Use

Use after aether_recon to get probe insertion instructions for Run 2.

aether_window

Free

Retrieve probe results after Run 2. Returns time-ordered probe/intent/effect/observation events around a mark.

Parameters

mark_id(string)

Mark/clip ID to center the window on

window_start_ms(integer)

Explicit window start timestamp (ms)

window_end_ms(integer)

Explicit window end timestamp (ms)

seconds_before(number)

Seconds before mark/now (default: 10)

seconds_after(number)

Seconds after mark/now (default: 0.5)

filter(string)

Filter events: all, probes_only, causal

Example

cursor-chat

@aether window clip_a1b2c3d4

ℹ️When to Use

Use after Run 2 to analyze probe events and verify/refute hypotheses from aether_recon.

Pro Features

aether_probe

Pro

Generate and install diagnostic probe snippets from an instrumentation plan. Pro/Studio only.

Parameters

plan(object)

Required

Instrumentation plan object from aether_recon/aether_instrument

auto_run(boolean)

Automatically enter Play mode after probe installation (default: true)

run_duration_seconds(number)

How long to run before collecting (default: 5)

auto_cleanup(boolean)

Remove probe scripts after collection (default: true)

collect_keyframes(boolean)

Capture keyframes during probe run (default: true)

Example

cursor-chat

@aether probe <plan>

⚠️Pro Feature

Install probes at runtime without recompiling. The AI agent handles the full probe lifecycle: install, run, collect, clean up.

aether_verify

Pro

Verify a fix worked: compares baseline vs current evidence using visual similarity + numeric metrics + log regression. Pro/Studio only.

Parameters

baseline_id(string)

Baseline clip/run ID to compare against

goal(string)

What should be true after the fix

window_seconds(number)

Time window for current evidence (default: 10)

visual_threshold(number)

Hamming distance threshold for visual similarity (default: 12)

require_no_new_errors(boolean)

Fail if new errors appeared (default: true)

metrics_to_check(array)

Specific metrics to verify (e.g., ['mesh_bounds', 'height_variance'])

Example

cursor-chat

@aether verify clip_before

⚠️Pro Feature

Automated before/after comparison. "Fixed means fixed" — the AI confirms your fix with visual similarity, metric checks, and log regression.

aether_vision_observe

Pro

Analyze keyframes with a Vision Language Model (VLM) to understand what happened visually. Pro/Studio only.

Parameters

window_seconds(number)

Time window in seconds to analyze (default: 10, max: 60)

backend(string)

Vision backend: auto (default, uses cloud for Pro), cloud (Aether proxy), local (Ollama), gemini (own API key)

max_frames(integer)

Maximum frames to send to VLM (default: 12, range: 3-20)

morph_only(boolean)

Only include morph-triggered frames (default: false)

focus_hint(string)

Optional hint about what to look for

budget_tokens(integer)

Target token budget for VLM response (default: 2000)

Example

cursor-chat

@aether vision_observe

⚠️Pro Feature

Pro users get cloud vision automatically — no API key or local setup needed. For privacy-sensitive projects, set AETHER_LOCAL_VISION_URL=http://localhost:11434 to use a local Ollama backend instead.

aether_package

Pro

Package a debugging session into a shareable Capsule. Captures timeline + errors + context. Pro adds ranked suspects and source links.

Parameters

target(string)

Required

Target to package: 'last_crash', 'last_error', 'last_mark', or 'session'

session_id(string)

Session ID (required if target is 'session')

window_seconds(number)

Time window in seconds (default: 60, only for 'session' target)

Example

cursor-chat

@aether package last_error

ℹ️When to Use

Package a debugging session for sharing or later analysis. Creates a self-contained Capsule with timeline, errors, and context.

aether_viewCapsule

Free

View a previously generated capsule. Returns metadata, file path, and viewer URL.

Parameters

capsule_id(string)

Optional specific capsule ID to view. If omitted, shows the last capsule.

Example

cursor-chat

@aether viewCapsule

ℹ️When to Use

Use after aether_package to view the capsule contents and get the viewer URL.

aether_proofclip_draft

Pro

Create a Proof Clip draft from a marked clip. Selects keyframes, generates captions, and persists a draft manifest. Pro/Studio only.

Parameters

clip_id(string)

Required

Clip ID to draft from

context_seconds(number)

Seconds of context before the clip timestamp (default: 10)

post_seconds(number)

Seconds after the clip timestamp (default: 0)

style(string)

Caption style preset: devlog, technical_receipt, player_hype (default: devlog)

max_frames(integer)

Maximum frames to include (default: 12)

min_spacing_ms(integer)

Minimum spacing between frames in ms (default: 500)

verify_result(object)

Optional VerifyResult from aether_verify for proof receipts

Example

cursor-chat

@aether proofclip_draft clip_a1b2c3d4

ℹ️When to Use

Turn a marked moment into a shareable proof clip draft. Exports to video for devlogs and marketing.

aether_proofclip_export

Pro

Export a Proof Clip (video + copy + Steam link) from a draft. Pro/Studio only.

Parameters

clip_id(string)

Required

Clip ID to export

preset(string)

Required

Export format preset: shorts_9x16, square_1x1, wide_16x9

style(string)

Caption style preset (default: draft style or devlog)

steam_url(string)

Steam store URL for UTM link generation

platform(string)

Platform for attribution (e.g., tiktok, youtube, x)

campaign(string)

Campaign name for UTM (default: proof_clip)

baseline_clip_id(string)

Optional baseline clip ID to generate a Fix Reel (before/after)

verify_result(object)

Optional VerifyResult from aether_verify for proof receipts

Example

cursor-chat

@aether proofclip_export clip_a1b2c3d4 shorts_9x16

ℹ️When to Use

Export a finished proof clip for marketing, devlogs, or QA documentation.

Utility

aether_docs

Free

Get authoritative documentation for Aether tools and concepts.

Parameters

topic(string)

Documentation topic: tools, capsules, setup, troubleshooting, or all

tool_name(string)

Specific tool name to get documentation for

Example

cursor-chat

@aether docs tools

ℹ️When to Use

Your agent can self-serve tool documentation. Rarely needed — the agent already has tool schemas from the MCP connection.

Usage Patterns

Standard Debugging (most common)

Triage — @aether triage → get last run metadata, suspects, receipts, next-step hints
Search logs — @aether console "ErrorText" → filter relevant logs
Watch behavior — @aether observe 15 → see keyframes + deltas + narration
Inspect state — @aether snapshot → point-in-time game state

Two-Run Debugging (hard-to-reproduce bugs)

Recon — @aether recon "describe the bug" → get instrumentation plan with plan_id
Probe — @aether probe plan_id (or pass full plan) → get probe snippets
Run 2 — Reproduce the issue after inserting probes
Analyze — @aether observe or @aether window <mark_id> → analyze probe results

Mark — @aether mark "Before fix" → save state
Package — @aether package last_error → create shareable capsule
View — @aether viewCapsule → inspect capsule contents

Proof Clip Export (Pro)

Mark — @aether mark "Wishlist spike moment"
Draft — @aether proofclip_draft clip_xxx
Export — @aether proofclip_export clip_xxx shorts_9x16

Response Format

All tools return JSON-RPC 2.0 responses with:

Success: { "jsonrpc": "2.0", "id": 1, "result": {...} }
Error: { "jsonrpc": "2.0", "id": 1, "error": {...} }

Results contain GTML-formatted data for AI consumption.

Best Practices

Start with aether_triage — it gives last run metadata, suspects, receipts, and next-step hints in one call
Use observe over tail — richer output with keyframes, deltas, and narration
Escalate to recon only when needed — most issues are diagnosed with core tools
Mark before fixes — save state so you can verify or share later

If You See X → Do Y

| If you see… | Do this | |-------------|---------| | "No run recorded" | Enter Play in Unity, reproduce the bug, then run aether_triage | | "No crash or error found" | Run the game until an error occurs, or use aether_package last_mark if you have a mark | | "Bridge not connected" | Reload Cursor window; ensure aether-bridge is running (check Output: Aether) | | "Invalid plan" | Run aether_recon first, then pass the full instrumentation_plan (or plan_id) to aether_probe | | "Capsule not found" | Run aether_package last_error (or last_crash / last_mark) | | "Run aged out" | Re-run the game and package again. Check retention: aether_doctor | | Any other failure | Run aether_doctor for diagnosis and fix steps |

Next Steps

Learn about Capsules and how they work
See Recipes for common tool usage patterns
Check Troubleshooting if tools aren't working

MCP Tools Reference

Core Tools

20-Second Ritual

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example

Advanced Tools

Event Streaming

Parameters

Example

Deep Inspection

Parameters

Example

Clips and Marks

Parameters

Example

Parameters

Example

Parameters

Example

Two-Run Debugging

Parameters

Example

Parameters

Example

Pro Features

Parameters

Example

Parameters

Example

Parameters

Example

Capsules and Sharing

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example

Utility

Parameters

Example

Usage Patterns

Standard Debugging (most common)

Two-Run Debugging (hard-to-reproduce bugs)

Packaging and Sharing (Pro)

Proof Clip Export (Pro)

Response Format

Best Practices

If You See X → Do Y

Next Steps