What can you do with this server?

Framesleuth is a local video analysis service over MCP that turns any video into a structured Context Bundle for coding agents. * Analyze any video frame-by-frame, with optional intent, skill, action, and custom prompts, generating a Context Bundle. * List available summary skills and action modes to guide analysis. * Manage reports: list all reports, retrieve full or slim bundles, get reproduction steps, error evidence, timeline, keyframe images, and animated GIF previews. * Get suggested next steps for a report. * Render shareable artifacts in Markdown, GitHub issue, or test-plan formats. * Locate suspect code in a repository based on analysis candidates. * Render HTML animations to video (MP4/GIF/WebM).

How do I use Framesleuth?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Framesleuth Analyze this bug recording and create a context bundle to fix the crash." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Framesleuth

by thestackhub1

Overview Schema Related Servers Score Discussions

Python

Local

Framesleuth

Local video → structured context for coding agents, exposed over MCP.

Feed Framesleuth a video and it reads it frame by frame, folds in optional browser sidecars, and produces a structured Context Bundle. Any video works: a bug recording, a feature demo, a design walkthrough, a Loom, a phone capture.

The bundle is served over MCP, so a VS Code agent, another coding agent, or your own system can drive the analysis and use the result to fix a bug, change a feature, or build something new, grounded in what the video actually shows.

Capture happens outside this repo, which holds the analysis agent only. A browser capture extension can record a session and post the video plus sidecars to the local API.

Everything runs locally. Nothing leaves your machine.

Quick start

Going from a video to a grounded change inside VS Code? See Use with VS Code & Claude (MCP): connect the bundled MCP server, then turn a recording into a fix, a feature, or a new build.

Fastest: one command with Docker

One command brings up the model server, the models, and the API. No Python, no virtualenv, no manual model setup.

git clone https://github.com/thestackhub1/framesleuth-agent.git
cd framesleuth-agent
docker compose up            # or: ./scripts/dev_up.sh

Compose picks up docker-compose.override.yml automatically; that file adds the Ollama server, the model-pull job, and the model volume. The first run pulls the vision and coder models (qwen2.5vl and qwen2.5-coder:7b, ~11 GB total) into a Docker volume, then starts the backend on http://127.0.0.1:8010. Later runs are instant. It's ready when the health check says healthy:

curl -s http://127.0.0.1:8010/v1/healthz | python -m json.tool   # "status": "healthy"

That's the whole setup. Run your first analysis below, or connect the MCP server in your editor (VS Code & Claude).

docker compose logs -f                  # follow progress / model download
docker compose down --remove-orphans    # stop  (add -v to also delete model volumes)

The stack runs its own Ollama on the internal Docker network and never publishes its port, so it won't clash with a native Ollama on :11434. The only host port is the API on :8010.

Already running Ollama natively with the models pulled? The Docker stack ships its own Ollama and would download them again. Use the direct path below instead. It reuses your existing Ollama and is faster, especially on macOS, where Docker can't reach the GPU.
On macOS, or anywhere without a GPU, Docker runs the models on CPU and the vision model is slow. On Linux with an NVIDIA GPU, uncomment the deploy: block on the ollama service in docker-compose.override.yml.
To run only the backend container against a native or external model server, use docker compose -f docker-compose.yml up. The base compose file defaults to native Ollama on http://host.docker.internal:11434; override VLM_URL and CODER_URL for another server.
Docker users: don't cp .env.example .env. If you already did, comment out VLM_URL and CODER_URL in it. Compose reads .env and those values beat the defaults above, and .env.example ships the native 127.0.0.1, which inside a container means the container itself. The symptom is a backend that starts cleanly and then can't reach any model.

Run your first analysis (curl)

Once the API reports healthy, either setup path, three calls take you from a video to a Context Bundle. Analysis is async: submit, poll, read.

No recording handy? Generate a throwaway one. It exercises the whole pipeline and takes about a second.

uv run python scripts/make_sample_video.py     # writes sample.mp4

# 1. Submit any screen recording (mp4/webm). Returns 202 { job_id, ... }
JOB=$(curl -s -F "video=@sample.mp4" http://127.0.0.1:8010/v1/analyze \
  | python -c "import sys, json; print(json.load(sys.stdin)['job_id'])")

# 2. Poll until state is "done" (queued → running → done)
curl -s "http://127.0.0.1:8010/v1/jobs/$JOB" | python -m json.tool

# 3. Read the Context Bundle
curl -s "http://127.0.0.1:8010/v1/report/$JOB" | python -m json.tool

Step 1 takes optional form fields: -F intent="why does save hang?", -F skill=bug_report, -F action=fix. GET /v1/skills and /v1/actions list the choices. Prefer a UI? The Postman collection chains these calls for you.

Run it directly (no Docker — fastest on macOS, best for development)

You need Python 3.11+, uv, 8 GB+ RAM, and a local model server. ffmpeg isn't required, since PyAV bundles its own; if ffprobe happens to be on PATH it's used to detect an audio stream.

