Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@px4-flight-debugger why did my latest flight failsafe and land blind?"
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.
Is it my planner, or is it PX4? An MCP server for people writing offboard and
autonomy code against PX4 SITL: Claude (or any MCP client) reads the .ulg
and answers "why did that flight never reach its goal?", "how far off was the
estimate from the simulator's truth?" or "how late does PX4 follow my velocity
commands?" in one call instead of a hand-written pyulog script.
> log_summary 2026-10-20/16_21_32
log 2026-10-20/16_21_32.ulg started 2026-10-20 09:21:32 PDT, 50.9 s, 10.2 MB
PX4 v1.14.4 dev on PX4_SITL
armed: 12.6s (internal command) -> 49.9s (landing)
in the air 14.4-47.9s
[...]
modes: 0.0 AUTO_LOITER disarmed -> 12.6 OFFBOARD armed -> 17.6 ALTCTL FAILSAFE -> 49.9 OFFBOARD disarmed
failsafe: first at 17.6s
estimator while armed: horizontal position invalid 17.5-50.0s; dead reckoning 13.5-50.0s
warnings and errors (6 distinct):
13.8s WARNING [health_and_arming_checks] Preflight Fail: No valid data from Compass 0 (x3, last 22.6s)
17.5s WARNING [mc_pos_control] Failsafe: blind land (x15, last 46.1s)
[...]
17.6s WARNING Failsafe activated, triggering fallback to altitude control
[...]That flight came from an obstacle-avoidance batch in Gazebo where, in two runs out of sixteen, the planner never got to start navigating. The planner was fine: SITL lost its compass right after arming, the estimator lost its horizontal position four seconds later and PX4 failsafed into a blind landing.
Developing offboard planners against PX4 SITL, most of the "is it my code or
the simulator?" questions are answered by the flight log, but reading one
means a fresh script each time: find which .ulg belongs to the flight, decode
the mode numbers, line up messages, events and estimator flags. The tools here
are the questions that kept coming up, answered in plain text an assistant can
read and reason about.
Related MCP server: log-mcp
Tool | Answers |
| which logs exist; which one was running at 10:07 local time |
| what happened: version, arming and why, takeoff/landing, modes, failsafes, estimator trouble, distinct warnings |
| everything that changed, in order: modes, commands and acks, failsafe flags, takeoff, estimator validity, warnings |
| console messages and decoded events by level, text and time window |
| when position/velocity were invalid, dead reckoning, resets, which sources were fused when, faults, rejected measurements |
| SITL only: estimate against the simulator's ground truth, on the ground before liftoff and in the air |
| PX4's response to offboard velocity setpoints as a first-order lag plus dead time |
| parameter values by name or glob, and changes during the flight |
| any uORB topic: fields, rates, stats over a window, a downsampled table |
| one line per log for a whole day: which ones failsafed, which ones mention "compass" |
| a PNG of any fields against time, mode changes marked |
All read-only. A log is named by path, file name (16_21_32.ulg), date/name
(2026-10-20/16_21_32), latest or latest-N. Times are seconds since the
log started; the local wall-clock start is in every header. PX4 names log
folders and files in UTC, while day arguments and printed start times are
local.
Needs uv.
git clone https://github.com/blar-tw/px4-flight-debugger && cd px4-flight-debugger
uv syncRegister it with Claude Code (user scope, so every project sees it):
claude mcp add px4-flight-debugger --scope user -- uv --directory /path/to/px4-flight-debugger run px4-flight-debuggeror add it to an MCP client's config by hand:
{
"mcpServers": {
"px4-flight-debugger": {
"command": "uv",
"args": ["--directory", "/path/to/px4-flight-debugger", "run", "px4-flight-debugger"],
"env": {"PX4_ULOG_DIRS": "/home/you/PX4-Autopilot/build/px4_sitl_default/rootfs/log", "PYTHONPATH": ""}
}
}
}PX4_ULOG_DIRS lists where to look (separated by :), default
~/PX4-Autopilot/build/px4_sitl_default/rootfs/log. Empty PYTHONPATH keeps a
sourced ROS 2 environment from leaking its packages into the server.
pyulog parses the file; each tool asks only for the topics it needs, and a few parsed logs are kept in memory, keyed on the file's modification time.
Events are decoded with the definitions PX4 embeds in the log, falling back
to a local all_events.json from a PX4 build. Nothing is downloaded.
Mode, arming and command names are PX4 v1.14's. The arming reason names come
from commander's arm_disarm_reason_t, not the ARM_DISARM_REASON_*
constants in VehicleStatus.msg, which are out of date (6 is "landing", not
"safety button").
velocity_tracking only counts setpoints with position NaN and velocity set
while PX4 is in offboard, which is what it flies as a velocity command. A
position setpoint whose velocity fields were simply left at zero is not one;
counting those halved the fitted lag before this rule. It says so when the
fit does not look like a lagged velocity follower.
estimate_vs_truth takes the truth relative to where the drone spawned (the
simulator's world frame need not start at PX4's local origin) and reports
separately how far PX4 placed its local origin from the simulator's.
pyulog prints warnings on stdout, which is the protocol channel on stdio;
they are sent to stderr instead. An unreadable file is a tool error, and
scan_logs skips it with the reason.
SITL logs carry the ground truth. vehicle_local_position_groundtruth
and vehicle_attitude_groundtruth are logged next to the estimate, so
estimate-vs-truth needs no Gazebo bridge or extra recorder. Across 97 SITL
flights here, the height estimate had settled between 1.17 m below and 1.22 m
above the truth while the drone still sat on the ground (either sign, more
than 0.3 m in 60 of them), and the offset carried into the air. Horizontally,
most of the error is where PX4 put its local origin at the first GPS fix: in
17_06_45 the origin sits 0.35 m from the spawn point and the estimate is off
by 0.39 m.
PX4's own lag and the planner's. Over 87 flights with a clean fit, PX4 followed an offboard velocity setpoint like a first-order lag of 0.45 s (0.40-0.55) after 0.20 s of dead time. For 17_06_45 the log says 0.65 s in total, while the planner that sent the setpoints measured about 0.75 s from its own side: transport and scheduling add roughly 0.1 s, and the end-to-end figure is the one a planner should budget.
A message mismatch, visible as an arming reason. The planner arms through
a VehicleCommand with from_external set, yet the log says "internal
command". Its px4_msgs (main) has source_component as uint16 where
v1.14 has uint8, which shifts the fields after it.
Built and tested against PX4 v1.14 SITL logs. Other versions parse, but enum values they added show up as numbers.
estimate_vs_truth needs a SITL log; real flights have no truth topic. It
takes the first truth sample as the spawn point, so the drone should be at
rest when logging starts (PX4 starts logging at boot by default).
PX4's default logging profile thins trajectory_setpoint to about 5 Hz, so
the fitted dead time is only good to about 0.2 s.
uv run pytestThe tests run on two real SITL logs cut down with
tools/make_fixture.py (1.3 MB together): the compass failure above and a
clean offboard flight whose height estimate drifts. Each test is a question
that once needed its own script, plus an MCP round trip in-process and over a
real stdio subprocess.
MIT licensed.
SITL only: PX4's position/yaw estimate against the simulator's ground truth, on the ground before liftoff and in the air, plus sudden jumps. Shows offsets a planner flying on the estimate would carry.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the analysis phases (ground pre-liftoff, in-air, sudden jumps) and the interpretation (offsets a planner would carry), but says nothing about what happens for a non-SITL log, error behavior, or the read-only analysis nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the critical "SITL only" scope before describing what is compared. The closing clause about planner offsets adds interpretive value with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description adequately covers purpose, scope, and analysis dimensions. The remaining gap is failure behavior on real-flight logs, which is a minor omission for this analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single `log` parameter has 100% schema description coverage with accepted formats documented in the schema. The description adds no parameter guidance of its own, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific comparison (PX4 position/yaw estimate vs simulator ground truth) with phases and a jump-detection angle, so an agent can tell it apart from velocity_tracking or estimator_health. It doesn't explicitly name a sibling, but the resource and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"SITL only" is an explicit applicability constraint that tells the agent when this tool does and does not apply, which is stronger than generic context. It does not name an alternative for non-SITL logs, so it stops short of a full when/when-not/alternatives statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
EKF2 view: when local position/velocity were invalid, dead reckoning, resets, which sources were fused and when (GPS, mag, baro...), faults, and innovation test ratios that exceeded 1 (measurements rejected).
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose meaningful traits — it flags faults, resets, and innovation-test ratios above 1 (i.e., rejected measurements) — but says nothing about read-only semantics, log size/performance, or output shape. Adequate for a diagnostic read tool, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the tool's identity ('EKF2 view') and then efficiently lists the reported categories. No filler, though the trailing parenthetical is slightly cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required, and the description does cover the content categories an agent needs to know. However, there is no usage routing among the estimator-related siblings, leaving a gap for a tool in a dense family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the 'log' parameter exists and schema description coverage is 100%, so the schema already documents the accepted path/'latest' formats. The description adds no parameter information, making 3 the correct baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific domain (EKF2 estimator health) and enumerates the concrete content it surfaces: invalid local position/velocity, dead reckoning, resets, fused sources, faults, and rejected measurements. This is enough to distinguish it from siblings like estimate_vs_truth and velocity_tracking, though it never states an explicit verb such as 'report' or 'show'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to reach for this tool versus the closely related estimate_vs_truth or velocity_tracking siblings, and no prerequisites or exclusions are given. The agent must infer usage from the content list alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything that changed, in order: modes and arming, commands and their acks, failsafe flags set/cleared, takeoff/landing, estimator validity, warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the semantically rich output content (the event classes it aggregates), which is genuine behavioral value, but it says nothing about read-only nature, cost, ordering guarantees beyond 'in order', or whether events are truncated by the default limit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with no filler, and the high-value framing ('everything that changed, in order') is front-loaded before the category list. Dense but efficient; nothing needs pruning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not required, and the description adequately frames the content. However, for a diagnostic tool sitting among many overlapping log-analysis siblings, the absence of any usage routing or parameter context leaves the agent without enough to choose it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: the 'log' parameter is richly documented in the schema, but 'limit' has no description anywhere. The description never mentions either parameter, so it fails to compensate for the documented gap around 'limit' semantics (default 120) or the 'latest-N' log selector.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (flight-log events) and enumerates the exact content categories produced — modes/arming, commands and acks, failsafe flags, takeoff/landing, estimator validity, warnings — so an agent knows precisely what data it yields. It stops short of explicitly contrasting with siblings like log_messages or estimator_health, which overlap in subject matter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to reach for this tool versus log_messages, scan_logs, or estimator_health, and no prerequisites or exclusions. The boundary with overlapping siblings (a timeline of estimator validity vs the estimator_health tool) is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List flight logs newest first with their local start time, or find the one that covers a given wall-clock time.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | local time 'HH:MM[:SS]' (today) or 'YYYY-MM-DD HH:MM' to find the log running then | |
| day | No | only logs started on this local date, 'YYYY-MM-DD' | |
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It usefully discloses ordering (newest first) and that times are local/wall-clock, but says nothing about permissions, pagination, default limit behavior, or what happens when no log matches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the primary action and appended with the alternate mode. No filler, every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists so return values need not be explained, and the two modes are covered. However, for a tool with zero annotations, missing guidance on the undocumented 'limit'/pagination behavior and on distinguishing it from sibling log tools leaves notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (the limit parameter is undocumented). The description clarifies the 'at' parameter's semantics (finding the log running at a wall-clock time) beyond the schema, and implies ordering, but adds nothing for 'day' or 'limit'. Baseline is appropriate given the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List flight logs') plus the ordering ('newest first') and a secondary mode ('find the one that covers a given wall-clock time'). It is clear what the tool does, though it never references any of the many siblings (log_summary, scan_logs, log_messages) that could also surface logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The two implicit modes (list all vs. find the log covering a time) are implied by the sentence, but there is no explicit when-to-use rule, no when-not condition, and no routing to alternatives like scan_logs or log_messages. The agent can infer usage but not with confidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every logged uORB topic with sample count, rate and field count.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It implies a read-only enumeration by saying 'Every logged uORB topic,' but it does not explicitly disclose read-only status, error behavior, or log requirements. It does state the returned fields, which adds some useful output context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It communicates the resource and the key return contents immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully explained, and the only parameter is documented in the schema. The description is minimally adequate but omits usage context relative to siblings, leaving selection guidance incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single 'log' parameter is already fully documented in the schema. The description adds no parameter semantics beyond the schema, making the baseline of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('logged uORB topic') and the returned metrics ('sample count, rate and field count'), which is specific enough to distinguish it from list_logs and topic_data. However, it does not explicitly name an alternative or exclude sibling tools, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says what is returned but gives no explicit guidance on when to use list_topics versus siblings like list_logs, log_messages, or topic_data. There is no mention of prerequisites, appropriate workflows, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PX4 console messages and decoded events at or above a level, oldest first.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| t_to | No | end, s since log start | |
| limit | No | ||
| t_from | No | start, s since log start | |
| contains | No | case-insensitive text filter | |
| min_level | No | EMERGENCY ALERT CRITICAL ERROR WARNING NOTICE INFO DEBUG | WARNING |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It usefully adds that output is ordered oldest-first and that results are filtered to entries 'at or above a level', but it says nothing about pagination behavior for limit, truncation, or what skipped records look like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with the resource front-loaded and the two most important behavioral facts (level threshold, oldest-first ordering) appended. Nothing is padded and nothing needs reordering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-shape explanation is not required, and the description covers content type, filter direction, and ordering. The one real gap is the absence of any signal about limit/pagination semantics and how 'decoded events' differ from plain console messages.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents log, t_from, t_to, contains, and min_level (including its level vocabulary). The description reinforces the level-threshold semantics of min_level but adds no new syntax or format detail, making a baseline 3 correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource pair (PX4 console messages and decoded events) plus scope conditions (level threshold, chronological order), so an agent immediately knows what it returns. It stops short of differentiating itself from siblings like scan_logs or topic_data, so 5 is not warranted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not guidance and no mention of alternatives such as scan_logs or log_summary. The level filter and ordering are described, but nothing tells the agent under what circumstances this tool should be preferred over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parameter values as logged at boot, and any changed during the log.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| names | No | exact parameter names | |
| pattern | No | glob over names, e.g. 'EKF2_*' or '*_DLL_*' |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the data scope (boot values and changes) but says nothing about permissions, read/write nature, rate limits, pagination, or error behavior; it only minimally describes what is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no wasted words and front-loads the core data scope. It is efficient but grammatically fragmentary, which slightly weakens structure and clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and the input schema has full description coverage, so the description does not need to explain parameter formats or return values. Still, it omits usage guidance and sibling differentiation, leaving clear gaps for a tool that shares a crowded namespace.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents log, names, and pattern parameters in detail. The description adds no parameter-level meaning beyond the phrase 'Parameter values,' making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource and temporal scope: parameter values logged at boot plus values changed during the log. However, it lacks an explicit verb and does not distinguish this tool from siblings like list_logs, log_summary, or log_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It states what data is available but not the conditions or contexts that select this tool over the many sibling log-analysis tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What happened in one flight: PX4 version, arming and why, takeoff and landing, mode changes, failsafes, estimator trouble while armed, distinct warnings and errors (console and decoded events).
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does add real behavioral context by disclosing the scope of the report and noting that warnings/errors are drawn from both console and decoded events, but it never states that this is a read-only operation, nor does it hint at cost, log-size limits, or that a large log may be summarized coarsely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single tight sentence fragment with a good front-loaded headline ('What happened in one flight') followed by a dense but purposeful enumeration. No sentence is wasted, though the trailing parenthetical feels like a compressed afterthought.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained, and the description does convey the full content scope. What is missing for a tool in this crowded sibling set is routing guidance and any behavioral note about read-only safety or log-size handling, leaving the definition adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'log' parameter is fully documented there, including the accepted path forms and the 'latest'/'latest-N' defaults. The description adds nothing about parameter behavior or defaulting, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description makes clear this produces a high-level summary of a single flight log and enumerates the specific content domains covered (PX4 version, arming, takeoff/landing, mode changes, failsafes, estimator trouble, warnings/errors). However, it is phrased as a content listing rather than a verb+resource statement, and it never distinguishes itself from overlapping siblings like flight_timeline, estimator_health, or log_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no conditions, and no mention of any alternative. An agent must infer from the sibling names alone whether to call log_summary or flight_timeline first, which is exactly the decision guidance the description should supply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plot logged fields against time (mode changes dashed, failsafes red) and return the PNG.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| t_to | No | end, s since log start | |
| series | Yes | one subplot per entry; 'topic.field', or several joined with '+', e.g. 'vehicle_local_position.z+vehicle_local_position_groundtruth.z' | |
| t_from | No | start, s since log start |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the visual conventions (mode changes dashed, failsafes red) and that the return value is a PNG image, but it says nothing about permissions, cost, size limits, or error behavior for a tool whose output is a rendered image.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly written sentence with the action, resource, and return value front-loaded and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description states the output is a PNG and describes its visual encoding, and parameters are fully covered by the schema. The only meaningful gap is the missing guidance on when this tool should be chosen over its plotting-like siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema documents log path forms, t_from/t_to units, and the 'topic.field' with '+' joining syntax in detail. The description adds nothing beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Plot') plus resource ('logged fields against time') and an explicit output ('return the PNG'). It is clear what the tool does, but it does not distinguish itself from plotting-adjacent siblings such as flight_timeline, estimate_vs_truth, or velocity_tracking, which an agent could easily confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but gives no when-to-use guidance, prerequisites, or alternatives. With several sibling tools that plausibly produce plots or timelines, the absence of any routing hint ('use estimate_vs_truth for X, this for Y') leaves selection to inference at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One line per log: start time, duration, time armed, first failsafe, warning count and the first warning. For questions like 'which flights today lost the compass' or 'which ones failsafed'.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | local date 'YYYY-MM-DD'; empty = the latest `limit` logs | |
| limit | No | at most this many of the newest logs | |
| contains | No | only count warnings containing this text |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and it does disclose the return contents per log line. It never states that this is a non-mutating scan, nor mentions cost, limits, or how per-parameter filtering ('contains') interacts with the aggregated warning counts—meaningful gaps for a zero-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the output-shape statement is front-loaded ahead of the motivating examples. Slightly dense field listing, but every item named is a distinct output column rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description arguably needn't restate return fields, and schema coverage is complete for inputs. The remaining hole is relational: with ten siblings that also touch logs, the definition never places scan_logs relative to list_logs/log_summary/log_messages, leaving selection ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so 'day', 'limit', and 'contains' are already fully documented in the schema; that establishes a baseline of 3. The description adds nothing about parameter behavior—notably it is silent on the fact that all three parameters are optional and default to the newest logs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the resource (logs) and, unusually, the exact shape of each output line (start time, duration, time armed, first failsafe, warning count, first warning), which tells an agent precisely what scanning yields. It does not name or contrast any sibling (list_logs, log_summary, log_messages, flight_timeline), so the boundary with those tools must be inferred from the example questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Two concrete example questions ('which flights today lost the compass', 'which ones failsafed') imply the intended use case, which is genuinely helpful for routing. However, there is no explicit when-to-use/when-not guidance and no alternative tool is named, so the agent must guess whether log_summary or list_logs would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Min/mean/max/first/last of a topic's fields over a time window, optionally with a downsampled table.
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| t_to | No | end, s since log start | |
| topic | Yes | uORB topic, e.g. 'vehicle_local_position' or 'sensor_mag[1]' | |
| fields | No | fields to report; empty = all | |
| points | No | also return this many evenly spaced samples (0 = stats only) | |
| t_from | No | start, s since log start |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It is clearly a read/compute operation and it discloses the two output modes (stats vs. downsampled table), but it says nothing about whether log source selection or large windows affect cost, nor about any pagination or truncation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence, front-loaded with the computed outputs followed by the scope and optional mode. No filler, though 'optionally with a downsampled table' is slightly ambiguous about what 'table' means.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required, and the 100%-covered input schema documents all six parameters including the log source. The description is therefore adequate for the core call but leaves usage routing and cost/permission behavior unstated for a tool with several siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description maps roughly to t_from/t_to ('over a time window') and to the points parameter ('downsampled table'), adding marginal meaning beyond the schema but no syntax or format detail the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific computation (min/mean/max/first/last) applied to a specific resource (a topic's fields) over a defined scope (a time window), which is far more informative than a tautology. It doesn't explicitly differentiate itself from siblings like plot_series or list_topics, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance. An agent must infer that this tool is for statistics while plot_series is for visualization, and the 'optionally with a downsampled table' phrase hints at an alternative output mode without stating when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How PX4 followed offboard velocity setpoints: fits a first-order lag plus dead time from trajectory_setpoint to the measured velocity (the 'reaction time' an avoidance planner has to budget for).
| Name | Required | Description | Default |
|---|---|---|---|
| log | No | path, '16_21_32.ulg', '2026-10-20/16_21_32', 'latest' or 'latest-N' | latest |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the modeling behavior and the signal pair it operates on, which is genuinely useful context, but it says nothing about cost, read-only nature, or the shape of the result (the output schema exists, so return format is partly covered). Adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the core action and result. Every clause adds information, though the parenthetical explanation adds length without changing the call semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter analysis tool with a fully documented schema and an existing output schema, the description explains what the analysis produces and why it matters. The main omission is routing guidance relative to sibling analyses, which is a usage concern more than a completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter 'log' with 100% schema description coverage, and the description adds no semantics about it (accepted path/name forms, default behavior). Baseline 3 is appropriate when the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (fits) and a precise analytical result (first-order lag plus dead time from trajectory_setpoint to measured velocity), which clearly distinguishes it from diagnostic siblings like estimator_health or estimate_vs_truth. However, it never explicitly contrasts itself with those siblings, so the differentiation is inferable rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the phrase 'the reaction time an avoidance planner has to budget for' hints at the use case (planner tuning), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many analysis siblings. The agent must infer when this fits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0estimate_vs_truthestimator_healthflight_timelinelist_logslist_topicslog_messageslog_paramslog_summaryplot_seriesscan_logstopic_datavelocity_trackingScored across 12 tools
Most tools have clearly distinct scopes: discovery (list_logs, scan_logs), single-flight narrative (log_summary, flight_timeline, log_messages), estimator analysis (estimator_health, estimate_vs_truth), and data access (list_topics, topic_data, plot_series). The main friction is between log_summary, flight_timeline, and log_messages, which all describe 'what happened in a flight' from slightly different angles, and between list_logs and scan_logs, though the descriptions do differentiate them well enough.
All names are snake_case and readable, with no mixed casing conventions. However the pattern is not uniformly verb_noun: list_logs, scan_logs, plot_series use verbs while log_summary, flight_timeline, estimator_health, topic_data are noun phrases, creating a minor stylistic inconsistency.
12 tools is well within the ideal range and each one maps to a distinct analysis need (discovery, summarization, event ordering, EKF health, truth comparison, setpoint tracking, params, topics, plotting). No tool feels redundant or padded.
The surface covers discovery, per-flight narrative, estimator diagnostics, parameters, uORB topics, and plotting, which is strong lifecycle coverage for flight log debugging. Minor gaps remain, such as raw/full-resolution topic export (topic_data only gives stats plus an optional downsampled table) and no dedicated actuator/motor or battery analysis path, though plot_series partially compensates.
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Log and read REPS time logs, properties, and categories via MCP. Requires REPSLog Premium.
