tools

var AlarmQueryTool = NewTool(
	"query_alarms",
	`Query alarms from SkyWalking OAP. Alarms are triggered when metrics breach configured thresholds.

Examples:
- {"start": "-1h"}: All alarms in the last hour
- {"scope": "Service", "start": "-30m"}: Service-level alarms in the last 30 minutes
- {"keyword": "timeout", "start": "-1h"}: Alarms whose message contains "timeout"
- {"tags": [{"key": "level", "value": "critical"}], "start": "-1h"}: Alarms with a specific tag`,
	queryAlarms,
	mcp.WithString("scope",
		mcp.Enum("All", "Service", "ServiceInstance", "Endpoint", "Process",
			"ServiceRelation", "ServiceInstanceRelation", "EndpointRelation", "ProcessRelation"),
		mcp.Description("Scope to filter alarms.")),
	mcp.WithString("keyword", mcp.Description("Keyword to filter alarm messages.")),
	mcp.WithArray("tags",
		mcp.Description("Array of alarm tags to filter by, each with key and value."),
		mcp.Items(map[string]any{
			"type": "object",
			"properties": map[string]any{
				"key":   map[string]any{"type": "string"},
				"value": map[string]any{"type": "string"},
			},
			"required": []string{"key", "value"},
		}),
	),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive step sizing.")),
	mcp.WithNumber("page_num", mcp.Description("Page number, default 1.")),
	mcp.WithNumber("page_size", mcp.Description("Page size, default 15.")),
)

var EndpointsTopologyTool = NewTool(
	"query_endpoints_topology",
	`Query the endpoint dependency topology for a given endpoint from SkyWalking OAP (getEndpointDependencies).

Returns the topology of endpoints that the given endpoint depends on or is depended upon by, including endpoint nodes and the calls between them.

Examples:
- {"endpoint_id": "ep-id-1"}: Endpoint topology for the last 30 minutes
- {"endpoint_id": "ep-id-1", "start": "-1h"}: Endpoint topology for the last hour`,
	queryEndpointsTopology,
	mcp.WithString("endpoint_id",
		mcp.Required(),
		mcp.Description("The ID of the endpoint to query dependencies for.")),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive step sizing.")),
)

var EventQueryTool = NewTool(
	"query_events",
	`Query events from SkyWalking OAP. Events record changes or incidents on a service, instance, or endpoint (e.g. deployments, restarts, scaling).

Examples:
- {"service": "Your_ApplicationName", "start": "-1h"}: Recent events for a service
- {"type": "Error", "start": "-30m"}: Error events in the last 30 minutes
- {"service": "Your_ApplicationName", "type": "Normal"}: Normal events for a service`,
	queryEvents,
	mcp.WithString("uuid", mcp.Description("Filter by event UUID.")),
	mcp.WithString("service", mcp.Description("Service name to filter events.")),
	mcp.WithString("service_instance", mcp.Description("Service instance name to filter events.")),
	mcp.WithString("endpoint", mcp.Description("Endpoint name to filter events.")),
	mcp.WithString("name", mcp.Description("Event name to filter.")),
	mcp.WithString("type", mcp.Enum("Normal", "Error"),
		mcp.Description("Event type: Normal or Error.")),
	mcp.WithString("layer", mcp.Description("Layer to filter events.")),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive step sizing.")),
	mcp.WithString("order", mcp.Enum(orderASC, "DES"),
		mcp.Description("Order events by time: ASC (oldest first) or DES (newest first, default).")),
	mcp.WithNumber("page_num", mcp.Description("Page number, default 1.")),
	mcp.WithNumber("page_size", mcp.Description("Page size, default 15.")),
)

var InstancesTopologyTool = NewTool(
	"query_instances_topology",
	`Query the service instance topology between two services from SkyWalking OAP (getServiceInstanceTopology).

Returns the topology of service instances for the given client and server services, including instance nodes and the calls between them.

Examples:
- {"client_service_id": "svc-id-1", "server_service_id": "svc-id-2"}: Instance topology for the last 30 minutes
- {"client_service_id": "svc-id-1", "server_service_id": "svc-id-2", "start": "-1h"}: Instance topology for the last hour`,
	queryInstancesTopology,
	mcp.WithString("client_service_id",
		mcp.Required(),
		mcp.Description("The ID of the client (upstream) service.")),
	mcp.WithString("server_service_id",
		mcp.Required(),
		mcp.Description("The ID of the server (downstream) service.")),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive step sizing.")),
)