git clone https://github.com/thestackhub1/framesleuth-agent.git
cd framesleuth-agent

# 1. Models — native Ollama (uses the Mac GPU) is the quick path
ollama serve &                                  # skip if already running
ollama pull qwen2.5vl && ollama pull qwen2.5-coder:7b

# 2. Install — from uv.lock, so you get the versions CI actually tested
uv sync --frozen --extra dev
source .venv/bin/activate
python scripts/download_models.py               # optional: pre-warm ASR + check servers

# 3. Configure + start the API (binds 127.0.0.1:8010)
cp .env.example .env                            # already defaults to the Ollama path above
framesleuth-api                                 # or: uvicorn framesleuth.service.api:app --port 8010

# 4. Verify  (says so either way — a silent command is not a passing check)
curl -s http://127.0.0.1:11434/v1/models | grep -q qwen2.5vl \
  && echo "VLM ready" || echo "VLM NOT ready — run: ollama pull qwen2.5vl"
curl -s http://127.0.0.1:8010/v1/healthz | python -m json.tool   # status: healthy, vlm: ready

When /v1/healthz shows vlm: ready, recordings get a real classification (analysis_quality.level of full or partial). ready means the server answered and listed your VLM_MODEL. If the model was never pulled you get vlm: degraded with model '<name>' not loaded instead.

With no vision model reachable at all, Framesleuth degrades gracefully. It still produces a valid Context Bundle from the browser sidecars (console errors, failed requests, clicks) and records what was thin in analysis_quality. Narrate while you record and the audio transcript (asr) stage contributes too.

Something not working? Run the setup doctor. It runs under a plain python3 even when your virtualenv is broken, and prints a one-line fix for each problem: a stale or missing venv, framesleuth-api not on PATH, ffmpeg and render prerequisites, an unreachable backend or model server, a wrong VLM_URL.
python3 scripts/doctor.py
The common one: command not found: framesleuth-api, or a uv pip install error about a missing interpreter, means your active venv was deleted or moved. Fix it from the framesleuth directory: deactivate; unset VIRTUAL_ENV; uv sync --frozen --extra dev; source .venv/bin/activate.

Stop

# Stop the backend: Ctrl+C in its terminal, or
pkill -f framesleuth-api

# Stop Ollama (optional — leaving it running keeps the model warm)
pkill -f "ollama serve"              # macOS app users: quit Ollama from the menu bar

Related MCP server: Framesleuth

Architecture

Any video (mp4/webm) + optional sidecars
    ↓
Local Analysis Service (pipeline)
    ├─ Preprocess (PyAV: duration/fps/dims)
    ├─ Transcript (faster-whisper)
    ├─ Keyframes (visual-delta change scoring)
    ├─ Understanding (local vision model — Qwen2.5-VL by default)
    ├─ Fusion + Classification
    ├─ Extraction → Context Bundle
    ├─ Summarize (skill/system-prompt-driven)
    └─ Grounding (workspace search)
    ↓
Context Bundle
    ↓
MCP server + local HTTP API
    └─ consumed by any MCP client (VS Code agent, other agents, capture extension)

Features

