Bagel 让你能用自然语言询问关于机器人、无人机和物联网数据的问题。对消息数据的每一次计算都是 DuckDB SQL，而非模型猜测，并且 Bagel 会展示查询语句，方便你审计。
我的 IMU 传感器是否过热？
Bagel 还具备智能边缘数据缩减管道：描述一个事件，Bagel 就会在机器人上运行检测，保留相关窗口，丢弃其余数据。一个 MCP 服务器将所有功能交到你的 LLM 手中：Claude Code、Gemini、Cursor，或完全本地模型。
Bagel 是首个为机器人数据提供真实分析工具包的 MCP 服务器，它让 LLM 各司其职：站在日志前面，绝不进入机器人的控制回路。
自然语言提问：无需深厚的领域知识。
透明计算：确定性 SQL 查询，无黑箱 LLM 数学运算。
自然语言管道："保留每次急刹车前后 10 秒，丢弃其余数据"：一句话即可变成可审计的管道：在写入任何字节前预览，然后一次性运行、跨机群运行，或在边缘持续运行。
广泛的 LLM 支持：Claude Code、Gemini、Cursor、Codex 等。
Docker 化环境：无需本地依赖。
可扩展能力：Bagel 可以学习新技巧。
广泛格式覆盖：缺少你的数据格式？提交工单。
[!TIP] 已有 Claude Code？ 只需粘贴本仓库链接，告诉 Claude 你想要的环境：
为 ROS2 Kilted 设置 https://github.com/Extelligence-ai/bagel。
Claude 会克隆仓库、启动 Docker，并为你配置好 MCP 连接。
安装 Docker Desktop 和 Claude Code（或其他支持 MCP 的 LLM）。
git clone https://github.com/Extelligence-ai/bagel.git && cd bagel
docker compose run --service-ports ros2-kilted[!TIP] 端口 8000 已被占用？将
MCP_SERVER_PORT设置为其他值，例如MCP_SERVER_PORT=8100 docker compose run --service-ports ros2-kilted，并在步骤 2 中使用该端口。
选择与你环境匹配的服务：
服务 | 用途 |
| ROS2 Kilted（最新版） |
| ROS2 Jazzy |
| ROS2 Iron |
| ROS2 Humble |
| ROS1 Noetic |
| ROS1 Noetic + CV |
| PX4 飞行日志 |
| ArduPilot 飞行日志 |
| Betaflight 飞行日志 |
| IoT / MQTT（实时） |
[!TIP] 要让 Bagel 访问你的本地文件，请在启动 Docker 前编辑
compose.yaml：取消注释并更新所选服务下的volumes部分。
等待以下输出：
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)在新终端中：
claude mcp add --transport sse bagel http://localhost:8000/sse[!NOTE] 出于安全考虑，MCP 端点仅绑定到
localhost（不暴露给局域网）。若要与其他机器共享，请移除compose.yaml中的127.0.0.1前缀，并在前面放置经过身份验证的代理：参见 SECURITY.md。
claude总结 ROS2 bag 文件 "./data/sample/ros2/mcap" 的元数据。
就这样：你正在与你的数据对话。
将步骤 2 替换为本地模型：你的数据和 LLM 都保留在机器上：
brew install ollama && ollama serve & # or ollama.com
ollama pull qwen3:8b
uvx ollmcp --mcp-server-url http://localhost:8000/sse --model qwen3:8b模型选择、预期和故障排除：本地 LLM 指南。
Bagel 可与任何支持 MCP 的 LLM 配合使用。以下是经过测试的替代方案设置手册：
找不到你的 LLM？提交工单。
Related MCP server: Robotics MCP Server
Bagel 附带一个 Claude Code 插件：四项技能教会 Claude 何时以及如何驱动服务器（日志分类、管道编写、实时接收、可视化导出），外加自动配置的 MCP 连接。
/plugin marketplace add Extelligence-ai/bagel
/plugin install bagel@bagel然后为你的数据格式启动容器（参见快速开始）：插件默认连接到 http://localhost:8000/sse。任何其他 MCP 客户端都可以通过 list_agent_capabilities 工具在服务端发现相同的工作流。
机器人记录的数据量远超你能负担的传输成本。Bagel 将一个提问转化为检测器，在数据记录处运行，仅传输真实事件周围的窗口。
以下是一次对话中的实际效果：
上述会话：一段 20 分钟（1200 秒）的录音，提示为"保留每次减速度超过 −10 m/s² 前后 10 秒"。预览检测到 7 个事件，合并为 4 个窗口，保留了 1200 秒中的 92 秒（7.6%）；运行将 2.1 GB 的 bag 文件缩减至 161 MB。这些数字是演示输出，并非基准测试结果：比率是事件窗口时长除以总时长，完全取决于你的工作负载。
行业 | 格式 |
机器人 | ROS1、ROS2、MCAP（任何配置文件）、Copper（通过 MCAP 导出）、ROS 文本日志（ |
无人机 | PX4、ArduPilot、Betaflight |
汽车 | ASAM MDF4（ |
物联网 | MQTT（实时、Sparkplug B）、PostgreSQL / TimescaleDB、InfluxDB 3 |
硬件状态 | WaffleForm 快照（ |
你已经拥有 ros2 *、PlotJuggler 和 grep。Bagel 不会取代它们：它回答那些让你费劲的问题，然后将结果交给你：
你目前的做法 | 改用 Bagel 提问 |
用 | "总结这个 bag"：同一个提示适用于 PX4、ArduPilot、MCAP、MQTT、Postgres |
用 | "/imu 中 z 轴减速度峰值是多少？5 秒滑动平均？" · 底层是真实 SQL：峰值、滑动平均、百分位数、跨主题相关性 |
在 PlotJuggler 时间轴上滚动寻找事件 | "找出所有减速度低于 −10 m/s² 的事件，并截取 ±30 秒片段"：然后在 PlotJuggler 中打开结果，并附带预定义布局 |
使用 | "读取 ~/.ros/log 中的 ERROR 并告诉我出了什么问题"：包含回溯信息，无需 bag 文件 |
在两个终端中回显两个主题，在电子表格中关联 | "电流和电压之间的相关性是多少？"：主题位于同一个 SQL 关系中，因此连接和 |
用 | 一个持续运行的边缘管道：持续记录，仅保留事件窗口，丢弃其余数据 |
用 bash 循环处理 200 个 bag 文件 | "对文件夹中的每个 bag 运行此管道"：一个管道，整个机群，附带汇总报告 |
编写 | 将上传到 S3、GCS 或 Azure 作为管道步骤，通过校验和跳过已存在的文件 |
每种格式使用不同的查看器：PX4 用 FlightPlot、ArduPilot 用 MAVExplorer、Betaflight 用 Blackbox Explorer | 对所有格式使用相同的对话，包括 ROS、MCAP、MQTT、Postgres、InfluxDB |
为每个问题编写一次性的 pandas 脚本 | 直接提问；Bagel 编写并运行查询 |
一句自然语言，一个答案，取代一串命令和明天就会删除的脚本。
你几乎可以问 Bagel 任何问题。例如：
/spot/status/battery_states主题中电流和电压之间的相关性是多少？
我认为机器人撞到了坑。你能检查一下 z 轴是否有突然减速来确认吗？
每当无人机减速超过 -10 m/s² 时，保留前后各 10 秒的数据。丢弃其余所有数据。
自上周以来，这台机器人有什么变化吗？
是时候考验 Bagel 了：它能捕捉到正在做横滚动作的无人机吗？剧透：🎉 它完全能做到。
当你提出问题时，Bagel 会分析数据源的元数据和主题，从而构建高层理解。
根据你的提示，如果需要进一步检查，Bagel 会识别最相关的主题，并解读它们的含义和结构。然后，Bagel 将相关的主题消息写入一个 Apache Arrow 文件，并使用 DuckDB 生成并执行针对该文件的查询。
这个过程会根据需要重复进行，运行新的查询，直到 Bagel 找到你问题的最佳答案。
LLM 擅长语言但数学能力较弱。Bagel 通过生成确定性的 DuckDB SQL 查询来克服这一局限。这些查询会显示出来供你审计，并且你可以引导 Bagel 纠正任何错误。
Bagel 通过 POML 文件学习新能力：这是一组结构化的指令，描述一个“把戏”，例如计算延迟统计。
例如，让我们定义 ./src/agent/examples/woof.poml。
<poml>
<task>
Count the topics in the data source.
If the count is odd, say "woof", else say "meow".
</task>
<output-format>
Return the sound, the topic count, and a few cute emojis. Nothing else.
</output-format>
</poml>提示 Bagel：
在 ROS2 bag "./data/sample/ros2/mcap" 上运行 POML 能力 "./src/agent/examples/woof.poml"。
结果：
meow 🐱 4 topics 🐱💤🎯自然语言管道 · 模型：节奏、门控和任务；预览 → 运行 → 保存 → 批处理 → 站在边缘
事件驱动数据缩减 · 检测事件，保留事件周围的时间窗口（片段或单个缩减 bag），跨车队批处理，上传到云端
通过 rosbridge 连接实时 ROS2 机器人 · 逐步教程
ROS 文本日志 · 无需打开 bag 即可检查 ~/.ros/log 中的错误和警告
MQTT · 实时 IoT 主题、Sparkplug B、边缘录制
PostgreSQL / TimescaleDB · 每个表都是一个主题
InfluxDB 3 · 每个测量值都是一个主题
汽车 MDF4 和 CAN (测试版) · 通道组和 DBC 消息是主题；单位随之而来
本地 LLM · 使用 Ollama 完全离线：你的数据和模型永远不会离开机器
Rerun · “在 Rerun 中显示该事件”：任何时间窗口都可作为即开即用的录制文件
Lichtblick / Foxglove · 事件窗口作为 MCAP + 为任一查看器预定义的布局
PlotJuggler · 直接打开 Bagel 的 MCAP 输出；一句话预定义会话、扁平化 CSV/Parquet 导出
Cloudini · 解码 cloudini 压缩的点云，或将 bag 的 PointCloud2 主题压缩为 CompressedPointCloud2
Slack · 管道在触发时向你的运维频道发送消息：“🚨 {资产} 急刹车”
LeRobot (测试版) · 检测到的事件成为训练片段：LeRobotDataset v3.0
我们已知的粗糙边缘，以免你走弯路：
两种格式处于测试阶段。 汽车 MDF4/CAN 读取器已针对我们使用相同库（asammdf、python-can）生成的文件进行了验证；真实的 CANape/INCA/Vector 生成的捕获尚未经过我们的测试台。LeRobot 导出使用真实的 lerobot 包进行了干净的负载测试，但尚未有策略从 Bagel 导出训练过。
缩减比率取决于工作负载，且未经基准测试。 比率是事件窗口持续时间与总持续时间的比值：安静录制大幅缩减，事件密集的录制缩减较少。本 README 中的数字是演示输出，并非实测基准。
SSE 是文档化的传输方式。 可流式 HTTP 已连接（MCP_TRANSPORT=streamable-http），但 compose 未转发该设置，且尚无客户端手册涵盖它，因此 SSE 是当前支持的路径（#168）。
MCP 端点没有身份验证。 设计上它仅绑定到 localhost；将其视为数据库套接字，在共享到其他机器之前请参阅 SECURITY.md。
小型本地模型难以处理多步骤管道。 4-8B 模型可以处理工具选择和简单 SQL；事件窗口缩减和多主题连接需要更大的模型。请参阅本地 LLM 指南。
实时数据库端到端测试在 CI 之外运行。 InfluxDB 和 Postgres 套件的纯测试在 CI 中运行；它们的实时端到端用例仅在你指向的实例上执行。其他所有内容，包括 ROS bag 写入路径，都在 CI 中运行。
我们期待你的帮助！支持该项目最简单的方式是在 GitHub 上给它一个 ⭐。
其他贡献方式：
请求新功能
报告错误
改进文档
添加新能力
在贡献之前，请查看指南。
加入我们的 Discord 服务器 参与讨论。我们经常在那里。
Bagel 在 Apache License 2.0 下开源。
Summarize a data source without returning its messages. Includes: a brief summary, basic metadata (start time, message count, config parameters), and a list of available topics. Excludes: detailed topic definitions or actual messages.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds transparency by explicitly stating what is included (summary, metadata, topics) and excluded (messages, detailed definitions), which helps set expectations beyond the schema. It does not add unnecessary detail, and no contradictions with annotations exist.
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 exceptionally concise: two sentences, front-loaded with the core purpose, and then a clear list of inclusions and exclusions. Every sentence earns its place with no redundant or tangential 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?
Given the existence of an output schema and the moderate complexity (one required parameter, optional args), the description covers the key aspects: what it does, what it returns, and what it excludes. It could be slightly more complete by explaining the purpose of 'args' or providing an example, but it is sufficient to differentiate from siblings and understand basic usage.
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 input schema has 0% description coverage, and the tool description does not explain the meaning of the 'path' parameter or the optional 'args'. It only implies that 'path' identifies a data source, which is inferred from the tool name. The description fails to provide adequate semantics for parameters, leaving the agent to guess about path format or additional arguments.
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 clearly states the tool's function: 'Summarize a data source without returning its messages.' It specifies the resource (data source) and the action (summarize), and distinguishes it from sibling tools like query_messages and describe_topic by explicitly excluding messages and detailed topic definitions.
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 provides clear context about what the tool returns and excludes, implying when to use it (when you need a high-level summary rather than messages). However, it does not explicitly name alternative tools or provide explicit 'when not to use' guidance, so it stops 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.
Generate a structured summary of a topic without returning its messages. Includes: short summary, DuckDB schema, original IDL definition, and guidelines for SQL queries. Excludes: actual topic data.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| path | Yes | ||
| topic | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds useful behavior details: the output includes a short summary, DuckDB schema, IDL definition, and SQL guidelines, while excluding actual data. This enriches the agent's understanding without contradicting annotations.
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 two sentences, front-loaded with the action and immediately followed by a concise list of includes/excludes. Every word contributes value; no filler or redundancy.
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?
The tool is relatively simple (read-only metadata fetch) and the output schema exists. The description covers what the output contains (summary, schema, IDL, SQL guidelines) and what it excludes (actual data). The only gap is parameter semantics, but overall the description is complete enough for an agent to invoke correctly with reasonable assumptions.
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 0%, and the description does not explain any of the parameters (path, topic, args). The names are somewhat self-explanatory (path likely refers to data source path, topic to topic name), but the description provides no explicit guidance on their format, constraints, or relationships. The agent must rely solely on schema field names, which is insufficient for a 0% coverage situation.
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 clearly states 'Generate a structured summary of a topic' with a specific verb and resource, and explicitly lists inclusions and exclusions. It distinguishes from siblings like query_messages (which returns messages) and describe_data_source (which describes the entire source, not a topic).
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 clarifies it does not return messages, implying it's for metadata/schema when querying topics. However, it does not explicitly name alternative tools for when to use them or provide positive guidance on when to choose this tool over peers like describe_data_source or query_messages. The context is clear but lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export time windows as a LeRobotDataset v3.0 for robot-learning training: each window becomes an episode, resampled to a uniform fps, with the given signals composing feature vectors like observation.state and action. Use after preview_pipeline to turn detected events into a curated dataset. Beta: load-tests clean with the lerobot package; awaiting validation by real training runs.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | Yes | ||
| args | No | ||
| name | No | dataset | |
| path | Yes | ||
| task | Yes | ||
| topics | Yes | ||
| episodes | Yes | ||
| features | Yes | ||
| robot_type | No | unknown |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose idempotency and non-destructiveness; the description adds valuable context beyond that: data is resampled to uniform fps, windows become episodes, and feature vectors are composed. The beta caveat ('awaiting validation by real training runs') is honest about maturity. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences deliver purpose, mechanism, workflow, and beta status with no filler. The most important information is front-loaded in the first sentence.
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?
The description is strong on the high-level transformation and workflow, and an output schema exists, but the tool is complex with nine parameters and nested objects. Given 0% schema description coverage, the description does not fully compensate by explaining required argument semantics, so completeness is only adequate.
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 0%, yet the description does not compensate for the nine parameters. It mentions fps and signals/features at a high level, but does not explain required parameters like path, topics, episodes, features, task, or optional ones like args and robot_type. The agent would have to guess at the intended meanings and formats.
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 clearly states a specific verb and resource: 'Export time windows as a LeRobotDataset v3.0 for robot-learning training.' It further details the transformation semantics (each window becomes an episode, resampled to uniform fps, signals become feature vectors), which distinguishes it from sibling export tools like export_for_plotjuggler and export_for_rerun.
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 provides explicit workflow context: 'Use after preview_pipeline to turn detected events into a curated dataset.' This clearly indicates when the tool should be invoked. However, it does not mention when-not-to-use or name alternatives for different export formats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a time window of topic data as a Lichtblick session: an MCAP file with JSON-encoded channels plus a layout with the plot series and time/value ranges pre-set. Works in Lichtblick (open source) and Foxglove, which share the layout format. Use after preview_pipeline to hand an event to a human.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| name | No | event | |
| path | Yes | ||
| topics | Yes | ||
| signals | No | ||
| end_seconds | Yes | ||
| start_seconds | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint: true, readOnlyHint: false, destructiveHint: false, openWorldHint: false. The description adds that it exports to a file path, implying a creation action but not destructive. It mentions the resulting file is an MCAP with JSON-encoded channels, which is useful. However, it does not disclose potential size limits, permission requirements for writing to the path, or whether the layout is fully customizable beyond presets. With annotations covering safety aspects, the description adds moderate value, so a 3 is appropriate.
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 three sentences, each adding value. It front-loads the main purpose, then explains the output format and compatibility, and ends with a usage directive. No fluff or repetition.
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?
There is an output schema (not shown but indicated), so return values need not be described. The tool is moderately complex with 7 parameters, but the description covers the core workflow (preview_pipeline then export) and the output characteristics. It lacks some parameter details (units, signal vs topic), but given the output schema exists, the description is mostly complete for the agent to understand what the tool does and when to use it. A 4 is warranted.
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 0%, so the description must compensate. It mentions the output includes 'plot series and time/value ranges pre-set', which hints at the 'signals' parameter (selecting which signals to include) but does not clarify the difference between 'topics' and 'signals', nor the units of start_seconds/end_seconds. It also does not explain 'name', 'path', or 'args'. With 7 parameters and 0% coverage, the description only partially compensates, hence a 3.
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 clearly states the tool exports a time window of topic data as a Lichtblick session, producing an MCAP file with JSON-encoded channels and a layout with pre-set plot series and time/value ranges. It names the verb 'export', the resource 'time window of topic data', and the output format, distinguishing it from sibling export tools (export_for_plotjuggler, export_for_rerun, export_for_lerobot) by specifying Lichtblick/Foxglove.
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?
Explicitly says 'Use after preview_pipeline to hand an event to a human.' This provides clear when-to-use guidance, and the sibling list includes preview_pipeline, making the sequential relationship explicit. It also indicates the tool works in both Lichtblick and Foxglove, which are open-source and share the layout format, helping the agent choose this over other export targets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a time window of topic data as a PlotJuggler session: a flattened CSV (one scalar column per signal) plus a layout file with the curves pre-added and the window pre-framed. Opening the returned command shows the event already plotted and zoomed. Use after preview_pipeline to hand an event to a human for visual inspection.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| name | No | event | |
| path | Yes | ||
| topics | Yes | ||
| signals | No | ||
| end_seconds | Yes | ||
| start_seconds | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotency and non-destructiveness, and the description adds meaningful behavioral detail beyond them: the session is a flattened CSV with one scalar column per signal, the layout has curves pre-added, and opening the returned command shows the event pre-zoomed. No annotation contradiction is present.
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 tightly packed sentences front-load the core export behavior and then give workflow guidance. Every clause adds information, with no redundancy or filler.
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?
The description covers input window, output artifacts, return behavior, and intended human-review workflow, and an output schema exists for return values. The main gap is the meaning of path and name, but overall it is sufficient for choosing and invoking the tool in its primary context.
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?
With 0% schema description coverage, the description must compensate, but it only clarifies topics, time window, and signals. Critical required parameters like path are not explained, and optional args/name semantics are left entirely implicit. Partial compensation for 7 total parameters is insufficient.
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 action: 'Export a time window of topic data as a PlotJuggler session,' and gives concrete output details (flattened CSV, layout file). It clearly distinguishes this from sibling export tools by naming the PlotJuggler format and the pre-framed/zoomed behavior.
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?
It explicitly says 'Use after preview_pipeline to hand an event to a human for visual inspection,' which gives clear workflow context. It does not enumerate when to prefer this over sibling exporters, but the intended post-preview inspection use case is strong enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a time window of topic data as a Rerun recording (.rrd): every scalar signal becomes a Rerun time series, so rerun <file> opens the event in the Rerun viewer. Use after preview_pipeline to hand an event to a human for visual inspection. Needs the optional rerun-sdk dependency (uv sync --group viz).
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| name | No | event | |
| path | Yes | ||
| topics | Yes | ||
| signals | No | ||
| end_seconds | Yes | ||
| start_seconds | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the operation is non-destructive and idempotent. The description adds useful behavioral context: scalar signals become Rerun time series, the output is an .rrd file, and a specific dependency is required. However, it does not disclose output file naming/location, behavior with non-scalar topics, or possible size/scope limitations.
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 three focused sentences: it opens with the core purpose, then adds the recommended usage context, then notes the dependency. It is concise and front-loaded, though the title and first sentence repeat the same 'export event window' idea.
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?
Given the tool has seven parameters and zero schema descriptions, the description provides a decent high-level overview but is not complete enough for reliable parameter use. It covers purpose, use case, output format, and dependency, yet leaves parameter semantics and output specifics largely implicit. The presence of an output schema and good annotations helps, but the large parameter surface area still demands more detail.
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 zero schema-level parameter description coverage, so the description must compensate, but it does not explicitly describe any of the seven parameters. It only hints at time window and topic filtering via phrases like 'time window of topic data' and 'scalar signal,' leaving `path`, `topics`, `start_seconds`, `end_seconds`, `signals`, `name`, and `args` under-explained.
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 clearly states a specific action—exporting a time window of topic data as a Rerun recording (.rrd)—and differentiates the tool from sibling export tools by naming the Rerun viewer and the .rrd format. It also mentions the concrete outcome (`rerun <file>` opens the event).
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 explicitly says when to use the tool: 'Use after preview_pipeline to hand an event to a human for visual inspection.' It also notes a prerequisite (optional rerun-sdk dependency), which helps the agent plan setup. It does not explicitly contrast with sibling export formats, but the unique target format and viewer make the intended context fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the predefined POML capabilities shipped with Bagel: each entry has a name, a path to pass to run_poml_capability, and a one-line summary. Use this to discover available capabilities instead of guessing file paths.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. However, it adds behavioral context by explaining the tool's role in discovery ('instead of guessing file paths') and provides details about output structure, which complements the annotations. No contradictions found.
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 two sentences long, front-loaded with the core purpose, and every clause serves a purpose: it states the subject (predefined POML capabilities), the output fields, the connection to `run_poml_capability`, and the concrete use case. Zero waste.
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?
Given that the tool takes no parameters, has a rich output schema (implied), and has strong annotations, the description is complete. It covers discovery, output structure, and usage guidance, making it fully self-sufficient for an agent to know when and how to use it.
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 tool has no parameters, and the schema description coverage is 100% (trivially). The description adds value by stating that each entry contains `name`, `path`, and `summary`, which prepares the agent for the output without needing to inspect the output schema. This is more than a baseline, justifying a score above 3.
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 clearly states the tool lists predefined POML capabilities, with specific details about output fields (`name`, `path`, `summary`). It distinguishes itself from sibling `list_pipeline_capabilities` by explicitly focusing on POML capabilities and mentions `run_poml_capability` as a related tool, making its purpose unmistakable.
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 includes explicit guidance on when to use the tool: 'Use this to discover available capabilities instead of guessing file paths.' This tells the agent the intended use case, and the mention of `run_poml_capability` hints at a follow-up action, providing clear context for when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this tool to inspect a live data stream and list the topics that can be subscribed to. Helpful before starting a subscription.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| host | No | ||
| port | No | ||
| type_ | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the annotations (readOnly, idempotent) by using the term 'inspect,' but does not add any additional behavioral details beyond the annotations themselves. The annotations already cover the key transparency aspects.
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, focused sentence that conveys the essential purpose without any unnecessary words or details. It is well-structured and to the point.
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?
While the description indicates the general outcome (listing topics), it gives no information about the meaning of the input parameters or the expected output structure. This leaves significant gaps for a potential caller.
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 description provides no information about the four parameters (type_, args, host, port). Since the schema also lacks descriptions, the meaning of these parameters, especially the required type_, is entirely unclear.
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 clearly states the tool's function: inspecting a live data stream and listing available topics. It also distinguishes this from subscribing, which is helpful.
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 notes it is 'helpful before starting a subscription,' which gives a clear use case. However, it does not explicitly compare or contrast with alternative tools like describe_topic or query_messages, so it could be more prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tasks and gates available to compose a data pipeline, including each one's module path, kind (task or gate), constructor parameters, and a short summary. Use this before authoring a pipeline so the correct module and args are chosen instead of guessed.
| Name | Required | Description | Default |
|---|---|---|---|
| include_unavailable | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already cover read-only and idempotent behavior, the description does not clarify the impact of the include_unavailable parameter, which could lead to misinterpretation of what 'available' means. The description's phrasing might imply only available items are returned by default, which is not fully accurate given the parameter.
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 concise, consisting of two clear sentences with no redundant information. It efficiently conveys the tool's purpose and primary use case.
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?
The description provides enough context for the tool's primary function and when to use it, but it omits explanation of the parameter and does not mention any output structure or limits. This leaves some gaps for an agent trying to fully understand the tool's behavior.
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 parameter include_unavailable has no description in the schema, and the tool description does not explain its meaning or effect. Although the name is suggestive, the lack of any explanation leaves its semantics ambiguous, especially regarding the default behavior.
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 clearly states that the tool lists tasks and gates for composing a data pipeline, along with their module path, kind, constructor parameters, and summary. This is specific and distinguishes it from sibling tools like run_pipeline or describe_data_source.
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?
It explicitly says 'Use this before authoring a pipeline so the correct module and args are chosen instead of guessed,' giving a clear when-to-use directive. This is an explicit usage guideline that effectively replaces guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dry-run an event-windowed reduction WITHOUT writing any files. Detects the rising-edge events where a SQL predicate becomes true on a topic, builds pre/post windows around them, merges overlaps, and reports how much data would be kept. Use this to audit a reduce/snippet pipeline before running it.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| path | Yes | ||
| predicate | Yes | ||
| event_topic | Yes | ||
| pre_seconds | Yes | ||
| post_seconds | No | ||
| debounce_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description details the operational behavior: 'Detects the rising-edge events where a SQL predicate becomes true on a topic, builds pre/post windows around them, merges overlaps, and reports how much data would be kept.' This substantially enriches understanding of what the tool does during the dry-run.
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 three sentences, front-loaded with the most critical information ('Dry-run... WITHOUT writing any files'), and each sentence adds meaningful detail—purpose, mechanism, and usage. There is no redundancy or 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?
The description covers purpose, behavior, and usage, which is strong for a moderately complex tool with an output schema. However, the lack of explanation for `path` and `args` creates a small completeness gap, especially given the schema carries no descriptions.
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 description provides contextual meaning for key parameters: predicate ('SQL predicate'), event_topic ('on a topic'), pre_seconds/post_seconds ('pre/post windows'), and debounce_seconds ('merges overlaps'). However, it does not explain `path` (a required parameter) or `args` at all, and with 0% schema description coverage, this gap leaves the agent guessing about those parameters.
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 opens with a specific verb ('Dry-run') and resource ('event-windowed reduction'), and explicitly states the key scope: 'WITHOUT writing any files.' This distinguishes it from sibling tools like run_pipeline and run_pipeline_batch, which presumably execute rather than preview.
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 explicit when-to-use guidance: 'Use this to audit a reduce/snippet pipeline before running it.' This implies the alternative (running the pipeline) and the context (auditing to verify data reduction behavior) clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a DuckDB SQL query on messages from a single topic in a data source. Returns the query results as structured dictionaries. Use this tool to answer user questions about message data, including filtering, aggregation, and downsampling.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| path | Yes | ||
| topic | Yes | ||
| end_seconds | No | ||
| sql_statement | Yes | ||
| start_seconds | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context beyond safety. It adds the single-topic scope and the DuckDB engine, but does not discuss query limits, errors, or authorization; without the output schema, the 'structured dictionaries' line would be the only return-value insight.
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?
Three sentences with the action first, output second, and usage guidance third; no filler. It is appropriately scaled for a moderately complex tool, though it could add a brief parameter note without becoming verbose.
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?
The core behavior and primary use case are covered, and the output schema plus annotations handle return values and safety. Still, for a tool with six parameters and user-supplied SQL, the description omits time-range semantics, args, and any boundary conditions such as cross-topic queries being unsupported.
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?
With schema description coverage at 0%, the description carries the parameter-explanation burden. It clarifies path (data source), topic (single topic), and sql_statement (DuckDB SQL capable of filtering/aggregation/downsampling), but leaves args, start_seconds, and end_seconds entirely unexplained.
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 opens with a specific action ('Run a DuckDB SQL query') and a bounded resource ('messages from a single topic in a data source'), clearly distinguishing it from sibling describe/run/export tools. It also states the intended result ('structured dictionaries').
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?
It explicitly says to use this tool for answering questions about message data with filtering, aggregation, and downsampling, which gives clear application context. It does not, however, name alternatives or exclusion cases, such as when to use export_for_plotjuggler or run_pipeline instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract INFO, WARN, and ERROR messages from a data source. Supports optional time filtering. Use for debugging or diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| path | Yes | ||
| end_seconds | No | ||
| start_seconds | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, and non-destructive behavior, which the description reinforces with 'Extract' but does not add new behavioral details. The description also mentions time filtering but does not clarify edge cases or side effects, so transparency relies mostly on annotations.
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 two concise sentences with no redundancy or irrelevant details. It directly states the action, the scope (INFO/WARN/ERROR), and the optional filtering, which is efficient and well-structured.
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?
The description provides the core purpose and usage but omits details about the return format or what happens when no time filter is applied. Since there is no output schema, it should clarify what the tool returns (e.g., a list of messages), but it only implies messages. This leaves some ambiguity for agents.
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 0%, so the description must compensate for parameter explanations. It only hints at 'optional time filtering' related to start_seconds and end_seconds, but leaves 'path' and 'args' completely undefined. This is insufficient for an agent to correctly construct the call without additional context.
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 clearly states the tool extracts INFO, WARN, and ERROR messages from a data source, which is specific and distinct from sibling tools that focus on pipelines or queries. It directly names the verb 'Extract' and the resource 'data source', making the purpose 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?
The description explicitly says 'Use for debugging or diagnostics', providing a clear context for when to employ this tool. It also mentions optional time filtering, which further guides usage, but it does not compare against alternatives or state when not to use it, so it is not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build and run a pipeline from a configuration and return the artifact paths it produced. Prefer running preview_pipeline first for event-driven reductions so the effect is audited before anything is written.
| Name | Required | Description | Default |
|---|---|---|---|
| config | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds that it produces artifact paths, implying write operations, which is useful beyond annotations. However, it doesn't disclose other side effects, rate limits, or error behaviors, so it's not exhaustive but adds some value.
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 two sentences, front-loaded with the core purpose, and the second sentence provides concise actionable guidance. Every word contributes without fluff.
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?
There is an output schema (not shown) and a single config param, but the description doesn't explain what constitutes a valid config, prerequisites, or error handling. It mentions artifact paths but not other return details (covered by output schema). For a complex pipeline execution tool, the description leaves ambiguity around configuration structure and side effects.
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 only parameter 'config' is an untyped object with additionalProperties true and zero description in the schema (0% coverage). The description merely says 'from a configuration' without detailing required fields, structure, or examples, failing to compensate for the lack of schema documentation.
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 clearly states the tool builds and runs a pipeline from a configuration and returns produced artifact paths. This is a specific verb+resource+outcome, and it distinguishes itself from preview_pipeline by explicitly advising to use preview first.
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 explicit guidance: prefer preview_pipeline first for event-driven reductions to audit effects before writes. This clearly situates run_pipeline as the execution step after preview, providing direct usage direction and an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one pipeline configuration against many data sources -- explicit paths or glob patterns like 'logs/*'. Each source is processed independently; a failure on one source is reported but does not stop the batch. Returns per-source results and a summary. For an event reduction, preview a representative source first.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | ||
| config | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior beyond annotations: sources are processed independently, a failure on one source is reported but does not stop the batch, and results include per-source output plus a summary. It does not detail side effects, but annotations already provide the main read/write/destructive hints and the output schema is present.
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?
Four short, purposeful sentences cover the main action, input style, failure behavior, and preview guidance. There is no filler or redundant repetition of schema/annotations, and important details are front-loaded.
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?
Given the output schema and annotations already cover return shape and safety hints, the description covers the essential usage context: one config, many paths, isolation of failures, batch summary, and a preview example. The main gap is that the config parameter remains opaque, but this is a single toolbox-dependent object rather than a fully documented structure.
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 description adds real meaning to 'paths' via explicit paths or glob patterns like 'logs/*', which the schema does not provide. However, the 'config' parameter is only described as 'one pipeline configuration' with no indication of its fields, expected structure, or constraints, and the schema has 0% description coverage.
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 opens with a specific action: 'Run one pipeline configuration against many data sources.' It further clarifies scope with 'explicit paths or glob patterns like logs/*', which distinguishes it from the sibling single-source tool run_pipeline.
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 clearly implies batch usage over many data sources and that sources are independent. It also gives a practical alternative/precondition: 'For an event reduction, preview a representative source first,' suggesting preview_pipeline. It does not explicitly say when to choose run_pipeline over run_pipeline_batch for a single source, but the distinction is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this tool to run a predefined capability described in a .poml file. Discover available capabilities and their paths with list_agent_capabilities. The file specifies task instructions and output formats. Optional context values can be injected to customize its behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| poml_path | Yes | ||
| poml_context | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not restate those. The description adds that the file specifies instructions and output formats, which is useful context. However, it does not disclose potential side effects like logging or resource usage, but the annotations cover the safety profile adequately.
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 three sentences, all earning their place: purpose, discovery path, and context customization. No fluff, properly front-loaded with the key action.
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?
Given the tool is high-level with an output schema and clear annotations, the description covers the essential aspects: what it does, how to find capabilities, and the optional context. It lacks details on error handling or output specifics, but the output schema likely provides that, making it complete enough.
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 0%, so the description must compensate. It mentions 'Optional context values can be injected to customize its behavior,' which aligns with `poml_context`, and implies `poml_path` is the location. This is a minimal addition and does not clarify the structure of `poml_context` or expected file paths.
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 clearly states the tool runs a predefined capability from a `.poml` file, distinguishing it from other tools like `list_agent_capabilities` and `run_pipeline`. It explains the file's role and the optional context injection, making the purpose specific and actionable.
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?
It explicitly instructs to discover capabilities with `list_agent_capabilities`, which provides clear when-to-use guidance. However, it does not specify when not to use this tool or mention alternatives like `run_pipeline`, leaving some room for ambiguity in choice of tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a pipeline configuration to a YAML file so it can be reused, edited, or run later with run.py. Returns the path to the written file.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| config | Yes | ||
| directory | No | pipelines |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring idempotentHint=true and destructiveHint=false, the description adds value by specifying the output (YAML file) and that it returns the file path. It does not contradict annotations and provides useful detail about the side effect of writing a file.
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 concise sentences with no redundancy. The first sentence immediately states the core action and purpose, and the second adds the return value. All words are necessary.
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?
Given the simple nature of a save operation with an output schema already present, the description adequately covers the main aspects. It mentions the return path, which is the key output. The directory parameter is left to schema defaults, and the config object is self-explanatory as a pipeline configuration. No critical information is missing.
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 0%, so the description must compensate by explaining parameters. It only mentions 'pipeline configuration' and implicitly 'name' and 'directory' through the tool name, but provides no clarification of the config object structure, name requirements, or directory default behavior. The description adds minimal meaning beyond what the schema alone shows.
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 clearly states the tool's function: 'Persist a pipeline configuration to a YAML file'. It is specific (action: persist, resource: pipeline configuration, format: YAML) and distinguishes itself from sibling tools like export_for_plotjuggler or run_pipeline by focusing on saving the config for later reuse.
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 provides context on when to use it: 'so it can be reused, edited, or run later with `run.py`'. This clarifies the intended workflow but does not explicitly mention alternatives or when not to use the tool. The contrast with run_pipeline (immediate execution) is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-detect the robot's current hardware, firmware, and software using waffle-iron and return the resulting hardware state. Requires the waffle CLI on PATH (cargo install waffle-iron). The WaffleForm it writes is immediately queryable as a data source.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | . |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
All annotations are false, so the description carries the full burden, and it performs well: it discloses auto-detection behavior, the side-effect of writing a WaffleForm, the dependency footprint, and the post-condition of data-source queryability. Could be stronger with failure modes (e.g., what happens if no robot is available, whether the directory is created). Not a contradiction, just an opportunity for more.
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?
Three tightly-scoped sentences: purpose, prerequisite/installation context, and side-effect/composition note. There is zero filler, and the most important information (what it does) is front-loaded. Every sentence adds distinct value.
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 the tool's complexity (1 optional param, no nested objects, output schema present), the description covers the essentials: core behavior, setup prerequisite, and downstream consumption model. Gaps include the role of the `directory` parameter and what happens on failure, but for a tool of this size these are minor. The description respects the line of what structured fields already convey and adds meaningful orchestration context.
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?
With 0% schema description coverage, the burden falls on the description to explain the `directory` parameter, but it's never mentioned. The schema itself only gives a name and default ('.'), so an agent must guess whether it's the output destination, the robot's config directory, or a scan root. Given the description does zero compensation for its single parameter, a 2 is appropriate here.
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 uses a specific verb-resource pair ('Auto-detect the robot's current hardware, firmware, and software') and clearly states the output ('return the resulting hardware state' and 'writes a WaffleForm'). It clearly distinguishes this from siblings like run_pipeline or query_messages by establishing a unique outcome (queryable data source) and the experimental beta caveat in the title adds useful maturity context.
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?
Discloses a hard prerequisite ('Requires the waffle CLI on PATH (cargo install waffle-iron)') and implies when it's useful by noting the output is 'immediately queryable as a data source.' It stops short of explicitly naming alternatives or excluding contexts (e.g., 'don't use for X, use save_pipeline instead'), so it loses a point here, but the practical when-to-use context is well covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this tool to connect to a live data stream and subscribe to one or more topics. Messages are written to a local sink directory, which can be used later as input for other tools (via the path argument in SourceFactory). Optionally attach a pipeline config to create a STANDING pipeline that runs on incoming messages -- e.g. an on_event cadence that captures and uploads a window around every anomaly.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| host | No | ||
| port | No | ||
| type_ | Yes | ||
| topics | No | ||
| pipeline | No | ||
| overwrite | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate those. It adds useful behavioral context: messages are written to a local sink directory, usable later via `path` in SourceFactory, and optionally creates a standing pipeline. This goes beyond the annotations without contradicting them.
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, well-structured sentence that front-loads the core purpose ('use this tool to connect to a live data stream and subscribe to one or more topics'), then adds concise details on the sink and optional pipeline. 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?
Given the tool's complexity (7 params, no enums) and the presence of an output schema, the description covers the essential aspects: purpose, side effects, and optional configuration. It omits details on some parameters (host, port, type_, etc.) which the schema alone doesn't explain, but these are likely less central. The description is reasonably complete for an agent to know when and how to use it.
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 schema description coverage is 0%, so the description carries the full burden. It mentions 'one or more topics' (topics parameter) and 'pipeline config' (pipeline parameter), but does not explain host, port, type_, args, or overwrite. With 7 parameters and only 2 partially described, the description insufficiently compensates for the total lack of schema descriptions.
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 clearly states the tool's purpose: 'connect to a live data stream and subscribe to one or more topics.' It specifies the verb (connect/subscribe) and the resource (live data stream topics), and differentiates from siblings like 'run_pipeline_batch' and 'query_messages' by focusing on live streaming and subscription.
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 opens with 'Use this tool to connect to a live data stream,' providing clear context for when to use it. It also explains that the sink directory can serve as input for other tools via SourceFactory, and mentions the optional pipeline for standing pipelines. However, it does not explicitly state when not to use it or name alternatives, though the context strongly implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools are distinct, but there are several near-overlaps: `run_pipeline` vs `run_pipeline_batch`, `read_loggings` vs `query_messages`, and the four `export_for_*` tools all serve the same broad goal. The descriptions are thorough enough to prevent complete confusion, but an agent will need to read carefully to pick the right one.
The set is mostly consistent snake_case with clear verb_noun prefixes like `list_*`, `describe_*`, `run_*`, and `export_*`. Minor inconsistencies exist: `read_loggings` is awkward, `run_poml_capability` doesn't align with `list_agent_capabilities`, and the `export_for_*` suffix pattern is less uniform.
18 tools falls in the heavier 16-25 range and feels slightly inflated by four nearly identical export tools plus several pipeline run/save/preview variants. The scope is broad enough that the count isn't absurd, but it could be tightened without losing capability.
The core data inspection, pipeline running, and export workflows are well covered. However, there are noticeable lifecycle gaps: no way to list or delete saved pipelines, no stop/unsubscribe for live subscriptions, and no editing/removal operations for capabilities or topics creates minor dead ends.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
GibsonAI MCP server: manage your databases with natural language
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Extelligence-ai/bagel'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
