agentflight

Overview Schema Source Related Servers Discussions Admin

agentflight_export_otel

Idempotent

Converts recorded agent cassette spans into W3C TraceContext and OpenTelemetry JSON traces, enabling latency waterfall visualization and distributed tracing in APM platforms.

Instructions

Export recorded AgentFlight cassette spans into W3C TraceContext and OpenTelemetry JSON traces.

Purpose

Converts recorded agent execution spans into OpenTelemetry-compliant trace spans with standard gen_ai semantic conventions, enabling critical-path latency waterfall visualization and distributed tracing in systems like StackPulse, Jaeger, or Datadog.

When to use

Exporting agent trajectories into APM or observability platforms for SLO tracking and latency bottleneck analysis.
Visualizing parent-child relationships and parallel tool execution spans.

When NOT to use

Do NOT use to verify hash chain cryptographic integrity; use agentflight_verify_cassette instead.
Do NOT use to compare two trajectories for regressions; use agentflight_diff_cassettes instead.

Behavior & Side Effects

If output_path is provided, writes the formatted OpenTelemetry JSON to that file; otherwise returns spans in-memory.
Idempotent: Successive calls with identical arguments produce identical span outputs.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cassette_path": "<cassette_path>"
    },
    "name": "agentflight_export_otel"
  }
}

Input Schema

Name	Required	Description
`output_path`	No	Optional filesystem path where OpenTelemetry trace JSON will be saved. If omitted, spans are returned in payload only.
`service_name`	No	Optional service name to populate in OpenTelemetry resource attributes. Defaults to cassette agent_id.
`cassette_path`	Yes	Filesystem path to the input .flight.json or .flight.jsonl cassette file.

Output Schema

Name	Required	Description	Default
`spans`	Yes	Array of W3C TraceContext compliant span dictionaries.
`span_count`	Yes	Total number of OpenTelemetry spans generated.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.1.1Nov 10, 2026

changedInput schema / properties / cassette_path / description

Previous value: -"Path to the .flight.json or .flight.jsonl cassette file."New value: +"Filesystem path to the input .flight.json or .flight.jsonl cassette file."

changedInput schema / properties / output_path / description

Previous value: -"Optional file path where exported OTel spans JSON will be written."New value: +"Optional filesystem path where OpenTelemetry trace JSON will be saved. If omitted, spans are returned in payload only."

changedInput schema / properties / service_name / description

Previous value: -"Optional override for the root OpenTelemetry service_name."New value: +"Optional service name to populate in OpenTelemetry resource attributes. Defaults to cassette agent_id."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "span_count": {
+      "description": "Total number of OpenTelemetry spans generated.",
+      "type": "integer"
+    },
+    "spans": {
+      "description": "Array of W3C TraceContext compliant span dictionaries.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "span_count",
+    "spans"
+  ],
+  "type": "object"
+}

First observedv1.1.0Nov 10, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), and the description adds the key non-obvious behavior: writing to disk when `output_path` is supplied versus returning spans in-memory otherwise. The idempotency note merely restates idempotentHint, and no permission or file-overwrite semantics are stated for the write path, so it stops short of a 5.

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

Conciseness4/5

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

The one-line summary is front-loaded and the headed sections make scanning easy, with no filler prose in the behavior or exclusion sections. It is slightly longer than strictly necessary — the Purpose paragraph partially restates the opening sentence — which keeps it from a 5.

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

Completeness5/5

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

With an output schema present, return-value detail is not needed, and the definition covers what matters: input file format, the optional file-write side effect, resource attribute naming, idempotency, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100% and each parameter (cassette_path, output_path, service_name with its agent_id default) is already documented in the schema. The description adds only the in-memory-versus-file behavioral framing for output_path and introduces no new format or syntax guidance, so the baseline 3 applies.

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

Purpose5/5

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

The opening sentence names a specific verb (export), a specific source (recorded AgentFlight cassette spans) and a specific output (W3C TraceContext / OpenTelemetry JSON traces). The Purpose section reinforces the distinguishing concept — gen_ai semantic conventions and latency waterfall visualization — so an agent can tell this apart from verify or diff siblings without reading schemas.

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

Usage Guidelines5/5

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

It gives both positive triggers (APM export, SLO tracking, latency bottleneck analysis, parent-child/parallel span visualization) and explicit exclusions that name the correct alternatives: `agentflight_verify_cassette` for hash-chain integrity and `agentflight_diff_cassettes` for regression comparison. The routing decision is fully specified.

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

Deploy Server