Bagel te permite hacer preguntas sobre datos de robótica, drones e IoT en lenguaje natural. Cada cálculo sobre los datos de tus mensajes es SQL de DuckDB, no una conjetura del modelo, y Bagel te muestra la consulta para que puedas auditarla.
¿Se está sobrecalentando mi sensor IMU?
Bagel también incluye un pipeline inteligente de reducción de datos en el edge: describe un evento y Bagel ejecuta la detección en el robot, conservando las ventanas que importan y descartando el resto. Un servidor MCP pone todo esto en manos de tu LLM: Claude Code, Gemini, Cursor o un modelo completamente local.
Bagel fue el primer servidor MCP en incluir un kit de análisis real para datos de robótica, y mantiene al LLM donde corresponde: frente a tus registros, nunca en el bucle de control de tu robot.
Pregunta en lenguaje natural: No se necesitan conocimientos profundos del dominio.
Cálculos transparentes: Consultas SQL deterministas. Nada de matemáticas de LLM en caja negra.
Pipelines en lenguaje natural: «Conserva 10 s alrededor de cada frenada brusca, descarta el resto»: una frase se convierte en un pipeline auditable: se previsualiza antes de escribir un byte y luego se ejecuta una vez, en una flota o de forma permanente en el edge.
Amplio soporte de LLM: Claude Code, Gemini, Cursor, Codex y más.
Entornos dockerizados: No se requieren dependencias locales.
Capacidades extensibles: Bagel puede aprender nuevos trucos.
Amplia cobertura de formatos: ¿Te falta tu formato de datos? Abre un ticket.
[!TIP] ¿Ya tienes Claude Code? Solo pega el enlace de este repositorio y dile a Claude qué entorno quieres:
Configura https://github.com/Extelligence-ai/bagel para ROS2 Kilted.
Claude clonará el repositorio, iniciará Docker y configurará la conexión MCP por ti.
Instala Docker Desktop y Claude Code (u otro LLM compatible con MCP).
git clone https://github.com/Extelligence-ai/bagel.git && cd bagel
docker compose run --service-ports ros2-kilted[!TIP] ¿El puerto 8000 ya está en uso? Define
MCP_SERVER_PORTcon otro valor, por ejemploMCP_SERVER_PORT=8100 docker compose run --service-ports ros2-kilted, y usa ese puerto en el paso 2.
Elige el servicio que coincida con tu entorno:
Servicio | Caso de uso |
| ROS2 Kilted (última versión) |
| ROS2 Jazzy |
| ROS2 Iron |
| ROS2 Humble |
| ROS1 Noetic |
| ROS1 Noetic + CV |
| Registros de vuelo de PX4 |
| Registros de vuelo de ArduPilot |
| Registros de vuelo de Betaflight |
| IoT / MQTT (en vivo) |
[!TIP] Para dar acceso a Bagel a tus archivos locales, edita
compose.yamlantes de iniciar Docker: descomenta y actualiza la secciónvolumesen el servicio que hayas elegido.
Espera esta salida:
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)En una terminal nueva:
claude mcp add --transport sse bagel http://localhost:8000/sse[!NOTE] El endpoint MCP está vinculado solo a
localhost(no expuesto a la LAN) por seguridad. Para compartirlo con otras máquinas, elimina el prefijo127.0.0.1encompose.yamly coloca un proxy autenticado delante: consulta SECURITY.md.
claudeResume los metadatos del bag ROS2 "./data/sample/ros2/mcap".
Eso es todo: ya estás hablando con tus datos.
Sustituye el paso 2 por un modelo local: tus datos y tu LLM permanecen en la máquina:
brew install ollama && ollama serve & # or ollama.com
ollama pull qwen3:8b
uvx ollmcp --mcp-server-url http://localhost:8000/sse --model qwen3:8bElección de modelos, expectativas y solución de problemas: Guía de LLMs locales.
Bagel funciona con cualquier LLM compatible con MCP. Guías de configuración para alternativas probadas:
Claude Code (guía detallada)
¿No encuentras tu LLM? Abre un ticket.
Related MCP server: Robotics MCP Server
Bagel incluye un plugin de Claude Code: cuatro habilidades que enseñan a Claude cuándo y cómo manejar el servidor (triage de registros, creación de pipelines, sinks en vivo, exportación de visualizaciones) además de la conexión MCP, configurada automáticamente.
/plugin marketplace add Extelligence-ai/bagel
/plugin install bagel@bagelA continuación, inicia el contenedor para tu formato de datos (consulta Inicio rápido): el plugin
se conecta a http://localhost:8000/sse por defecto. Cualquier otro cliente MCP puede
descubrir los mismos flujos de trabajo en el lado del servidor mediante la herramienta list_agent_capabilities.
Un robot graba más datos de los que puedes permitirte mover. Bagel convierte una pregunta en un detector, lo ejecuta donde se graban los datos y envía solo las ventanas alrededor de los eventos reales.
Aquí lo tienes en una conversación:
La sesión anterior: una grabación de 20 minutos (1200 s) y la indicación «conserva 10 segundos antes y después de cada deceleración más fuerte que −10 m/s²». La vista previa detecta 7 eventos, los fusiona en 4 ventanas y conserva 92 s de los 1200 (7,6 %); la ejecución reduce un bag de 2,1 GB a 161 MB. Estas cifras son resultados de demostración ilustrativos, no un benchmark medido: la proporción es la duración de las ventanas de eventos dividida entre la duración total, por lo que depende por completo de tu carga de trabajo.
Industria | Formatos |
Robótica | ROS1, ROS2, MCAP (cualquier perfil), Copper (mediante exportación MCAP), registros de texto ROS ( |
Drones | PX4, ArduPilot, Betaflight |
Automoción | ASAM MDF4 ( |
IoT | MQTT (en vivo, Sparkplug B), PostgreSQL / TimescaleDB, InfluxDB 3 |
Estado del hardware | WaffleForm instantáneas ( |
Ya tienes ros2 *, PlotJuggler y grep. Bagel no los reemplaza: responde a las preguntas
para las que te hacen trabajar, y luego te deriva a ellos:
Lo que haces hoy | Pregúntale a Bagel en su lugar |
| «Resume este bag»: la misma indicación funciona en PX4, ArduPilot, MCAP, MQTT, Postgres |
| «¿Cuál es el pico de desaceleración en z en /imu? ¿Media móvil en 5 s?» · SQL real por debajo: picos, medias móviles, percentiles, correlaciones entre topics |
Recorrer las líneas temporales de PlotJuggler buscando el evento | «Encuentra toda desaceleración inferior a −10 m/s² y corta fragmentos de ±30 s»: luego abre el resultado en PlotJuggler con una disposición predefinida |
| «Lee los ERROR de ~/.ros/log y dime qué falló»: incluye tracebacks, no se necesita bag |
Hacer eco de dos topics en dos terminales, correlacionar en una hoja de cálculo | «¿Cuál es la correlación entre corriente y voltaje?»: los topics viven en una sola relación SQL, así que los joins y |
| Un pipeline de edge permanente: graba continuamente, conserva solo las ventanas de eventos, descarta el resto |
Un bucle bash sobre 200 bags | «Ejecuta este pipeline en todos los bags de la carpeta»: un solo pipeline, toda la flota, con un informe combinado |
Scripts de | Subir a S3, GCS o Azure como paso del pipeline, omitiendo por checksum los archivos que ya están allí |
Un visor distinto para cada formato: FlightPlot para PX4, MAVExplorer para ArduPilot, Blackbox Explorer para Betaflight | La misma conversación para todos ellos, y también ROS, MCAP, MQTT, Postgres, InfluxDB |
Escribir un script pandas desechable para cada pregunta | Pide la pregunta; Bagel escribe y ejecuta la consulta |
Una frase en lenguaje natural, una respuesta, en lugar de un pipeline de comandos y un script que borrarás mañana.
Puedes preguntarle a Bagel casi cualquier cosa. Por ejemplo:
¿Cuál es la correlación entre corriente y voltaje en el topic
/spot/status/battery_states?
Creo que el robot golpeó un bache. ¿Puedes comprobar si hubo una desaceleración repentina en el eje z para confirmarlo?
Cada vez que el dron desacelere más fuerte que -10 m/s², mantén 10 segundos antes y después. Descarta todo lo demás.
¿Cambió algo en este robot desde la semana pasada?
Es hora de poner a prueba a Bagel: ¿puede atrapar un dron haciendo toneles? Spoiler: 🎉 ¡Sí puede!
Cuando haces una pregunta, Bagel analiza los metadatos y temas de tu fuente de datos para construir una comprensión de alto nivel.
Según tu indicación, si se necesita una inspección adicional, Bagel identifica los temas más relevantes e interpreta su significado y estructura. Luego, Bagel escribe los mensajes de los temas relevantes en un archivo Apache Arrow y utiliza DuckDB para generar y ejecutar consultas contra él.
Este proceso se repite según sea necesario, ejecutando nuevas consultas hasta que Bagel encuentra la mejor respuesta a tu pregunta.
Los LLM sobresalen en lenguaje pero tienen dificultades con las matemáticas. Bagel supera esto generando consultas SQL deterministas de DuckDB. Estas consultas se muestran para que puedas auditarlas y puedes guiar a Bagel para corregir cualquier error.
Bagel aprende nuevas capacidades a través de archivos POML: un conjunto estructurado de instrucciones que describen un "truco", como calcular estadísticas de latencia.
Por ejemplo, definamos ./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>Indícale a Bagel:
Ejecuta la capacidad POML "./src/agent/examples/woof.poml" en el archivo ROS2 bag "./data/sample/ros2/mcap".
Resultado:
meow 🐱 4 topics 🐱💤🎯Pipelines de lenguaje natural · el modelo: una cadencia, compuertas y tareas; vista previa → ejecutar → guardar → por lotes → en el borde
Reducción de datos basada en eventos · detectar eventos, mantener ventanas alrededor de ellos (fragmentos o un solo archivo bag reducido), procesar por lotes entre flotas, subir a la nube
Robots ROS2 en vivo a través de rosbridge · un tutorial paso a paso
Registros de texto ROS · inspeccionar errores y advertencias de ~/.ros/log sin abrir un archivo bag
MQTT · temas IoT en vivo, Sparkplug B, grabación en el borde
PostgreSQL / TimescaleDB · cada tabla es un tema
InfluxDB 3 · cada medición es un tema
Automotriz MDF4 y CAN (beta) · los grupos de canales y los mensajes DBC son temas; las unidades acompañan
LLM locales · completamente sin conexión con Ollama: tus datos y tu modelo nunca salen de la máquina
Rerun · "muéstrame ese evento en Rerun": cualquier ventana de tiempo como una grabación lista para abrir
Lichtblick / Foxglove · ventanas de eventos como MCAP + diseños predefinidos para cualquier visor
PlotJuggler · abre las salidas MCAP de Bagel directamente; sesiones predefinidas de una sola frase, exportaciones CSV/Parquet planas
Cloudini · decodificar nubes de puntos comprimidas con cloudini, o comprimir los temas PointCloud2 de un bag en CompressedPointCloud2
Slack · las pipelines publican en tu canal de operaciones cuando se activan: "🚨 frenada brusca en {asset}"
LeRobot (beta) · los eventos detectados se convierten en episodios de entrenamiento: un LeRobotDataset v3.0
Aspectos que sabemos que son imperfectos, para que no los descubras de la manera difícil:
Dos formatos están en beta. Los lectores de MDF4/CAN automotrices están verificados contra archivos que generamos con las mismas bibliotecas que los leen (asammdf, python-can); las capturas reales producidas por CANape/INCA/Vector aún no han pasado por nuestro banco de pruebas. Las exportaciones de LeRobot pasan las pruebas de carga limpiamente con el paquete real lerobot, pero aún no se ha entrenado ninguna política a partir de una exportación de Bagel.
Las tasas de reducción dependen de la carga de trabajo y no están evaluadas. La relación es la duración de la ventana de eventos sobre la duración total: las grabaciones tranquilas se reducen drásticamente, las llenas de eventos mucho menos. Las cifras en este README son salidas de demostración ilustrativas, no un punto de referencia medido.
SSE es el transporte documentado. Streamable HTTP ya está conectado (MCP_TRANSPORT=streamable-http), pero compose no reenvía la configuración y ningún runbook de cliente lo cubre todavía, por lo que SSE es la ruta compatible hoy (#168).
Sin autenticación en el endpoint MCP. Por diseño se vincula solo a localhost; trátalo como un socket de base de datos y consulta SECURITY.md antes de compartirlo fuera de tu máquina.
Los modelos locales pequeños tienen dificultades con pipelines de múltiples pasos. Un modelo de 4-8B maneja la selección de herramientas y SQL simple; la reducción por ventanas de eventos y las uniones de múltiples temas requieren un modelo más grande. Consulta la guía de LLM locales.
Las pruebas de extremo a extremo de bases de datos en vivo se ejecutan fuera de CI. Las pruebas puras de las suites de InfluxDB y Postgres se ejecutan en CI; sus casos de extremo a extremo en vivo solo se ejecutan contra una instancia a la que les apuntes. Todo lo demás, incluidas las rutas de escritura de ROS bag, se ejecuta en CI.
¡Nos encantaría tu ayuda! La forma más fácil de apoyar el proyecto es darle una ⭐ en GitHub.
Otras grandes formas de contribuir:
Solicitar nuevas funciones
Reportar errores
Mejorar la documentación
Agregar nuevas capacidades
Antes de contribuir, por favor revisa las directrices.
Únete a la conversación en nuestro servidor de Discord. Pasamos el rato allí regularmente.
Bagel es de código abierto bajo la Licencia Apache 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