Frame-by-frame understanding with a local vision model (Qwen2.5-VL by default; engine-agnostic)
Adaptive keyframe selection. Coverage-binned and visual-salience-ranked (AKS-style), with a build-aware budget for feature and design videos. Perceptual-hash dedup drops near-identical frames so the VLM budget goes on distinct content.
Bug and build. A feature class plus a structured build context: screens, UI components, a screen-to-screen user flow, design notes, and where to implement. An agent can build from it, not only diagnose.
Error detection and extraction from console, OCR, and UI state
Corpus-aware grounding. Error symbols or feature/UI nouns resolve to ranked file:line hits. Definitions are preferred, distinctive symbols weighted via IDF plus whole-word match, .gitignore respected, and the search bounded for large repos.
Trust signals. Per-field confidence, where agreeing signals across modalities corroborate each other, plus a task-aware actionability (ready/thin/insufficient) alongside the pipeline quality level.
Redaction-first design. Secrets (passwords, tokens, keys) and PII (emails, Luhn-valid card numbers, SSNs/phones, cloud keys) are scrubbed from OCR, captions, the transcript, and the raw sidecar streams before any of it reaches a model or is persisted. That covers the bundle and the sibling timeline.json, sidecars.json and transcript.json.
Observability. Per-stage timings land on every bundle (stage_timings) and live on GET /v1/jobs/{id}, so you can see where analysis time went.
Job lifecycle and delivery. Cooperative cancellation (DELETE /v1/jobs/{id}, checked between frames), a hard per-job timeout (JOB_TIMEOUT_S), crash recovery that fails orphaned jobs on restart rather than leaving zombies, SSE progress with explicit terminal events (GET /v1/jobs/{id}/events), a completion webhook (WEBHOOK_URL), real queue depth in /healthz, and TTL retention cleanup (BUNDLE_TTL_DAYS) swept at startup and periodically (RETENTION_SWEEP_INTERVAL_S).
Interaction overlay. A click/cursor sidecar with coordinates draws a marker on the matching keyframe, so the model sees where the user acted.
Cleaner transcripts. faster-whisper voice-activity filtering (ASR_VAD_FILTER) drops silence before decoding; the detected or forced language is recorded.
OCR backstop (optional ocr extra). A sparse VLM OCR on an error frame gets a second, independent Tesseract reading. Without the extra it's a no-op.
No data leaves your machine. Fully local, no telemetry, no cloud APIs.
Engine-agnostic. Swap Ollama, llama.cpp, or vLLM via config only.
Works on any video, not just bug recordings. A demo, a walkthrough, a talk, a phone clip: each yields a faithful summary and a timeline of key moments (summary, key_moments[]) rather than something forced into a bug shape. The bug-only fields (severity, expected/actual, repro steps) stay null instead of carrying fabricated placeholders.
Structured output. A canonical Context Bundle with evidence citations.
Configurable response. Pick a summary skill and an action mode (fix/implement/design/summarize/explain/triage/test/report/reproduce, auto-picked from the classification), plus a machine-readable suggested_actions menu and on-demand artifact renderers (markdown, GitHub issue, test plan).
Eval harness. Model-free classification, grounding, citation and faithfulness suites (python scripts/eval_harness.py --behavioral) run in CI on every push and PR: a GitHub Actions 3.11/3.12 matrix of ruff, black, mypy --strict, pytest behind a coverage gate, the eval harness against per-metric thresholds in evals/, and an OpenAPI-freshness check, plus a separate security job running pip-audit and pre-commit. The faithfulness suite proves every emitted key moment and step cites real, resolvable evidence.
Resilient. Handles no-audio videos, weak local models, and low-confidence cases.
HTML → video (frame-by-frame). Turn a self-contained HTML animation (CSS/JS/canvas) into MP4, GIF, or WebM via the render_html_video MCP tool or POST /v1/render-html. Frames are captured one at a time under a paused virtual clock and encoded to a color-correct H.264 MP4 (yuv420p+bt709, near-lossless): full color, no dropped frames, no quality loss, up to 4K and 5–60 fps. The Docker image includes it by default (headless Chromium + ffmpeg). On the direct path, add the render extra (see below); without it the endpoint returns 503 with an actionable message.

Enable & troubleshoot HTML → video

On Docker (docker compose up) this already works; the image bakes in Playwright, Chromium and ffmpeg. Build with --build-arg INSTALL_RENDER=false for a slimmer image without it. The steps below are for the direct path.

Playwright lives in an optional [render] extra rather than core, because it pulls a ~150 MB headless-Chromium browser the video→bundle pipeline never needs. (av, opencv and faster-whisper are core.) Install the extra and you're done. The Chromium build downloads on your first render, so there's no separate playwright install chromium step:

# In the same environment the server runs in:
uv sync --frozen --extra dev --extra render   # or --all-extras
# ffmpeg must be on PATH (brew install ffmpeg / apt-get install ffmpeg)

# Restart framesleuth-api, then verify (Chromium fetches itself on first render):
curl -s http://127.0.0.1:8010/v1/healthz | python -m json.tool
# → "render": {"playwright": true, "chromium": <true after first render>, "ffmpeg": true}

Set FRAMESLEUTH_AUTO_INSTALL_BROWSER=0 to disable the auto-download and run playwright install chromium yourself, e.g. in a locked-down environment.

The other optional extra is ocr. For the dedicated OCR backstop on error frames, run uv sync --frozen --extra dev --extra ocr and put the tesseract binary on PATH (brew install tesseract / apt-get install tesseract-ocr). Absent, it's a no-op: the VLM still does OCR, and the backstop only adds a second reading. Use ".[all]" for dev + render + ocr.

If render.ready is false, ask /v1/version for the details. /v1/healthz is public, so it omits the hint and python fields rather than publish the server's filesystem layout to an unauthenticated caller:

curl -s http://127.0.0.1:8010/v1/version | python -m json.tool
# → "render": {"ready": false, "hint": "...", "python": "/path/to/the/interpreter", ...}
# With API_TOKEN set, this endpoint is token-gated:
#   curl -s -H "Authorization: Bearer $API_TOKEN" http://127.0.0.1:8010/v1/version

render.hint tells you what's missing. When you followed the steps and still get "Playwright is not installed", it's usually one of two things: framesleuth-api is running from a different environment than the one you installed into (render.python names the interpreter it uses), or the server wasn't restarted.

Project structure