var ListEndpointsTool = NewTool(
	"list_endpoints",
	`List endpoints of a service registered in SkyWalking OAP.

An endpoint represents an individual API path or operation exposed by a service.
Use list_services to obtain a service ID before calling this tool.

The response includes each endpoint's id and name.
The id can be used as a filter in metrics queries that accept an endpoint scope.

Workflow:
1. Call list_layers to find available layers
2. Call list_services with a layer to find the service and its ID
3. Call this tool with the service ID to list its endpoints

Examples:
- {"service_id": "abc123"}: List all endpoints of a service
- {"service_id": "abc123", "keyword": "/api/user", "limit": 20}: Search endpoints by keyword`,
	listEndpoints,
	mcp.WithTitleAnnotation("List service endpoints"),
	mcp.WithString("service_id", mcp.Required(),
		mcp.Description("The service ID to list endpoints for. Use list_services to obtain a service ID."),
	),
	mcp.WithString("keyword",
		mcp.Description("Keyword to filter endpoints by name. Leave empty to list all endpoints."),
	),
	mcp.WithNumber("limit",
		mcp.Description("Maximum number of endpoints to return. Defaults to 100."),
	),
	mcp.WithString("start",
		mcp.Description(`Start time for the query. Examples: "2024-01-01 12:00:00", "-1h" (1 hour ago).`),
	),
	mcp.WithString("end",
		mcp.Description(`End time for the query. Examples: "2024-01-01 13:00:00", "now". Defaults to current time if omitted.`),
	),
	mcp.WithString("step",
		mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive sizing: SECOND (<1h), MINUTE (1h-24h), HOUR (1d-7d), DAY (>7d)."),
	),
	mcp.WithBoolean("cold",
		mcp.Description("Whether to query from cold-stage storage. Set to true for historical data queries."),
	),
)

var ListInstancesTool = NewTool(
	"list_instances",
	`List all instances of a service registered in SkyWalking OAP.

A service instance represents an individual running process of a service (e.g. a pod or JVM process).
Use list_services to obtain a service ID before calling this tool.

The response includes each instance's id, name, language, instanceUUID, and attributes.
The id can be used as a filter in metrics or log queries that accept a service_instance_id.

Workflow:
1. Call list_layers to find available layers
2. Call list_services with a layer to find the service and its ID
3. Call this tool with the service ID and a time range to list its instances

Examples:
- {"service_id": "abc123", "start": "2024-01-01 12:00", "end": "2024-01-01 13:00"}: List instances in a time range
- {"service_id": "abc123", "start": "-1h"}: List instances active in the past hour`,
	listInstances,
	mcp.WithTitleAnnotation("List service instances"),
	mcp.WithString("service_id", mcp.Required(),
		mcp.Description("The service ID to list instances for. Use list_services to obtain a service ID."),
	),
	mcp.WithString("start", mcp.Required(),
		mcp.Description(`Start time for the query. Examples: "2024-01-01 12:00:00", "-1h" (1 hour ago), "-30m" (30 minutes ago).`),
	),
	mcp.WithString("end",
		mcp.Description(`End time for the query. Examples: "2024-01-01 13:00:00", "now". Defaults to current time if omitted.`),
	),
	mcp.WithString("step",
		mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive sizing: SECOND (<1h), MINUTE (1h-24h), HOUR (1d-7d), DAY (>7d)."),
	),
	mcp.WithBoolean("cold",
		mcp.Description("Whether to query from cold-stage storage. Set to true for historical data queries."),
	),
)

var ListLayersTool = NewTool(
	"list_layers",
	`List all available layers registered in SkyWalking OAP.

A layer represents a technology or deployment environment in SkyWalking's topology,
such as GENERAL, MESH, K8S, OS_LINUX, etc. Layers are used to categorize services
and filter topology views.

Workflow:
1. Call this tool to discover which layers are available in the monitored environment
2. Use the returned layer names when querying services or metrics that require a layer filter

Examples:
- {}: List all layers (no parameters required)`,
	listLayers,
	mcp.WithTitleAnnotation("List available layers"),
)

