Cluster and diagnostic tools

The fleet’s health and resources, and the diagnostic reads an agent uses when something is wrong.

Permission is what the tool server requires before it dispatches; who holds it is read from the control plane’s own grant. The two are read from different places on purpose: a tool server that grants more than the control plane does offers an operation and then has it refused halfway through a conversation.

Advertised says whether the tool appears in the default tool list. Most do not: a small window is advertised and the rest are found with search_tools, read with describe_tool and invoked with request_tool. A tool reached that way is checked against the same permission as a direct call.

Generated from Tool. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

Tool	Permission	Who holds it	Advertised
cluster_events	events:read	developer, operator, readonly, support	no
cluster_health	nodes:read	developer, operator, readonly, support	yes
cluster_nodes	nodes:read	developer, operator, readonly, support	no
cluster_resources	nodes:read	developer, operator, readonly, support	no
debug_bundle	debug:access	operator	no
debug_consul	operator	—	no
debug_docker	operator	—	no
debug_reconcile	debug:access	operator	no
debug_scaling	debug:access	operator	no

cluster_events

Stream or retrieve recent cluster events. Use format=‘summary’ (default) for minimal output, ‘standard’ for operational details, or ‘full’ for complete data.

Argument	Type	Required	Meaning
since	string	no	Show events since (e.g., ‘10m’, ‘1h’)
type	one of all, deployment, container, scaling, error, warning	no	Filter by event type
deployment	string	no	Filter by deployment name
limit	integer	no	Maximum events to return
format	one of summary, standard, full	no	Response detail level: ‘summary’ (minimal), ‘standard’ (operational), ‘full’ (complete). Default: summary

cluster_health

Get overall cluster health status and any active alerts

Takes no arguments.

cluster_nodes

List all nodes in the cluster with resource utilization

Takes no arguments.

cluster_resources

Get cluster-wide resource utilization summary

Argument	Type	Required	Meaning
deployment	string	no	Optional: filter by deployment

debug_bundle

Generate a comprehensive debug bundle for support and troubleshooting. Contains logs, configs, and system state.

Argument	Type	Required	Meaning
include_logs	boolean	no	Include recent logs from Odysseus and deployments
include_config	boolean	no	Include sanitized configuration (secrets redacted)
include_metrics	boolean	no	Include recent metrics snapshots
deployments	array	no	Specific deployments to include (omit for all with issues)
since	string	no	Include data since (e.g., ‘1h’, ‘24h’)

debug_consul

Check Consul service discovery health and connectivity from Odysseus perspective

Argument	Type	Required	Meaning
service	string	no	Specific service to check (optional)
include_catalog	boolean	no	Include full service catalog in response

debug_docker

Check Docker daemon connectivity and resource availability from Odysseus perspective

Argument	Type	Required	Meaning
include_containers	boolean	no	Include list of all containers (not just managed)
include_images	boolean	no	Include list of available images
include_networks	boolean	no	Include network information

debug_reconcile

Force reconciliation of a deployment’s desired vs actual state. Useful for investigating drift or stuck deployments.

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment to reconcile
verbose	boolean	no	Include detailed reconciliation steps in response

debug_scaling

Debug autoscaling behavior for a deployment. Shows metrics, cooldowns, and scaling recommendations.

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment to debug
time_range	one of 15m, 1h, 6h, 24h	no	Time range for metrics analysis