framesleuth/
├── framesleuth/              # Main package
│   ├── config.py            # Typed config (pydantic-settings)
│   ├── schemas.py           # Data contracts (Context Bundle, enums)
│   ├── errors.py            # Exception taxonomy
│   ├── logging_config.py    # Structured JSON logging, job-id correlation
│   ├── prompts.py           # VLM / classify / summary / fix prompt templates
│   ├── skills.py            # Built-in summary skills (summary, bug_report, ...)
│   ├── actions.py           # Action modes (fix/explain/triage/...) + suggested-actions menu
│   ├── render.py            # Artifact renderers (markdown / GitHub issue / test plan)
│   ├── clients/             # VLM, coder HTTP clients (OpenAI-compatible)
│   ├── pipeline/            # preprocess, asr, scenes, understand, fusion, classify,
│   │                        #   bug_extract, build_context, confidence, dedup, overlay,
│   │                        #   ocr, redact, summarize, sidecars, grounding, gif,
│   │                        #   atomic, html_render
│   ├── eval/                # harness.py — model-free behavioral suites
│   ├── orchestrator/        # graph.py — linear async stage pipeline
│   ├── jobs/                # store.py — SQLite job state + bundle index
│   ├── service/             # FastAPI HTTP endpoints
│   └── mcp_server/          # framesleuth MCP server (VS Code + any MCP client)
├── tests/                   # pytest tests + fixtures
├── scripts/                 # doctor.py (setup check), download_models.py, dev_up.sh,
│                            #   eval_harness.py, export_openapi.py
├── evals/                   # thresholds.json + baseline.json (the CI quality gate)
├── openapi.json             # generated API schema — the contract clients build from
├── postman/                 # HTTP API collection + environment
├── docs/                    # capabilities, use-with-vscode-and-claude, web-integration
└── pyproject.toml           # Dependencies and tool config

Development

Run tests

pytest tests/ -q                                        # fast: no coverage gate
pytest tests/ -q --cov=framesleuth --cov-fail-under=75  # what CI enforces

Regenerate the API schema (after changing any route)

python scripts/export_openapi.py --out openapi.json

CI fails if this file is stale; the website generates its typed client from it.

Run the eval gates

python scripts/eval_harness.py --behavioral   # see evals/README.md

Code quality

ruff check framesleuth tests
black --check framesleuth tests
mypy --strict framesleuth

Set up pre-commit hooks

pre-commit install

Docs, a short and focused set:

Capabilities. One reference for every input, output, skill, action, renderer, HTTP endpoint and MCP tool.
Use with VS Code & Claude (MCP). Connect the framesleuth MCP server to Copilot, Claude Code, and Claude Desktop.
Web App Integration (end-to-end). Embed Framesleuth behind your own backend with an agent loop.
Postman Collection. Exercise the HTTP API end to end, in the app or headless with Newman.
Runbook & Troubleshooting. Setup, health checks, and common issues.

License

Apache-2.0

Capture client

Bug capture lives outside this repo. Any screen recording works, so you can drive the agent with your own video file. A browser capture extension can also record a session, collect browser sidecars (console errors, failed requests, clicks), and post the video plus sidecars to this agent's local API.

CORS is an exact allowlist. The local dev origins http://localhost:3000 and http://127.0.0.1:3000 are on by default; set ALLOW_LOCAL_DEV_ORIGINS=false on a hardened deployment to drop them. chrome-extension:// origins come from the IDs you list in CHROME_EXTENSION_IDS, empty by default, so a capture extension has to add its own. Everything else goes in WEB_ORIGINS, also empty by default: no remote site is trusted, framesleuth.com included. The agent answers Chrome's Private Network Access preflight, so an allowed origin can drive a backend running locally.

To let the hosted "Try it" widget talk to your agent, opt in explicitly:

WEB_ORIGINS=https://framesleuth.com,https://www.framesleuth.com

The agent stays bound to loopback; CORS only controls which browser origins may read its responses.

Set API_TOKEN for anything beyond a single-user laptop. With a token set, every /v1 endpoint except /v1/healthz requires Authorization: Bearer <token>. CORS won't stop another local process, or a DNS-rebinding page, from sending requests to loopback. A token will. The Docker stack reads it from .env, and publishes the API on 127.0.0.1 only.

Status: backend, pipeline and MCP server are complete.

Questions? Open an issue, or check runbook.md for common ones.

Available Tools

14 tools

analyze_videoA

Analyze any video and return the new report id.

Works on any kind of video — a bug recording, a feature demo, a design walkthrough, a Loom, a phone capture — and distills it into a structured Context Bundle a coding agent can act on (fix a bug, add or change a feature, or build something new).

Args: path: Path to the video file (.mp4/.webm/.mkv/.mov/.avi). repo_root: Repo to ground references against (pass the open workspace). intent: The user's request to act on, e.g. "fix the save button that hangs", "add a dark-mode toggle like the demo shows", or "build this onboarding screen from the walkthrough". It is recorded on the report and shapes the generated action prompt so the calling agent does what the user actually asked. skill: Built-in summary style — one of the names from list_skills (e.g. "summary", "bug_report", "tutorial", "action_items"). Defaults to "summary". system_prompt: A fully custom system prompt for the summary; overrides skill when provided. action: Built-in action mode shaping the fix-prompt — one of the names from list_actions (e.g. "fix", "explain", "triage", "test", "report", "reproduce"). Auto-picked from the classification when omitted. action_prompt: A fully custom action task; overrides action. ctx: The MCP request context, injected by the server; used to stream progress to the client during the (multi-minute) analysis.

