Monitoring & alerts tools
These tools give an AI client access to a server’s real-time performance metrics and the alert rules that watch them. They cover requests like “how loaded is web-01 right now,” “which server is using the most disk I/O,” or “set up an alert for high memory usage on the database servers.”
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
get_cpu_usage | CPU utilization statistics for a server | Read-only |
get_memory_usage | Memory utilization statistics for a server | Read-only |
get_disk_usage | Disk space usage for a device or partition | Read-only |
get_disk_io | Disk read/write throughput for a server | Read-only |
get_network_traffic | Network bandwidth and packet rates for a server | Read-only |
get_top_servers | Servers ranked by resource usage | Read-only |
get_server_metrics_summary | Combined CPU, memory, disk, and network overview for a server | Read-only |
list_alerts | Triggered alerts, with filtering | Read-only |
get_alert | Full detail for a single alert | Read-only |
mute_alert | Suppress notifications for an alert | Additive |
get_alert_rules | Configured alert rules and thresholds | Read-only |
create_alert_rule | Create a new alert rule | Additive |
update_alert_rule | Modify an existing alert rule | Idempotent write |
delete_alert_rule | Permanently delete an alert rule | Destructive |
Metrics
The five time-series metrics tools (get_cpu_usage, get_memory_usage, get_disk_usage, get_disk_io, get_network_traffic) all accept start_date and end_date in ISO 8601 format (e.g. 2024-01-01T00:00:00Z). When start_date is omitted, it defaults to 24 hours before the current time; end_date defaults to now.
get_cpu_usage
Get CPU utilization metrics for a server over a time range. Returns current, average, min, and max usage percentage, along with a health status derived from the current value.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
start_date | string | No | Start of the time range, ISO 8601 (e.g. 2024-01-01T00:00:00Z). Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 (e.g. 2024-01-02T00:00:00Z) |
Example
“Show me CPU usage for web-01 over the last 24 hours”
The client resolves web-01 to a server ID and returns current, average, min, and max CPU usage with a status (idle, low, moderate, high, or critical).
get_memory_usage
Get RAM utilization metrics for a server over a time range. Returns current, average, min, and max usage percentage, along with a health status. Useful for investigating memory pressure or out-of-memory issues.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“Is db-02 running low on memory?”
Returns memory usage statistics for the last 24 hours by default, including a status field that flags idle, low, moderate, high, or critical usage.
get_disk_usage
Get disk space usage for a server by device or partition. Returns usage percentage and total, used, and free space in human-readable units. Requires either device or partition; if neither is given, the tool automatically looks up the server’s available devices and uses the first one.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
device | string | No | Device path (e.g. /dev/sda1). Auto-discovered if omitted and partition is also omitted |
partition | string | No | Partition path (e.g. /) |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“How much disk space is left on the root partition of app-03?”
Returns current, average, min, and max usage percentage plus total/used/free space for the resolved device or partition.
get_disk_io
Get disk read/write throughput metrics for a server. Returns peak and average transfer rates per device. Useful for diagnosing storage performance bottlenecks.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get disk I/O metrics for |
device | string | No | Disk device name (e.g. sda, nvme0n1) |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“Check disk I/O on the database server for the last hour”
Returns read/write throughput data points for the requested device and time range.
get_network_traffic
Get network bandwidth and traffic metrics for a server by interface. Returns current, average, and peak values for input/output throughput (bps) and packet rate (pps).
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
interface | string | No | Network interface (e.g. eth0) |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“What’s the network throughput on the load balancer today?”
Returns current, average, and peak input/output bandwidth and packet rates for the server’s interface.
get_top_servers
Get the top servers in a workspace ranked by resource usage over the last 24 hours. Supports querying multiple metric types in a single call.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
metric_types | string | No | Comma-separated metric types: cpu, memory, disk_io, traffic. Leave empty to get all four |
Example
“Which servers are using the most CPU and memory right now?”
Calling with metric_types="cpu,memory" returns ranked results for both metrics in one response.
get_server_metrics_summary
Get a comprehensive monitoring overview for a single server, combining CPU, memory, disk, and network data availability into one compact response. Intended as a quick health check or a starting point before drilling into a specific metric with its dedicated tool.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
hours | integer | No | Hours of history to summarize. Default 24, capped at 168 (one week) |
Example
“Give me a quick health check on web-01”
Returns a summary noting whether CPU, memory, disk, and network data are available for the requested window, with pointers to the dedicated tools for full time-series data.
Alerts
Alert rules define the thresholds that generate alerts; alerts are the individual notifications those rules trigger. get_alert_rules and the CRUD tools below all operate on rules, while list_alerts, get_alert, and mute_alert operate on the alerts a rule has produced.
list_alerts
List alerts for a workspace, optionally filtered by server, status, or acknowledgement/dismissal state. Useful for checking active alerts or reviewing alert history.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | No | Filter by server ID |
status | string | No | Filter by alert status |
acknowledged | boolean | No | Filter by acknowledgement state (false returns active/unacknowledged alerts) |
dismissed | boolean | No | Filter by dismissed state |
page | integer | No | Page number |
page_size | integer | No | Items per page |
Example
“Show me active alerts on the production servers”
Returns alerts filtered to acknowledged=false, so only alerts that haven’t been reviewed yet appear.
get_alert
Get full detail for a specific alert.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert ID to retrieve |
Example
“What triggered alert abc-123?”
Returns the full alert record, including the rule and metric values that caused it to fire.
mute_alert
Mute an alert to temporarily suppress its notifications. Use this once an alert is known and already being worked on, to stop repeated notifications without resolving the underlying rule.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert ID to mute |
duration | integer | No | Mute duration in minutes |
Example
“Mute that disk space alert for the next 2 hours, we’re already fixing it”
Suppresses notifications for the alert for the given duration.
get_alert_rules
Get the monitoring alert rules and notification thresholds configured for servers in a workspace, optionally filtered to one server.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | No | Filter rules to a specific server |
Example
“What alert rules are configured for the database servers?”
Returns each rule’s condition, threshold, and notification settings.
create_alert_rule
Create an alert rule that defines a monitoring threshold and how it should notify. Use this to set up new monitoring for CPU, memory, or disk metrics.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the alert rule |
metric_type | string | Yes | Metric to monitor (e.g. cpu, memory, disk) |
condition | string | Yes | Condition operator (e.g. gt, lt, gte, lte) |
threshold | number | Yes | Threshold value that triggers the alert |
servers | array | No | Server IDs to apply the rule to |
notification_channels | array | No | Notification channel IDs |
description | string | No | Description of the rule |
enabled | boolean | No | Whether the rule is active. Default true |
Example
“Alert me if any web server’s memory usage goes above 90%”
Creates a rule with metric_type="memory", condition="gt", and threshold=90, scoped to the specified servers.
update_alert_rule
Update an existing alert rule. Only the fields included in the call are changed; at least one updatable field must be provided. Use this to adjust thresholds or notification settings without recreating the rule.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Alert rule ID to update |
name | string | No | New name |
metric_type | string | No | New metric type |
condition | string | No | New condition operator |
threshold | number | No | New threshold value |
servers | array | No | New list of server IDs |
notification_channels | array | No | New list of notification channel IDs |
description | string | No | New description |
enabled | boolean | No | Enable or disable the rule |
Example
“Raise the CPU alert threshold for db-02 to 95%”
Updates only threshold on the matching rule, leaving its other fields unchanged.
delete_alert_rule
Permanently delete an alert rule. Use this to remove rules that are no longer needed.
Access: Destructive
Deleting an alert rule cannot be undone. Consider disabling the rule with update_alert_rule (enabled: false) instead if you might need it again.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Alert rule ID to delete |
Example
“Delete the old disk space alert rule for the decommissioned server”
Removes the rule permanently; it stops evaluating and generating alerts immediately.