var ListProcessesTool = NewTool(
	"list_processes",
	`List processes of a service instance registered in SkyWalking OAP.

A process represents an individual OS or language-level process running within a service instance.
Use list_instances to obtain an instance ID before calling this tool.

The response includes each process's id, name, serviceId, serviceName, instanceId, instanceName,
agentId, detectType, labels, and attributes.

Workflow:
1. Call list_layers to find available layers
2. Call list_services with a layer to find the service and its ID
3. Call list_instances with the service ID to find an instance and its ID
4. Call this tool with the instance ID and a time range to list its processes

Examples:
- {"instance_id": "abc123", "start": "-1h"}: List processes active in the past hour
- {"instance_id": "abc123", "start": "2024-01-01 12:00", "end": "2024-01-01 13:00"}: List processes in a time range`,
	listProcesses,
	mcp.WithTitleAnnotation("List instance processes"),
	mcp.WithString("instance_id", mcp.Required(),
		mcp.Description("The instance ID to list processes for. Use list_instances to obtain an instance ID."),
	),
	mcp.WithString("start", mcp.Required(),
		mcp.Description(`Start time for the query. Examples: "2024-01-01 12:00:00", "-1h" (1 hour ago), "-30m" (30 minutes ago).`),
	),
	mcp.WithString("end",
		mcp.Description(`End time for the query. Examples: "2024-01-01 13:00:00", "now". Defaults to current time if omitted.`),
	),
	mcp.WithString("step",
		mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive sizing: SECOND (<1h), MINUTE (1h-24h), HOUR (1d-7d), DAY (>7d)."),
	),
	mcp.WithBoolean("cold",
		mcp.Description("Whether to query from cold-stage storage. Set to true for historical data queries."),
	),
)

var ListServicesTool = NewTool(
	"list_services",
	`List all services registered in SkyWalking OAP under a specific layer.

A service represents a logical grouping of monitored workloads. Each service belongs to one
or more layers (e.g. GENERAL, MESH, K8S). Use list_layers first to discover available layers.

The response includes each service's id, name, group, shortName, layers, and normal flag.
The id can be used as a filter in other tools such as query_logs or query_traces.

Workflow:
1. Call list_layers to discover available layers
2. Call this tool with the desired layer to get the services in that layer

Examples:
- {"layer": "GENERAL"}: List all services in the GENERAL layer
- {"layer": "MESH"}: List all services in the service mesh layer`,
	listServices,
	mcp.WithTitleAnnotation("List services by layer"),
	mcp.WithString("layer", mcp.Required(),
		mcp.Description("The layer to list services for. Use list_layers to get available layer names."),
	),
)

var LogQueryTool = NewTool(
	"query_logs",
	`Query logs from SkyWalking OAP with flexible filters.

Workflow:
1. Use this tool to find logs matching specific criteria
2. Specify one or more query conditions to narrow down results
3. Use start/end to limit the time range for the search
4. Supports filtering by service, instance, endpoint, trace, tags, and time
5. Supports cold storage query and pagination

Examples:
- {"service_id": "Your_ApplicationName", "start": "2024-06-01 12:00:00", "end": "2024-06-01 13:00:00"}: Query logs for a service in a time range
- {"trace_id": "abc123..."}: Query logs related to a specific trace
- {"trace_id": "abc123...", "segment_id": "seg456...", "span_id": 0}: Query logs for a specific span
- {"tags": [{"key": "level", "value": "ERROR"}], "cold": true}: Query error logs from cold storage`,
	queryLogs,
	mcp.WithString("service_id", mcp.Description("Service ID to filter logs.")),
	mcp.WithString("service_instance_id", mcp.Description("Service instance ID to filter logs.")),
	mcp.WithString("endpoint_id", mcp.Description("Endpoint ID to filter logs.")),
	mcp.WithString("trace_id", mcp.Description("Related trace ID to filter logs by trace scope.")),
	mcp.WithString("segment_id", mcp.Description("Related segment ID to narrow logs to a specific segment within a trace.")),
	mcp.WithNumber("span_id", mcp.Description("Related span ID to narrow logs to a specific span within a segment.")),
	mcp.WithArray("tags",
		mcp.Description("Array of log tags, each with key and value."),
		mcp.Items(map[string]any{
			"type": "object",
			"properties": map[string]any{
				"key":   map[string]any{"type": "string"},
				"value": map[string]any{"type": "string"},
			},
			"required": []string{"key", "value"},
		}),
	),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity: SECOND, MINUTE, HOUR, DAY. "+
			"If not specified, uses adaptive step sizing: "+
			"SECOND (<1h), MINUTE (1h-24h), HOUR (1d-7d), DAY (>7d)")),
	mcp.WithBoolean("cold", mcp.Description("Whether to query from cold-stage storage.")),
	mcp.WithNumber("page_num", mcp.Description("Page number, default 1.")),
	mcp.WithNumber("page_size", mcp.Description("Page size, default 15.")),
	mcp.WithString("query_order", mcp.Enum("ASC", "DES"),
		mcp.Description("Order logs by timestamp: ASC (oldest first) or DES (newest first, default).")),
)