Returns the report id, the summary/fix-prompt resource URIs, the resolved action, and the derived suggested_actions menu.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`skill`	No
`action`	No
`intent`	No
`repo_root`	No
`action_prompt`	No
`system_prompt`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses important behavioral traits: analysis takes multiple minutes, progress is streamed via ctx, action is auto-picked when omitted, and system_prompt/action_prompt override skill/action. This adds meaningful context without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: a one-line summary, use-case framing, a complete Args block, and Returns expectations. It is well-structured and front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is self-contained: it covers purpose, usage, all parameter semantics, behavioral notes, and return values. It references sibling tools like list_skills and list_actions for valid enum values, and the output schema is complemented by the explicit Returns list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since schema description coverage is 0%, the description fully compensates by explaining every parameter in detail: path formats, repo_root grounding, intent examples and effect, skill/action enum hints with defaults, and override relationships. This goes far beyond the raw schema types and null defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Analyze any video and return the new report id', which clearly states the verb, resource, and output. It distinguishes itself from sibling get_*/list_* tools by emphasizing creation of a new report from video input, reinforced by the diverse video examples.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear when-to-use context: any video that needs to be distilled into an actionable Context Bundle for a coding agent. It does not explicitly mention alternatives or exclusions, but the use case is specific enough for an agent to select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_error_evidenceB

Read-onlyIdempotent

Return the timestamped error evidence for a report.

ParametersJSON Schema

Name	Required	Description	Default
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds 'timestamped' as a trait of the returned data but doesn't disclose other behavioral details such as error handling, return format, or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that avoids redundancy and gets straight to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one parameter and an output schema, the description is minimal but somewhat sufficient. It lacks usage context and explicit differentiation from siblings, leaving some ambiguity about when to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single parameter (report_id) with no description, and the description's phrase 'for a report' provides some semantic context linking the parameter to a report. However, it does not explain the expected format or value domain beyond the schema's type string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Return') and resource ('timestamped error evidence for a report'). It distinguishes from sibling tools like get_timeline and get_repro_steps by focusing on error evidence, though it doesn't explicitly contrast with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like get_timeline or get_repro_steps. The description only states what it does, not in which situations it should be chosen.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_keyframe_imageA

Read-onlyIdempotent

Return a keyframe image for a report by its index.

ParametersJSON Schema

Name	Required	Description	Default
`index`	Yes
`report_id`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, which are consistent with the 'Return' operation. The description does not add extra behavioral context such as output format, error handling, or index bounds. Since annotations cover the safety profile, this is adequate but not enriched.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence, front-loaded with the action and resource. No wasted words, and it covers the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter getter with read-only and idempotent annotations, the description is mostly complete. It states what is returned and how it is selected. It could mention the return format (e.g., URL or binary) but given the simplicity, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description clarifies that 'index' selects the keyframe by its position. The role of 'report_id' is not explicitly explained, though its name is self-descriptive. This partially compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Return a keyframe image for a report by its index' clearly states the action (return), the resource (keyframe image), and the selection method (by report and index). It distinguishes from sibling tools like get_video_gif and render by specifying 'keyframe image' and 'report' context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when a specific keyframe image from a report is needed, identified by an index. However, it does not provide explicit guidance on when to choose this over alternatives like get_video_gif or get_report, nor does it mention any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_reportA

Read-onlyIdempotent

Return the Context Bundle for a report id.

view="full" (default) returns everything; view="slim" returns the action-relevant subset (classification, quality, steps, evidence, candidates, suggested actions) for agents on a small context window.

Typed as a Literal so the client rejects a typo. As a bare str, view="slimm" silently returned the FULL bundle — defeating the only purpose of the parameter for exactly the caller who needed it.

ParametersJSON Schema

Name	Required	Description	Default
`view`	No		full
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral detail: the 'slim' view returns an action-relevant subset, and the Literal typing was introduced to prevent typos that previously caused silently returning the full bundle. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized at four sentences. The first sentence states the core purpose, the second explains the parameter options, and the following sentences justify the type design. Every sentence earns its place, and the content is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and clear annotations, the description covers the main decision a caller needs to make (full vs slim) and the semantic meaning of the view parameter. It does not enumerate the contents of a Context Bundle, but the sibling tools and output schema fill that gap. Adequate for tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It thoroughly explains the 'view' parameter, including the enum values, default, and the rationale for using a Literal type. The 'report_id' parameter is left implicit, but its meaning is obvious from the tool's name and context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a specific verb and resource: 'Return the Context Bundle for a report id.' This clearly distinguishes it from sibling tools like get_repro_steps or get_error_evidence, which retrieve narrower pieces of data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers clear guidance on choosing between view='full' and view='slim' based on context window size, but it does not explicitly state when to use get_report instead of sibling tools. Usage is implied by the tool's purpose rather than explicitly contrasted with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_repro_stepsA

Read-onlyIdempotent

Return the numbered reproduction steps for a report.

ParametersJSON Schema

