Improve tool descriptions for LLM (#21)

* Descriptions for how to use get logs, traces, metric done

* Improve the descriptions for tools

* Argument descriptions for log and K8s event endpoints are done

* Add descriptions for node and metric arguments

* Argument descriptions for trace and k8s endpoints

main.go

@@ -19,132 +19,157 @@ type MetoroTools struct {
 var metoroTools = []MetoroTools{
 	{
 		Name:        "get_environments",
-		Description: "Get Kubernetes environments/clusters, monitored by Metoro",
+		Description: "Get Kubernetes environments/clusters",
 		Handler:     tools.GetEnvironmentsHandler,
 	},
 	{
 		Name:        "get_services",
-		Description: "Get services running in your Kubernetes cluster, monitored by Metoro",
+		Description: "Get services running in your Kubernetes cluster. Metoro treats the following Kubernetes resources as a 'service': Deployment, StatefulSet, DaemonSet",
 		Handler:     tools.GetServicesHandler,
 	},
 	{
 		Name:        "get_namespaces",
-		Description: "Get namespaces in your Kubernetes cluster, monitored by Metoro",
+		Description: "Get namespaces in your Kubernetes cluster",
 		Handler:     tools.GetNamespacesHandler,
 	},
 	{
-		Name:        "get_logs",
-		Description: "Get logs from all/any services/hosts/pods running in your Kubernetes cluster. Results are limited to 100 logs lines",
-		Handler:     tools.GetLogsHandler,
+		Name: "get_logs",
+		Description: `Get logs from all or specific services/hosts/pods running in your Kubernetes cluster. Results are limited to 100 logs lines. How to use this tool:
+                      First, use get_log_attributes tool to retrieve the available log attribute keys which can be used as Filter or ExcludeFilter keys for this tool.
+                      Then use get_log_attribute_values_for_individual_attribute tool to get the possible values a log attribute key can be used for filtering logs.
+                      Then you can use this tool (get_logs) to get the specific logs you are looking for.
+                      e.g. Filter use case: get_logs with filters: {key: [value]} for including specific logs. Where the key was retrieved from get_log_attributes tool and the value was retrieved from get_log_attribute_values_for_individual_attribute tool. Multiple values for a key are ORed together.
+                      If you want to filter log messages with a specific substring, you can use Regexes or ExcludeRegexes argument.`,
+		Handler: tools.GetLogsHandler,
 	},
 	{
-		Name:        "get_traces",
-		Description: "Get traces from services running in your Kubernetes cluster in the last 5 minutes, monitored by Metoro",
-		Handler:     tools.GetTracesHandler,
+		Name: "get_traces",
+		Description: `Get traces from all or specific services/hosts/pods running in your Kubernetes cluster. Results are limited to 100 traces. How to use this tool:
+					  First, use get_trace_attributes tool to retrieve the available trace attribute keys which can be used as Filter/ExcludeFilter keys.
+                      Then use get_trace_attribute_values_for_individual_attribute tool to get the possible values a trace attribute key can be for filtering traces.
+                      Then you can use this tool (get_traces) to get the specific traces you are looking for. 
+                      e.g. Filter use case: get_traces with filters: {key: [value]} for including specific traces. Where key was retrieved from get_trace_attributes tool and value was retrieved from get_trace_attribute_values_for_individual_attribute tool. Multiple values for a key are ORed together. 
+					  Regexes and ExcludeRegexes arguments can be used to filter traces endpoints that match the given regexes.`,
+		Handler: tools.GetTracesHandler,
 	},
 	{
-		Name:        "get_metric",
-		Description: "Get metrics from your Kubernetes cluster, monitored by Metoro",
-		Handler:     tools.GetMetricHandler,
+		Name: "get_metric",
+		Description: `Get a specific metric's timeseries data. How to use this tool: 
+                      First, use get_metric_names tool to retrieve the available metric names which can be used as MetricName argument for this tool.
+                      Then use get_metric_attributes tool to retrieve the available attribute keys and values for a specific MetricName which can be used as Filter/ExcludeFilter keys for this tool.
+                      You can also use Splits argument to group the metric data by the given metric attribute keys.`,
+		Handler: tools.GetMetricHandler,
 	},
 	{
-		Name:        "get_trace_metric",
-		Description: "Get trace metrics from your Kubernetes cluster, monitored by Metoro",
-		Handler:     tools.GetTraceMetricHandler,
+		Name: "get_trace_metric",
+		Description: `Get trace data as timeseries. E.g. if you want to see request count, errors, duration/latencies (RED metrics) use this tool to get back the timeseries data. How to use this tool:
+                      First, use get_trace_attributes tool to retrieve the available trace attribute keys which can be used as Filter/ExcludeFilter keys for this tool or the Splits argument to group the data by the given trace attribute keys.
+                      Then use get_trace_attribute_values_for_individual_attribute tool to get the possible values a trace attribute key can be for filtering traces.
+                      Then use get_trace_metric tool to get the timeseries data for the given trace attribute keys and values that you are interested in.`,
+		Handler: tools.GetTraceMetricHandler,
 	},
 	{
 		Name:        "get_trace_attributes",
-		Description: "Get trace attributes from your Kubernetes cluster",
+		Description: "Get the possible trace attribute keys which can be used as Filter/ExcludeFilter keys or Splits for get_traces, get_trace_metric and get_trace_attribute_values_for_individual_attribute tools arguments",
 		Handler:     tools.GetTraceAttributesHandler,
 	},
 	{
 		Name:        "get_trace_attribute_values_for_individual_attribute",
-		Description: "Get trace attribute values for a specific attribute",
+		Description: "Get trace the possible values a trace attribute key can be used as a value for filtering traces",
 		Handler:     tools.GetTraceAttributeValuesForIndividualAttributeHandler,
 	},
 	{
 		Name:        "get_profiles",
-		Description: "Get profiles from your Kubernetes cluster",
+		Description: "Get profiles of your services running in your Kubernetes cluster. This tool is useful for answering performance related questions for a specific service. It provides information about which functions taking time in the service.",
 		Handler:     tools.GetProfilesHandler,
 	},
 	{
-		Name:        "get_k8s_events",
-		Description: "Get Kubernetes events from your clusters with filtering options",
-		Handler:     tools.GetK8sEventsHandler,
+		Name: "get_k8s_events",
+		Description: `Get the Kubernetes events from your clusters. Kubernetes events are useful for understanding what is happening in your cluster. 
+                      They are emitted by the Kubernetes API server when there is a change in the state of the cluster. How to use this tool:
+                      First, use get_k8s_events_attributes tool to retrieve the available Kubernetes event attribute keys which can be used as Filter/ExcludeFilter keys for this tool.
+                      Then use get_k8s_event_attribute_values_for_individual_attribute tool to get the possible values a Kubernetes event attribute key can be for filtering Kubernetes events.
+                      And then you can call this tool (get_k8s_events) to get the specific events you are looking for. e.g. Filter use case: get_k8s_events with filters: {key: [value]} for including specific Kubernetes events. Where key was retrieved from get_k8s_events_attributes tool and value was retrieved from get_k8s_event_attribute_values_for_individual_attribute tool. Multiple values for a key are ORed together.`,
+		Handler: tools.GetK8sEventsHandler,
 	},
 	{
 		Name:        "get_k8s_events_attributes",
-		Description: "Get Kubernetes events attributes",
+		Description: "Get possible attribute keys for Kubernetes events which can be used for filtering them.",
 		Handler:     tools.GetK8sEventsAttributesHandler,
 	},
 	{
 		Name:        "get_k8s_event_attribute_values_for_individual_attribute",
-		Description: "Get Kubernetes event attribute values for a specific attribute",
+		Description: "Get possible attribute values for a specific Kubernetes event attribute key. E.g. EventType attribute key might have values like Normal, Warning, etc.",
 		Handler:     tools.GetK8sEventAttributeValuesForIndividualAttributeHandler,
 	},
 	{
 		Name:        "get_k8s_events_volume",
-		Description: "Get Kubernetes events volume",
+		Description: "Get the timeseries data for the number of Kubernetes events in your cluster, whether its filtered by a specific attribute or not. The volume of events are split by EventType so you can see the breakdown of Warning/Normal events.",
 		Handler:     tools.GetK8sEventsVolumeHandler,
 	},
 	{
-		Name:        "get_metricAttributes",
-		Description: "Get metric attributes",
+		Name:        "get_metric_attributes",
+		Description: "Get possible attribute keys and values for a metric which can be used for filtering them.",
 		Handler:     tools.GetMetricAttributesHandler,
 	},
 	{
 		Name:        "get_metric_names",
-		Description: "Get metric names",
+		Description: "Get available metric names to query. These metric names can be used as MetricName argument for get_metric, get_metric_metadata and get_metric_attributes tools.",
 		Handler:     tools.GetMetricNamesHandler,
 	},
 	{
 		Name:        "get_metric_metadata",
-		Description: "Get metric metadata",
+		Description: "Get metric metadata tool can be used to get detailed information about a metric including its type, unit and description.",
 		Handler:     tools.GetMetricMetadata,
 	},
 	{
 		Name:        "get_pods",
-		Description: "Get pods information from your Kubernetes cluster",
+		Description: "Get the pods that are running in your cluster. You must provide either a ServiceName to get pods for a specific service or a NodeName to get pods running on a specific node.",
 		Handler:     tools.GetPodsHandler,
 	},
 	{
 		Name:        "get_k8s_service_information",
-		Description: "Get detailed information about a Kubernetes service including its type (Deployment, DaemonSet, etc.), YAML configuration, and current running replicas (excluding HPA)",
+		Description: "Get detailed information including the YAML of a Kubernetes service. This tool is useful for understanding the configuration of a service.",
 		Handler:     tools.GetK8sServiceInformationHandler,
 	},
 	{
 		Name:        "get_log_attributes",
-		Description: "Get log attributes",
+		Description: "Get possible log attribute keys which can be used for filtering logs.",
 		Handler:     tools.GetLogAttributesHandler,
 	},
 	{
 		Name:        "get_log_attribute_values_for_individual_attribute",
-		Description: "Get log attribute values for a specific attribute",
+		Description: "Get possible values for a specific log attribute key which can be used for filtering logs.",
 		Handler:     tools.GetLogAttributeValuesForIndividualAttributeHandler,
 	},
 	{
 		Name:        "get_nodes",
-		Description: "Get nodes information from your Kubernetes cluster",
+		Description: "Get the nodes that are running in your cluster. To use this tool, first call get_node_attributes to get the possible node attribute keys and values which can be used for filtering nodes.",
 		Handler:     tools.GetNodesHandler,
 	},
+	{
+		Name:        "get_node_attributes",
+		Description: "Get possible node attribute keys and values which can be used for filtering nodes.",
+		Handler:     tools.GetNodeAttributesHandler,
+	},
 	{
 		Name:        "get_node_info",
-		Description: "Get detailed node information from your Kubernetes cluster",
+		Description: "Get detailed node information about a specific node. This tool provides information about the node's capacity, allocatable resources, and usage, yaml, node type, OS and Kernel information.",
 		Handler:     tools.GetNodeInfoHandler,
 	},
 	{
 		Name:        "get_service_summaries",
-		Description: "Get service summaries from your Kubernetes cluster",
+		Description: "Get summaries of services/workloads running in your Kubernetes cluster. The summary includes the number of requests, errors (5xx and 4xx), P50, p95, p99 latencies. This tool is useful for understanding the performance of your services at a high level for a given relative or abosulute time range.",
 		Handler:     tools.GetServiceSummariesHandler,
 	},
 	{
 		Name:        "get_alerts",
-		Description: "Get alerts from your Kubernetes cluster",
+		Description: "Get list of alerts from your Kubernetes cluster. These alerts are configured by the user in Metoro therefore it may not have full coverage for all the issues that might occur in the cluster.",
 		Handler:     tools.GetAlertsHandler,
 	},
 	{
 		Name:        "get_alert_fires",
-		Description: "Get alert fires from your Kubernetes cluster",
+		Description: "Get list of alert fires from your Kubernetes cluster. Alert fires are the instances when an alert is triggered. This tool provides information about the alert name, the time it was triggered, the time it recovered, the environment, and the service name (if available) and the alert trigger message.",
 		Handler:     tools.GetAlertFiresHandler,
 	},
 }
@@ -196,7 +221,7 @@ var metoroResources = []MetoroResource{
 	{
 		Path:        "api://metrics",
 		Name:        "metricNames",
-		Description: "Provides a list of available metric names that can be used for as MetricName arguments to get_metric, get_metric_metadata and get_metricAttributes tools to get metrics data.",
+		Description: "Provides a list of available metric names that can be used for as MetricName arguments to get_metric, get_metric_metadata and get_metric_attributes tools to get metrics data.",
 		ContentType: "text/plain",
 		Handler:     resources.MetricsResourceHandler,
 	},

model/model.go

@@ -62,15 +62,15 @@ const (
 type MetricFunction struct {
 	ID string `json:"id"`
 	// The type of the function
-	FunctionType FunctionType `json:"functionType"`
+	FunctionType FunctionType `json:"functionType" jsonschema:"required,description=The type of the function to apply to the metric possible values are monotonicDifference / valueDifference / customMathExpression"`
 	// The payload of the function
 	// TODO: If we have more payloads this can be an interface but for now its a math expression since its the only payload.
-	FunctionPayload MathExpression `json:"functionPayload"`
+	FunctionPayload MathExpression `json:"functionPayload" jsonschema:"description=The payload of the customMathExpression. this is only set for customMathExpression. "`
 }
 
 type MathExpression struct {
-	Variables  []string `json:"variables"`
-	Expression string   `json:"expression"`
+	Variables  []string `json:"variables" jsonschema:"description=The variables to use in the math expression. For now this should always be ['a'] if set"`
+	Expression string   `json:"expression" jsonschema:"description=The math expression to apply to the metric. For example if you want to divide the metric by 60 you would set the expression as a / 60"`
 }
 
 type FunctionType string

tools/get_alert_fires.go

@@ -7,8 +7,8 @@ import (
 )
 
 type GetAlertFiresHandlerArgs struct {
-	TimeConfig utils.TimeConfig `json:"time_config" jsonschema:"required,description=The time period to get alert fires for. e.g. if you want to get fires for the last 5 minutes, you would set time_period=5 and time_window=Minutes"`
-	AlertId    string           `json:"alert_id" jsonschema:"required,description=The ID of the alert to get fires for"`
+	TimeConfig utils.TimeConfig `json:"time_config" jsonschema:"required,description=The time period to get alert fires for. e.g. if you want to get alert fires for the last 5 minutes you would set time_period=5 and time_window=Minutes. You can also set an absoulute time range by setting start_time and end_time"`
+	AlertId    string           `json:"alert_id" jsonschema:"required,description=The ID of the alert to get the alert fires for"`
 }
 
 func GetAlertFiresHandler(arguments GetAlertFiresHandlerArgs) (*mcpgolang.ToolResponse, error) {

tools/get_k8s_event_attribute_values.go

@@ -10,15 +10,14 @@ import (
 )
 
 type GetK8sEventAttributeValueHandlerArgs struct {
-	TimeConfig     utils.TimeConfig    `json:"time_config" jsonschema:"required,description=The time period to get the possible values of K8 event attributes values. e.g. if you want to see the possible values for the attributes in the last 5 minutes, you would set time_period=5 and time_window=Minutes"`
-	Attribute      string              `json:"attribute" jsonschema:"required,description=The attribute to get values for"`
-	Filters        map[string][]string `json:"filters" jsonschema:"description=The filters to apply to the events. it is a map of filter keys to array values where array values are ORed when the filters are applied.e.g. key for service name is service.name"`
-	ExcludeFilters map[string][]string `json:"excludeFilters" jsonschema:"description=The exclude filters to exclude/eliminate the events. Events matching the exclude filters will not be returned. it is a map of filter keys to array values where array values are ORed when the filters are applied.e.g. key for service name is service.name"`
-	Regexes        []string            `json:"regexes" jsonschema:"description=The regexes to apply to the event messages. Events with messages matching regexes will be returned"`
-	ExcludeRegexes []string            `json:"excludeRegexes" jsonschema:"description=The regexes to exclude from the event messages. Events with messages matching regexes will be excluded"`
+	TimeConfig     utils.TimeConfig    `json:"time_config" jsonschema:"required,description=The time period to get the possible values of K8 event attributes values. e.g. if you want to see the possible values for the attributes in the last 5 minutes you would set time_period=5 and time_window=Minutes. You can also set an absoulute time range by setting start_time and end_time"`
+	Attribute      string              `json:"attribute" jsonschema:"required,description=The attribute key to get the possible values for"`
+	Filters        map[string][]string `json:"filters" jsonschema:"description=The filters to apply before getting the possible values. For example if you want to get the possible values for attribute key service.name where the environment is X you would set the Filters as {environment: [X]}"`
+	ExcludeFilters map[string][]string `json:"excludeFilters" jsonschema:"description=The exclude filters to exclude/eliminate possible values an attribute can take. Events matching the exclude filters will not be returned. For example if you want the possible values for attribute key service.name where the attribute environment is not X then you would set the ExcludeFilters as {environment: [X]}"`
+	Regexes        []string            `json:"regexes" jsonschema:"description=The regexes to apply to the event messages. Only the attribute values (for a given attribute key) of events messages that match these regexes will be returned. For example if you want the possible values for attribute key service.name where the event message contains the word 'error' you would set the regexes as ['error']"`
+	ExcludeRegexes []string            `json:"excludeRegexes" jsonschema:"description=The exclude regexes to apply to the event messages. The attribute values (for a given attribute key) of events messages that match these regexes will not be returned. For example if you want the possible values for attribute key service.name where the event message does not contain the word 'error' you would set the exclude regexes as ['error']"`
 	Environments   []string            `json:"environments" jsonschema:"description=The environments to get events from. If empty, events from all environments will be returned"`
 	Ascending      bool                `json:"ascending" jsonschema:"description=If true, events will be returned in ascending order, otherwise in descending order"`
-	PrevEndTime    *float64            `json:"prevEndTime" jsonschema:"description=The end time of the previous request"`
 }
 
 func GetK8sEventAttributeValuesForIndividualAttributeHandler(arguments GetK8sEventAttributeValueHandlerArgs) (*mcpgolang.ToolResponse, error) {