var MQEExpressionTool = NewTool(
	"execute_mqe_expression",
	`Execute MQE (Metrics Query Expression) to query and calculate metrics data.

MQE is SkyWalking's powerful query language that allows you to:
- Query metrics with labels: service_percentile{p='50,75,90,95,99'}
- Perform calculations: service_sla * 100, service_cpm / 60
- Compare values: service_resp_time > 3000
- Use aggregations: avg(service_cpm), sum(service_cpm), max(service_resp_time)
- Mathematical functions: round(service_cpm / 60, 2), abs(service_resp_time - 1000)
- TopN queries: top_n(service_cpm, 10, des)
- Trend analysis: increase(service_cpm, 2), rate(service_cpm, 5)
- Sort operations: sort_values(service_resp_time, 10, des)
- Baseline comparison: baseline(service_resp_time, upper)
- Relabel operations: relabels(service_percentile{p='50,75,90,95,99'}, p='50,75,90,95,99', percentile='P50,P75,P90,P95,P99')
- Logical operations: view_as_seq([metric1, metric2]), is_present([metric1, metric2])
- Label aggregation: aggregate_labels(total_commands_rate, sum)

Result Types:
- SINGLE_VALUE: Single metric value (e.g., avg(), sum())
- TIME_SERIES_VALUES: Time series data with timestamps
- SORTED_LIST: Sorted metric values (e.g., top_n())
- RECORD_LIST: Record-based metrics
- LABELED_VALUE: Metrics with multiple labels

USAGE REQUIREMENTS:
- The 'expression' parameter is mandatory for all queries
- For service-specific queries, specify 'service_name' and optionally 'layer' (defaults to GENERAL)
- For relation metrics, provide both source and destination entity parameters
- Use 'start' and 'end' to set a time range; if omitted, defaults to the last 30 minutes
- Use 'debug: true' for query tracing and troubleshooting
- Use 'cold: true' to query from cold storage (BanyanDB only)

Entity Filtering (all optional):
- Service level: service_name + layer + normal
- Instance level: service_instance_name
- Endpoint level: endpoint_name
- Process level: process_name
- Relation queries: dest_service_name + dest_layer, dest_service_instance_name, etc.

Examples:
- {expression: "service_sla * 100", service_name: "Your_ApplicationName", layer: "GENERAL",
  start: "-1h", end: "now"}: Convert SLA to percentage for last hour
- {expression: "service_resp_time > 3000 && service_cpm < 1000", service_name: "Your_ApplicationName", 
	start: "-30m", end: "now"}: Find high latency with low traffic in last 30 minutes
- {expression: "avg(service_cpm)", start: "-2h", end: "now"}: Calculate average CPM for last 2 hours
- {expression: "service_cpm", start: "now", end: "+24h"}: Query CPM for next 24 hours (useful for capacity planning)
- {expression: "top_n(service_cpm, 10, des)", start: "2025-07-06 16:00:00", end: "2025-07-06 17:00:00", 
	step: "MINUTE"}: Top 10 services by CPM with minute granularity`,
	executeMQEExpression,
	mcp.WithString("expression", mcp.Required(),
		mcp.Description("MQE expression to execute (required). "+
			"Examples: `service_sla`, `avg(service_cpm)`, `service_sla * 100`, `service_percentile{p='50,75,90,95,99'}`")),
	mcp.WithString("service_name", mcp.Description("Service name for entity filtering")),
	mcp.WithString("layer",
		mcp.Description("Service layer for entity filtering. "+
			"Examples: `GENERAL` (default), `MESH`, `K8S_SERVICE`, `DATABASE`, `VIRTUAL_DATABASE`. "+
			"Defaults to GENERAL if not specified")),
	mcp.WithString("service_instance_name", mcp.Description("Service instance name for entity filtering")),
	mcp.WithString("endpoint_name", mcp.Description("Endpoint name for entity filtering")),
	mcp.WithString("process_name", mcp.Description("Process name for entity filtering")),
	mcp.WithBoolean("normal",
		mcp.Description("Whether the service is normal (has agent installed). "+
			"If not specified, will be auto-detected based on service layer")),
	mcp.WithString("dest_service_name", mcp.Description("Destination service name for relation metrics")),
	mcp.WithString("dest_layer",
		mcp.Description("Destination service layer for relation metrics. "+
			"Examples: `GENERAL`, `MESH`, `K8S_SERVICE`, `DATABASE`")),
	mcp.WithString("dest_service_instance_name", mcp.Description("Destination service instance name for relation metrics")),
	mcp.WithString("dest_endpoint_name", mcp.Description("Destination endpoint name for relation metrics")),
	mcp.WithString("dest_process_name", mcp.Description("Destination process name for relation metrics")),
	mcp.WithBoolean("dest_normal", mcp.Description("Whether the destination service is normal")),
	mcp.WithString("start", mcp.Description("Start time for the query. Examples: `2025-07-06 12:00:00`, `-1h` (1 hour ago), `-30m` (30 minutes ago)")),
	mcp.WithString("end", mcp.Description("End time for the query. Examples: `2025-07-06 13:00:00`, `now`, `-10m` (10 minutes ago)")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY", "MONTH"),
		mcp.Description("Time step between start time and end time: "+
			"SECOND (second-level), MINUTE (minute-level), HOUR (hour-level), "+
			"DAY (day-level), MONTH (month-level). "+
			"If not specified, uses adaptive step sizing: "+
			"SECOND (<1h), MINUTE (1h-24h), HOUR (1d-7d), DAY (>7d)")),
	mcp.WithBoolean("cold", mcp.Description("Whether to query from cold-stage storage")),
	mcp.WithBoolean("debug", mcp.Description("Enable query tracing and debugging")),
	mcp.WithBoolean("dump_db_rsp", mcp.Description("Dump database response for debugging")),
)