Name	Required	Description	Default
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds little beyond the 'numbered' qualifier, and no behavioral details like auth requirements or rate limits are mentioned. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant information. Every word earns its place, and it is appropriately sized for a simple getter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the existing annotation and output schema cover return values and safety. The description is complete enough for basic invocation, though it lacks usage context which is already penalized under its own dimension.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only ties the parameter to 'a report', adding minimal meaning beyond the field name 'report_id'. No format, source, or constraints are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and clearly identifies the resource ('numbered reproduction steps for a report'). This distinguishes it from sibling tools like get_report or get_timeline, which target different aspects of a report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus siblings like get_report or get_error_evidence. The context is implied but not explicit, and there are no exclusions or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_suggested_actionsA

Read-onlyIdempotent

Return the machine-readable next-step menu for a report.

Each item is {action, label, rationale, ref} — present them to the user or auto-invoke the referenced resource/tool. Recomputed from the current bundle so it reflects the latest grounding/quality.

ParametersJSON Schema

Name	Required	Description	Default
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as read-only and idempotent. The description adds meaningful behavioral details: the result is 'recomputed from the current bundle' to reflect latest grounding/quality, and items can be presented or used for auto-invocation. This goes beyond the structured hints, though it doesn't cover error cases or edge effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two sentences, with the first sentence delivering the core purpose immediately. The second sentence adds necessary detail on item structure and recomputation without any fluff or redundancy. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter, an output schema, and read-only/idempotent annotations, this description covers the essential aspects: what it returns and the dynamic 'recomputed' behavior. The output schema handles return details, so the description need not elaborate further. It lacks error handling notes but is sufficient for a simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has only report_id with no description (0% schema coverage), so the description must compensate. It does add some context by saying 'for a report' and referencing the 'current bundle', implying report_id refers to a report within that bundle. However, it does not explain the ID format, provenance, or validation, which is a partial compensation only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Return' and clearly specifies the resource: 'the machine-readable next-step menu for a report'. It distinguishes itself from siblings like get_report by focusing on suggested actions, and even outlines the item structure ({action, label, rationale, ref}), leaving no ambiguity about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when a report's next-step menu is needed, to be presented or auto-invoked. It does not explicitly contrast with siblings like list_actions, but the purpose is evident. It lacks an explicit when-not-to-use or alternative comparison, preventing a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_timelineA

Read-onlyIdempotent

Return the merged event timeline for a report.

ParametersJSON Schema

Name	Required	Description	Default
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not contradict the annotations (readOnlyHint and idempotentHint are consistent with 'Return'). However, it adds no behavioral context beyond the annotation title 'Fused event timeline' — it merely paraphrases it. Since annotations already disclose the safe read-only nature, the lack of additional context is acceptable but provides no extra insight.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that gets straight to the point. Every word earns its place; there is no waste or redundancy. It perfectly balances brevity with clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one parameter and an existing output schema, the description is mostly complete. It defines the tool's core purpose and scope. However, it lacks a bit of context about what 'merged' means (e.g., merged from which sources) and does not provide any usage alternatives, but the simplicity of the tool and the presence of the output schema mitigate this gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter (report_id) with no description (0% coverage). The description says 'for a report,' which implicitly ties report_id to a report, but it does not explicitly explain the parameter's format or purpose beyond the name itself. This provides minimal compensation for the schema gap, but the parameter is self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Return the merged event timeline for a report.' It uses a specific verb ('Return') and a distinct resource ('merged event timeline') that differentiates it from sibling tools like get_repro_steps or get_error_evidence. The scope ('for a report') is explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when you need the merged event timeline for a report) but does not provide explicit exclusions or mention alternatives. No sibling tools are referenced, so the agent must infer usage from the purpose alone. This falls short of clear guidance but is not misleading.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_video_gifA

Idempotent

Render an animated GIF preview of the video for a report.

Useful for embedding a short looping preview in an issue, chat, or PR description. fps/width/start/end are optional and clamped to safe ranges; the GIF is cached on disk per parameter set.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No
`fps`	No
`start`	No
`width`	No
`report_id`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey idempotent and non-destructive. The description adds clamping behavior and on-disk caching per parameter set, which are not in annotations. It explains the caching side-effect but doesn't elaborate on potential output format or resource implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short paragraphs, front-loaded with the purpose, then a use case and parameter constraints. Every sentence adds value with no redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has five parameters and no output schema. The description covers purpose, use case, and parameter constraints, but lacks any mention of the return format (e.g., GIF URL, bytes) and does not clarify the meaning of report_id beyond the schema. Given the absence of an output schema, more detail on the return value would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions fps/width/start/end are optional and clamped, but does not explain what each parameter controls (e.g., units, meaning of start/end) or the clamp ranges. This is partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Render an animated GIF preview of the video for a report.' This is a specific verb+resource+output combination that distinguishes it from siblings like get_keyframe_image (static image) and render_html_video (HTML video).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a concrete use case: 'Useful for embedding a short looping preview in an issue, chat, or PR description.' This tells the agent when to use the tool, but it does not explicitly mention alternative tools or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_actionsA

