esp-runtime-mcp

capture_log

Reads ESP-IDF device serial output, waits for ordered regex expectations, detects crashes, and decodes backtraces. Use it to verify boot or test logs and stop on panic or timeout.

Instructions

Read the device console until all expect patterns match, a crash is caught, or time runs out.

Crashes found in the log are parsed and symbolised automatically. Check passed: true only if every expect pattern matched and no crash was seen.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "capture_log"
  }
}

Input Schema

Name	Required	Description
`elf`	No
`baud`	No	Default $ESPBAUD or 115200
`port`	No	Serial port or URL (rfc2217://host:port). Default $ESPPORT
`reset`	No	Hard-reset via RTS/EN before capturing, to see boot
`expect`	No	Regexes that must appear IN ORDER; capture stops when all matched
`duration_s`	No	Maximum capture time
`tail_lines`	No
`project_dir`	No	ESP-IDF project for backtrace symbolisation
`stop_on_panic`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 29, 2026

TDQS

A3.5/5.0

Behavior3/5

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

With no annotations, the description does useful work: it discloses automatic crash parsing/symbolisation and defines the exact semantics of `passed` (all patterns matched AND no crash). However it omits important operational traits of a serial capture — that it blocks for up to duration_s (600s max), that the port is held exclusively, and that symbolisation depends on elf/project_dir being supplied.

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 short sentences, front-loaded with the termination conditions, then the implicit symbolisation behavior, then the result-checking hint. Nothing is padded and the `passed` guidance is immediately actionable.

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 9-parameter, no-annotation, no-output-schema tool, the description covers the core contract and one result field but not the shape of the rest of the response (log tail, crash report structure) nor the blocking/latency profile. It is enough to call correctly in the simple case, not enough to set expectations fully.

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 coverage is 67%, so the schema already explains port, baud, reset, expect, duration_s and project_dir; the description reinforces expect ordering and project_dir's role in symbolisation. The two undocumented parameters, tail_lines and stop_on_panic, get no explanation in either place, which is the main gap.

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?

States a specific verb and resource ('Read the device console') plus the three termination conditions (all expect patterns matched, crash caught, timeout), which makes the operation concrete. It does not differentiate from the sibling analyze_log, which an agent could plausibly confuse it with since both deal with logs.

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?

Usage is only implied: the mention of live expect matching and crash capture hints at 'capture a fresh run', while analyze_log presumably works on an existing log. There is no explicit when-to-use statement, no exclusions, and no mention of list_serial_ports as a prerequisite for finding a port.

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

Deploy Server