var MQEMetricsListTool = NewTool(
	"list_mqe_metrics",
	`List available metrics in SkyWalking that can be used in MQE expressions.

This tool helps you discover what metrics are available for querying and their metadata information 
including metric type and catalog. You can optionally provide a regex pattern to filter the metrics by name.

Metric Categories:
- Service metrics: service_sla, service_cpm, service_resp_time, service_apdex, service_percentile
- Instance metrics: service_instance_sla, service_instance_cpm, service_instance_resp_time
- Endpoint metrics: endpoint_sla, endpoint_cpm, endpoint_resp_time, endpoint_percentile
- Relation metrics: service_relation_client_cpm, service_relation_server_cpm
- Database metrics: database_access_resp_time, database_access_cpm
- Infrastructure metrics: service_cpu, service_memory, service_thread_count

Metric Types:
- REGULAR_VALUE: Single value metrics (e.g., service_sla, service_cpm)
- LABELED_VALUE: Multi-label metrics (e.g., service_percentile, k8s_cluster_deployment_status)
- SAMPLED_RECORD: Record-based metrics

Usage Tips:
- Use regex patterns to filter specific metric categories
- Check metric type to understand how to use them in MQE expressions
- Regular value metrics can be used directly in calculations
- Labeled value metrics require label selectors: metric_name{label='value'}

Examples:
- {regex: "service_.*"}: List all service-related metrics
- {regex: ".*_cpm"}: List all CPM (calls per minute) metrics
- {regex: ".*percentile.*"}: List all percentile metrics
- {}: List all available metrics`,
	listMQEMetrics,
	mcp.WithString("regex", mcp.Description("Optional regex pattern to filter metrics by name. Examples: `service_.*`, `.*_cpm`, `endpoint_.*`")),
)