Read-onlyIdempotent

List built-in action modes (names + descriptions) for analyze_video.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, and the description adds only that the modes are 'built-in' and include names and descriptions. This provides some context but no additional behavioral detail beyond what annotations and the description already imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that is perfectly sized and front-loaded. Every word contributes to understanding the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no parameters and an output schema (though not shown), and the description states exactly what is returned (names + descriptions). This is complete for a simple listing tool, and the connection to analyze_video provides the necessary context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the description has no parameter semantics to explain. The baseline for no params is 4, and the description adds no confusion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb (list) and resource (built-in action modes for analyze_video), and the phrase 'for analyze_video' distinguishes it from sibling tools like list_skills. It is immediately clear what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by specifying that it applies to analyze_video, implying use when needing to discover available action modes. However, it does not explicitly state when to use it over alternatives or mention any exclusions, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_reportsA

Read-onlyIdempotent

List all available report ids (from any analyzed video).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the description only needs to add context. It adds that the tool returns IDs only and that it aggregates across any analyzed video, which is useful behavioral nuance. It does not cover ordering or result size, but for a simple list operation with output schema, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence of eight words that is front-loaded with the action and resource. Every word adds value: 'all available' indicates completeness, 'report ids' specifies the return type, and 'from any analyzed video' defines the data source. No waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, an output schema (which explains return structure), and annotations covering safety, the description is complete. It provides the necessary context to understand the tool's purpose and scope without needing further elaboration.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, so the baseline is 4. The description correctly implies no inputs are needed, and the empty schema confirms this. There is no ambiguity or missing parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' with the resource 'report ids' and clarifies scope ('from any analyzed video'). It clearly distinguishes from siblings like get_report (which retrieves a specific report) and list_actions/list_skills (which list other entity types).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: you use this when you need the list of available report IDs. However, it does not explicitly state when not to use it or mention alternatives such as get_report for retrieving a specific report. The guidance is implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_skillsA

Read-onlyIdempotent

List built-in summary skills (names + descriptions) for analyze_video.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds that skills are built-in and specific to analyze_video, providing context about the tool's scope. No contradiction. It doesn't describe additional behavior beyond what annotations and output schema cover, but the added scope is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, action-first, no unnecessary words. Highly concise and easy to process.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only list tool with an output schema, the description sufficiently conveys purpose and scope. No missing information that would prevent correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters, so there is no parameter semantics to document. The description adds no parameter details, but none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'list' and identifies the resource as 'built-in summary skills' scoped to 'analyze_video'. This clearly distinguishes it from sibling list tools like list_actions and list_reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when the agent needs to discover available summary skills for analyze_video. The scope is clear, though no explicit exclusions or alternative tool names are given. This is sufficient given the tool's simple nature.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

locate_in_codeA

Read-onlyIdempotent

Return code candidates already grounded in the bundle, or re-ground now.

repo_root is REQUIRED when the bundle carries no candidates yet — it is never inferred from the working directory.

ParametersJSON Schema

Name	Required	Description	Default
`repo_root`	No
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint and idempotentHint, but the description adds a valuable behavioral constraint: repo_root is never inferred and is required when the bundle lacks candidates. This goes beyond the schema/annotations and alerts the agent to a potential failure mode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the main action, with no fluff. The information about repo_root is essential and placed prominently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with an output schema, the description covers the core behavior and the critical condition. It doesn't explain return structure, but the output schema handles that; some context around 'bundle' is still absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clearly explains the semantics and conditional requirement of repo_root, but leaves report_id and 'bundle' undefined, relying on contextual inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Return') and resource ('code candidates') with an explicit conditional ('or re-ground now'), clearly distinguishing this from sibling report/video/action tools. The title 'Locate suspect code' reinforces the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or alternative guidance is provided; however, the core statement implies the tool is for retrieving or creating code candidates. The repo_root conditional offers parameter-level guidance but not tool-selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

renderA

Read-onlyIdempotent

Render a report as a shareable artifact.

format is one of markdown, issue (GitHub issue text), or test-plan. Returns the rendered text.

ParametersJSON Schema

