Tools reference

All times use RFC 3339, for example 2026-09-08T09:00:00Z.

query_logs

Search and filter log records.

Parameter	Type	Required	Meaning
query	string	no	Text to find in the log message.
severity	string	no	One of TRACE, DEBUG, INFO, WARN, ERROR, FATAL.
start_time	string	no	Start of the time range.
end_time	string	no	End of the time range.
limit	number	no	Records to return. Default 100, maximum 1000.

query_metrics

Read time-series metrics.

Parameter	Type	Required	Meaning
name	string	no	Metric name pattern.
start_time	string	yes	Start of the time range.
end_time	string	yes	End of the time range.

query_traces

Search traces.

Parameter	Type	Required	Meaning
service_name	string	no	Filter by service.
operation_name	string	no	Filter by span name.
start_time	string	no	Start of the time range.
end_time	string	no	End of the time range.
min_duration_ms	number	no	Only traces at least this long.
limit	number	no	Traces to return. Default 100.

get_trace

Read one trace.

Parameter	Type	Required	Meaning
trace_id	string	yes	The trace ID.

get_receiver_info

Report the effective OTLP endpoints of the root receiver. The tool has no parameters. It reads the engine’s health endpoint and returns this JSON object.

Field	Type	Meaning
otlpGrpcPort	number	The effective gRPC port. Send gRPC telemetry to this port.
otlpHttpPort	number	The effective HTTP port. Send HTTP telemetry to this port.
otlpGrpcConfiguredPort	number	The gRPC port that the root asked for.
otlpHttpConfiguredPort	number	The HTTP port that the root asked for.
otlpGrpcPortConflict	boolean	true when the gRPC port was busy and the root moved to another port.
otlpHttpPortConflict	boolean	true when the HTTP port was busy and the root moved to another port.
grpcEndpoint	string	The gRPC address, for example http://127.0.0.1:4317.
httpEndpoint	string	The HTTP address, for example http://127.0.0.1:4318.

Call this tool before you configure an OTLP exporter. Do not assume the default ports. See Ports and the effective port.

query_improvements

List the telemetry-quality findings that the Improvements page shows. Every parameter is optional. With no parameters the tool returns every finding.

Parameter	Type	Required	Meaning
impact	string	no	One of high, med, low.
source	string	no	One of logs, metrics, traces.
kind	string	no	The detector name, for example noisy_logs, stale_metric, or suggested_alert.
include_metric_health	boolean	no	Also return the per-metric health table. Default false.

The result has these fields.

Field	Type	Meaning
generatedAt	string	When the engine built the report.
windowSecs	number	The lookback window the engine scanned, in seconds.
findings	array	The findings that match the filters. Each finding has id, kind, impact, source, title, description, meta, recommendation, action, and ai.
counts	object	total, high, med, and low for the findings in the result.
metricHealth	array	One row per metric with metric, state (ok, stale, broken), points, and lastSeen. Present only when include_metric_health is true.

A finding has no state, so there is no tool to close one. The engine scans the last hour again every 30 seconds. After you fix the cause, the old telemetry ages out of the window and the finding disappears on its own. Call the tool again to confirm.

Example prompts

• “Query the logs for ERROR entries in the last hour and explain what happened.”
• “Find the slowest traces from the last 24 hours and name the bottleneck span.”
• “Get the trace abc123 and explain the span hierarchy.”
• “Read loggerhead://stats and summarise what has been collected.”
• “Call get_receiver_info and set OTEL_EXPORTER_OTLP_ENDPOINT to the gRPC address.”
• “Call query_improvements with impact high, fix the first finding in this project, then call it again to confirm the finding is gone.”