var MQEMetricsTypeTool = NewTool(
	"get_mqe_metric_type",
	`Get type information for a specific metric.

This tool returns the type and catalog information for a given metric name, which helps understand 
what kind of data the metric contains and how it should be used in MQE expressions.

Metric Types:
- REGULAR_VALUE: Single numeric value metrics
  - Can be used directly in arithmetic operations
  - Examples: service_sla, service_cpm, service_resp_time
  - Usage: service_sla, service_sla * 100, avg(service_cpm)

- LABELED_VALUE: Multi-dimensional metrics with labels
  - Require label selectors to specify which values to query
  - Examples: service_percentile, k8s_cluster_deployment_status
  - Usage: service_percentile{p='50,75,90,95,99'}

- SAMPLED_RECORD: Record-based metrics with sampling
  - Used for detailed record analysis
  - Examples: top_n_database_statement, traces
  - Usage: Complex aggregations and filtering

Understanding metric types is crucial for:
- Writing correct MQE expressions
- Knowing whether to use label selectors
- Understanding result data structure
- Choosing appropriate aggregation functions

Examples:
- {metric_name: "service_cpm"}: Get type info for service CPM metric
- {metric_name: "service_percentile"}: Get type info for service percentile metric
- {metric_name: "endpoint_sla"}: Get type info for endpoint SLA metric`,
	getMQEMetricsType,
	mcp.WithString("metric_name", mcp.Required(),
		mcp.Description("Name of the metric to get type information for (required). "+
			"Examples: `service_sla`, `service_percentile`, `endpoint_cpm`")),
)

var ProcessesTopologyTool = NewTool(
	"query_processes_topology",
	`Query the process topology for a given service instance from SkyWalking OAP (getProcessTopology).

Returns the topology of processes running within the given service instance, including process nodes and the calls between them.

Examples:
- {"service_instance_id": "instance-id-1"}: Process topology for the last 30 minutes
- {"service_instance_id": "instance-id-1", "start": "-1h"}: Process topology for the last hour`,
	queryProcessesTopology,
	mcp.WithString("service_instance_id",
		mcp.Required(),
		mcp.Description("The ID of the service instance to query process topology for.")),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive step sizing.")),
)