Name	Required	Description	Default
`format`	No		markdown
`report_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds valuable context by stating 'Returns the rendered text' and clarifying that 'issue' means GitHub issue text, which goes beyond what annotations offer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using two short paragraphs to convey the purpose, formats, and return type. Every sentence adds functional value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only tool with an output schema and good annotations, the description covers the core functionality and return type. The only notable gap is the lack of explicit guidance about when to prefer this over sibling tools, but the complexity is low enough that this is not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clearly explains the 'format' parameter with all allowed values and their meanings, while 'report_id' is naturally implied by the phrase 'Render a report', making the schema self-explanatory enough.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Immediately states 'Render a report as a shareable artifact' with a clear verb and resource. The format parameter is explained, and while it doesn't explicitly name sibling tools, the focus on reports vs. videos distinguishes it from render_html_video.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use guidance or alternatives are mentioned. It does not tell the agent when to use this tool versus get_report or render_html_video, nor does it provide any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

render_html_videoA

Idempotent

Render an HTML document (CSS / JS / canvas animation) to mp4/gif/webm.

Use this to export a self-contained animated HTML page (e.g. one you just designed) as a shareable clip. Captures the animation frame-by-frame (full color, no dropped frames, no quality loss) and encodes a color-correct H.264 MP4 / VP9 WebM / palette GIF — up to 4K, 5-60 fps. Returns the absolute path to the encoded file, written under the bundle directory. Requires the optional render extra (Playwright) + ffmpeg.

ParametersJSON Schema

Name	Required	Default
`fps`	No
`html`	Yes
`width`	No
`format`	No	mp4
`height`	No
`duration_s`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral detail beyond annotations: frame-by-frame capture with no dropped frames/quality loss, specific codecs and formats, resolution/fps ranges, output written to the bundle directory, and dependencies (Playwright + ffmpeg). It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two brief paragraphs, front-loaded with the core purpose. Every sentence adds value: purpose, use case, capture/encode behavior, output location, and dependency note. No waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values. It covers the main operational aspects: self-contained HTML input, output formats, quality, resolution/fps limits, file location, and runtime dependencies. This is sufficient for a tool of moderate complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning for format (mp4/gif/webm), fps range (5-60), resolution (up to 4K), and output path. It does not explicitly explain duration_s, but the parameter name and default make it reasonably clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Render an HTML document (CSS / JS / canvas animation) to mp4/gif/webm.' This clearly distinguishes it from sibling tools like analyze_video or get_video_gif, which focus on existing videos rather than generating new ones from HTML.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Use this to export a self-contained animated HTML page (e.g. one you just designed) as a shareable clip,' giving clear context. It does not explicitly list when not to use it or name alternatives, but the use case is precise enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

14 tool updatesv0.1.0Aug 6, 2026
- First observedanalyze_video
- First observedget_error_evidence
- First observedget_keyframe_image
- First observedget_report
- First observedget_repro_steps
- First observedget_suggested_actions
- First observedget_timeline
- First observedget_video_gif
- First observedlist_actions
- First observedlist_reports
- First observedlist_skills
- First observedlocate_in_code
- First observedrender
- First observedrender_html_video

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

Each tool targets a distinct resource or action: list_* for enumerating options, analyze_video for creation, get_* for specific report components, render for output formatting, and render_html_video for HTML-to-video conversion. Even the two visual retrieval tools (get_keyframe_image and get_video_gif) are clearly distinguished by static vs. animated output.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern (list_*, get_*, analyze_video, render_html_video). The main deviation is the bare verb 'render' which lacks an object, and 'locate_in_code' uses a prepositional structure, but overall the naming is predictable and readable.

Tool Count5/5

With 14 tools, the server is well-scoped for a video analysis platform. Each tool serves a distinct purpose in the workflow—analysis, report retrieval, configuration enumeration, and rendering—without unnecessary bloat or redundancy.

Completeness5/5

The tool surface covers the full lifecycle from video analysis (analyze_video) through report retrieval (get_report, get_repro_steps, get_error_evidence, etc.) to output generation (render, render_html_video). It also provides supporting tools like list_skills, list_actions, and list_reports to avoid dead ends. No critical gaps are apparent.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

clipkit A
dev.clipkit
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Multimedia Processing Image & Video Processing
15215
ContendeoOAuth
app.contendeo
Multimodal video analysis MCP — transcription, vision, and OCR for any video URL.
Multimedia Processing Image & Video Processing AI & Machine Learning
2
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2

Related MCP Servers

popcorn
Multimedia Processing Image & Video Processing Speech Processing
haithamelmengad
A
license
A
quality
D
maintenance
An MCP server that enables AI agents to analyze videos locally by extracting transcripts, detecting scene changes, and returning key frames.
Updated 7 months ago (2026-02-05 12:49 UTC)
5
6
MIT
Framesleuth
Image & Video Processing Testing & QA Tools
santoshshinde2012
A
license
A
quality
B
maintenance
Local bug-reproduction video analysis tool that processes bug recordings frame-by-frame, producing a structured Bug Context Bundle, and exposes this capability over MCP for use by coding agents like VS Code and Claude.
Updated 2 months ago (2026-07-11 16:41 UTC)
14
3
Apache 2.0
video-vision-mcp
Multimedia Processing Image & Video Processing
KitDevUA
A
license
A
quality
B
maintenance
An MCP server enabling Claude Code to analyze any video (local file, URL, or Jira ticket attachment) by extracting frame images and audio transcripts, or using Gemini for native video analysis.
Updated a month ago (2026-08-11 00:07 UTC)
4
MIT
watch-skill
Image & Video Processing Audio Processing
oxbshw
A
license
Not graded
quality
A
maintenance
MCP server that enables AI agents to watch and analyze videos from 1800+ sources, with persistent indexing, OCR, transcription, and a self-verification loop for debugging.
Updated 2 months ago (2026-07-05 19:18 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/thestackhub1/framesleuth-agent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server