var ServicesTopologyTool = NewTool(
	"query_services_topology",
	`Query the service topology from SkyWalking OAP.

- If service_ids is provided, returns the topology scoped to those specific services (getServicesTopology).
- Otherwise, returns the global topology across all services (getGlobalTopology), optionally filtered by layer.

Examples:
- {}: Global topology for the last 30 minutes
- {"layer": "GENERAL"}: Global topology for a specific layer
- {"service_ids": ["svc-id-1", "svc-id-2"], "start": "-1h"}: Topology for specific services`,
	queryServicesTopology,
	mcp.WithArray("service_ids",
		mcp.Description("List of service IDs to scope the topology. If empty, the global topology is returned."),
		mcp.WithStringItems(),
	),
	mcp.WithString("layer",
		mcp.Description("Layer to filter the global topology (e.g. GENERAL, MESH). Only used when service_ids is empty.")),
	mcp.WithString("start", mcp.Description("Start time for the query.")),
	mcp.WithString("end", mcp.Description("End time for the query. Default is now.")),
	mcp.WithString("step", mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive step sizing.")),
)

var TracesQueryTool = NewTool(
	"query_traces",
	`This tool queries traces from SkyWalking OAP based on various conditions and provides intelligent data processing for LLM analysis.

Workflow:
1. Use this tool when you need to find traces matching specific criteria
2. Specify one or more query conditions to narrow down results
3. Use start/end to limit the time range for the search
4. Choose the appropriate view for your analysis needs

Query Conditions:
- service_id: Filter by specific service
- service_instance_id: Filter by specific service instance
- trace_id: Search for a specific trace ID
- endpoint_id: Filter by specific endpoint
- start/end: Time range for the query (e.g., start "-1h", end "now")
- min_trace_duration/max_trace_duration: Filter by trace duration in milliseconds
- trace_state: Filter by trace state (success, error, all)
- query_order: Sort order (start_time, duration, start_time_desc, duration_desc)
- view: Data presentation format (summary, errors_only, full)
- slow_trace_threshold: Optional threshold for identifying slow traces in milliseconds
- tags: Filter by span tags (key-value pairs)

Important Notes:
- SkyWalking OAP requires either a time range or 'trace_id' to be specified
- If no time range and no trace_id are provided, a default duration of "1h" (last 1 hour) will be used
- This ensures the query always has a valid time range or specific trace to search

View Options:
- 'full': (Default) Complete raw data for detailed analysis
- 'summary': Intelligent summary with performance metrics and insights
- 'errors_only': Focused list of error traces for troubleshooting

Best Practices:
- Start with 'summary' view to get an intelligent overview
- Use 'errors_only' view for focused troubleshooting
- Combine multiple filters for precise results
- Use time ranges to limit search scope and improve performance
- Only set slow_trace_threshold when you need to identify performance issues
- Use tags to filter traces by specific attributes or metadata

Examples:
- {"service_id": "Your_ApplicationName", "start": "-1h", "end": "now", "view": "summary"}: Recent traces summary with performance insights
- {"trace_state": "error", "start": "-7d", "end": "now", "view": "errors_only"}: Error traces from last week for troubleshooting
- {"min_trace_duration": 1000, "query_order": "duration_desc", "view": "summary"}: Slow traces analysis with performance metrics
- {"slow_trace_threshold": 5000, "view": "summary"}: Identify traces slower than 5 seconds
- {"service_id": "Your_ApplicationName"}: Query with default 1-hour duration
- {"tags": [{"key": "http.method", "value": "POST"}, {"key": "http.status_code", "value": "500"}], 
	"start": "-1h", "end": "now"}: Find traces with specific HTTP tags`,
	searchTraces,
	mcp.WithTitleAnnotation("Query traces with intelligent analysis"),
	mcp.WithString("service_id",
		mcp.Description("Service ID to filter traces. Use this to find traces from a specific service."),
	),
	mcp.WithString("service_instance_id",
		mcp.Description("Service instance ID to filter traces. Use this to find traces from a specific instance."),
	),
	mcp.WithString("trace_id",
		mcp.Description("Specific trace ID to search for. Use this when you know the exact trace ID."),
	),
	mcp.WithString("endpoint_id",
		mcp.Description("Endpoint ID to filter traces. Use this to find traces for a specific endpoint."),
	),
	mcp.WithString("start",
		mcp.Description("Start time for the query. Examples: \"2023-01-01 12:00:00\", \"-1h\" (1 hour ago), \"-30m\" (30 minutes ago)"),
	),
	mcp.WithString("end",
		mcp.Description("End time for the query. Examples: \"2023-01-01 13:00:00\", \"now\","+
			" \"-10m\" (10 minutes ago) Defaults to current time if omitted."),
	),
	mcp.WithString("step",
		mcp.Enum("SECOND", "MINUTE", "HOUR", "DAY"),
		mcp.Description("Time step granularity. If not specified, uses adaptive sizing."),
	),
	mcp.WithNumber("min_trace_duration",
		mcp.Description("Minimum trace duration in milliseconds. Use this to filter out fast traces."),
	),
	mcp.WithNumber("max_trace_duration",
		mcp.Description("Maximum trace duration in milliseconds. Use this to filter out slow traces."),
	),
	mcp.WithString("trace_state",
		mcp.Enum(TraceStateSuccess, TraceStateError, TraceStateAll),
		mcp.Description(`Filter traces by their state:
- 'success': Only successful traces
- 'error': Only traces with errors
- 'all': All traces (default)`),
	),
	mcp.WithString("query_order",
		mcp.Enum(QueryOrderStartTime, QueryOrderDuration),
		mcp.Description(`Sort order for results:
- 'start_time': Oldest first
- 'duration': Shortest first`),
	),
	mcp.WithString("view",
		mcp.Enum(ViewSummary, ViewErrorsOnly, ViewFull),
		mcp.Description(`Data presentation format:
- 'full': (Default) Complete raw data for detailed analysis
- 'summary': Intelligent summary with performance metrics and insights
- 'errors_only': Focused list of error traces for troubleshooting`),
	),
	mcp.WithNumber("slow_trace_threshold",
		mcp.Description("Optional threshold for identifying slow traces in milliseconds. "+
			"Only when this parameter is set will slow traces be included in the summary. "+
			"Traces with duration exceeding this threshold will be listed in slow_traces. "+
			"Examples: 500 (0.5s), 2000 (2s), 5000 (5s)"),
	),
	mcp.WithArray("tags",
		mcp.Description(`Array of span tags to filter traces. Each tag should have 'key' and 'value' fields.
Examples: [{"key": "http.method", "value": "POST"}, {"key": "http.status_code", "value": "500"}]`),
		mcp.Items(map[string]any{
			"type": "object",
			"properties": map[string]any{
				"key":   map[string]any{"type": "string"},
				"value": map[string]any{"type": "string"},
			},
			"required": []string{"key", "value"},
		}),
	),
	mcp.WithBoolean("cold",
		mcp.Description("Whether to query from cold-stage storage. Set to true for historical data queries."),
	),
)