feat: add more annotations to tools (#132)

* feat: add title annotations to all tools

This commit adds the ability to customise tools using `mcp.ToolOption`s,
then updates all calls to `MustTool` to include a title annotation,
which can be displayed in any UIs instead of the non-human-friendly
name.

Co-authored-by: Luccas Quadros <[email protected]>

* feat: add more annotations to tools

Add the read-only, idempotent, and destructive hint annotations to tools
where appropriate.

Co-authored-by: Luccas Quadros <[email protected]>

---------

Co-authored-by: Luccas Quadros <[email protected]>

Author: sd2k

tools/alerting.go

@@ -150,6 +150,8 @@ var ListAlertRules = mcpgrafana.MustTool(
 	"Lists Grafana alert rules, returning a summary including UID, title, current state (e.g., 'pending', 'firing', 'inactive'), and labels. Supports filtering by labels using selectors and pagination. Example label selector: `[{'name': 'severity', 'type': '=', 'value': 'critical'}]`. Inactive state means the alert state is normal, not firing",
 	listAlertRules,
 	mcp.WithTitleAnnotation("List alert rules"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type GetAlertRuleByUIDParams struct {
@@ -182,6 +184,8 @@ var GetAlertRuleByUID = mcpgrafana.MustTool(
 	"Retrieves the full configuration and detailed status of a specific Grafana alert rule identified by its unique ID (UID). The response includes fields like title, condition, query data, folder UID, rule group, state settings (no data, error), evaluation interval, annotations, and labels.",
 	getAlertRuleByUID,
 	mcp.WithTitleAnnotation("Get alert rule details"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type ListContactPointsParams struct {
@@ -256,6 +260,8 @@ var ListContactPoints = mcpgrafana.MustTool(
 	"Lists Grafana notification contact points, returning a summary including UID, name, and type for each. Supports filtering by name - exact match - and limiting the number of results.",
 	listContactPoints,
 	mcp.WithTitleAnnotation("List notification contact points"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddAlertingTools(mcp *server.MCPServer) {

tools/asserts.go

@@ -136,6 +136,8 @@ var GetAssertions = mcpgrafana.MustTool(
 	"Get assertion summary for a given entity with its type, name, env, site, namespace, and a time range",
 	getAssertions,
 	mcp.WithTitleAnnotation("Get assertions summary"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddAssertsTools(mcp *server.MCPServer) {

tools/dashboard.go

@@ -56,13 +56,16 @@ var GetDashboardByUID = mcpgrafana.MustTool(
 	"Retrieves the complete dashboard, including panels, variables, and settings, for a specific dashboard identified by its UID.",
 	getDashboardByUID,
 	mcp.WithTitleAnnotation("Get dashboard details"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 var UpdateDashboard = mcpgrafana.MustTool(
 	"update_dashboard",
 	"Create or update a dashboard",
 	updateDashboard,
 	mcp.WithTitleAnnotation("Create or update dashboard"),
+	mcp.WithDestructiveHintAnnotation(true),
 )
 
 type DashboardPanelQueriesParams struct {
@@ -144,6 +147,8 @@ var GetDashboardPanelQueries = mcpgrafana.MustTool(
 	"Get the title, query string, and datasource information for each panel in a dashboard. The datasource is an object with fields `uid` (which may be a concrete UID or a template variable like \"$datasource\") and `type`. If the datasource UID is a template variable, it won't be usable directly for queries. Returns an array of objects, each representing a panel, with fields: title, query, and datasource (an object with uid and type).",
 	GetDashboardPanelQueriesTool,
 	mcp.WithTitleAnnotation("Get dashboard panel queries"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddDashboardTools(mcp *server.MCPServer) {

tools/datasources.go

@@ -69,6 +69,8 @@ var ListDatasources = mcpgrafana.MustTool(
 	"List available Grafana datasources. Optionally filter by datasource type (e.g., 'prometheus', 'loki'). Returns a summary list including ID, UID, name, type, and default status.",
 	listDatasources,
 	mcp.WithTitleAnnotation("List datasources"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type GetDatasourceByUIDParams struct {
@@ -93,6 +95,8 @@ var GetDatasourceByUID = mcpgrafana.MustTool(
 	"Retrieves detailed information about a specific datasource using its UID. Returns the full datasource model, including name, type, URL, access settings, JSON data, and secure JSON field status.",
 	getDatasourceByUID,
 	mcp.WithTitleAnnotation("Get datasource by UID"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type GetDatasourceByNameParams struct {
@@ -113,6 +117,8 @@ var GetDatasourceByName = mcpgrafana.MustTool(
 	"Retrieves detailed information about a specific datasource using its name. Returns the full datasource model, including UID, type, URL, access settings, JSON data, and secure JSON field status.",
 	getDatasourceByName,
 	mcp.WithTitleAnnotation("Get datasource by name"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddDatasourceTools(mcp *server.MCPServer) {

tools/incident.go

@@ -51,6 +51,8 @@ var ListIncidents = mcpgrafana.MustTool(
 	"List Grafana incidents. Allows filtering by status ('active', 'resolved') and optionally including drill incidents. Returns a preview list with basic details.",
 	listIncidents,
 	mcp.WithTitleAnnotation("List incidents"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type CreateIncidentParams struct {
@@ -148,4 +150,6 @@ var GetIncident = mcpgrafana.MustTool(
 	"Get a single incident by ID. Returns the full incident details including title, status, severity, labels, timestamps, and other metadata.",
 	getIncident,
 	mcp.WithTitleAnnotation("Get incident details"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )

tools/loki.go

@@ -224,6 +224,8 @@ var ListLokiLabelNames = mcpgrafana.MustTool(
 	"Lists all available label names (keys) found in logs within a specified Loki datasource and time range. Returns a list of unique label strings (e.g., `[\"app\", \"env\", \"pod\"]`). If the time range is not provided, it defaults to the last hour.",
 	listLokiLabelNames,
 	mcp.WithTitleAnnotation("List Loki label names"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // ListLokiLabelValuesParams defines the parameters for listing Loki label values
@@ -263,6 +265,8 @@ var ListLokiLabelValues = mcpgrafana.MustTool(
 	"Retrieves all unique values associated with a specific `labelName` within a Loki datasource and time range. Returns a list of string values (e.g., for `labelName=\"env\"`, might return `[\"prod\", \"staging\", \"dev\"]`). Useful for discovering filter options. Defaults to the last hour if the time range is omitted.",
 	listLokiLabelValues,
 	mcp.WithTitleAnnotation("List Loki label values"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // LogStream represents a stream of log entries from Loki
@@ -471,6 +475,8 @@ var QueryLokiLogs = mcpgrafana.MustTool(
 	"Executes a LogQL query against a Loki datasource to retrieve log entries or metric values. Returns a list of results, each containing a timestamp, labels, and either a log line (`line`) or a numeric metric value (`value`). Defaults to the last hour, a limit of 10 entries, and 'backward' direction (newest first). Supports full LogQL syntax for log and metric queries (e.g., `{app=\"foo\"} |= \"error\"`, `rate({app=\"bar\"}[1m])`). Prefer using `query_loki_stats` first to check stream size and `list_loki_label_names` and `list_loki_label_values` to verify labels exist.",
 	queryLokiLogs,
 	mcp.WithTitleAnnotation("Query Loki logs"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // fetchStats is a method to fetch stats data from Loki API
@@ -529,6 +535,8 @@ var QueryLokiStats = mcpgrafana.MustTool(
 	"Retrieves statistics about log streams matching a given LogQL *selector* within a Loki datasource and time range. Returns an object containing the count of streams, chunks, entries, and total bytes (e.g., `{\"streams\": 5, \"chunks\": 50, \"entries\": 10000, \"bytes\": 512000}`). The `logql` parameter **must** be a simple label selector (e.g., `{app=\"nginx\", env=\"prod\"}`) and does not support line filters, parsers, or aggregations. Defaults to the last hour if the time range is omitted.",
 	queryLokiStats,
 	mcp.WithTitleAnnotation("Get Loki log statistics"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // AddLokiTools registers all Loki tools with the MCP server

tools/oncall.go

@@ -194,6 +194,8 @@ var ListOnCallSchedules = mcpgrafana.MustTool(
 	"List Grafana OnCall schedules, optionally filtering by team ID. If a specific schedule ID is provided, retrieves details for only that schedule. Returns a list of schedule summaries including ID, name, team ID, timezone, and shift IDs. Supports pagination.",
 	listOnCallSchedules,
 	mcp.WithTitleAnnotation("List OnCall schedules"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type GetOnCallShiftParams struct {
@@ -219,6 +221,8 @@ var GetOnCallShift = mcpgrafana.MustTool(
 	"Get detailed information for a specific Grafana OnCall shift using its ID. A shift represents a designated time period within a schedule when users are actively on-call. Returns the full shift details.",
 	getOnCallShift,
 	mcp.WithTitleAnnotation("Get OnCall shift"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // CurrentOnCallUsers represents the currently on-call users for a schedule
@@ -280,6 +284,8 @@ var GetCurrentOnCallUsers = mcpgrafana.MustTool(
 	"Get the list of users currently on-call for a specific Grafana OnCall schedule ID. Returns the schedule ID, name, and a list of detailed user objects for those currently on call.",
 	getCurrentOnCallUsers,
 	mcp.WithTitleAnnotation("Get current on-call users"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type ListOnCallTeamsParams struct {
@@ -310,6 +316,8 @@ var ListOnCallTeams = mcpgrafana.MustTool(
 	"List teams configured in Grafana OnCall. Returns a list of team objects with their details. Supports pagination.",
 	listOnCallTeams,
 	mcp.WithTitleAnnotation("List OnCall teams"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type ListOnCallUsersParams struct {
@@ -354,6 +362,8 @@ var ListOnCallUsers = mcpgrafana.MustTool(
 	"List users from Grafana OnCall. Can retrieve all users, a specific user by ID, or filter by username. Returns a list of user objects with their details. Supports pagination.",
 	listOnCallUsers,
 	mcp.WithTitleAnnotation("List OnCall users"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddOnCallTools(mcp *server.MCPServer) {

tools/prometheus.go

@@ -98,6 +98,8 @@ var ListPrometheusMetricMetadata = mcpgrafana.MustTool(
 	"List Prometheus metric metadata. Returns metadata about metrics currently scraped from targets. Note: This endpoint is experimental.",
 	listPrometheusMetricMetadata,
 	mcp.WithTitleAnnotation("List Prometheus metric metadata"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type QueryPrometheusParams struct {
@@ -161,6 +163,8 @@ var QueryPrometheus = mcpgrafana.MustTool(
 	"Query Prometheus using a PromQL expression. Supports both instant queries (at a single point in time) and range queries (over a time range).",
 	queryPrometheus,
 	mcp.WithTitleAnnotation("Query Prometheus metrics"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type ListPrometheusMetricNamesParams struct {
@@ -229,6 +233,8 @@ var ListPrometheusMetricNames = mcpgrafana.MustTool(
 	"List metric names in a Prometheus datasource. Retrieves all metric names and then filters them locally using the provided regex. Supports pagination.",
 	listPrometheusMetricNames,
 	mcp.WithTitleAnnotation("List Prometheus metric names"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type LabelMatcher struct {
@@ -332,6 +338,8 @@ var ListPrometheusLabelNames = mcpgrafana.MustTool(
 	"List label names in a Prometheus datasource. Allows filtering by series selectors and time range.",
 	listPrometheusLabelNames,
 	mcp.WithTitleAnnotation("List Prometheus label names"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 type ListPrometheusLabelValuesParams struct {
@@ -389,6 +397,8 @@ var ListPrometheusLabelValues = mcpgrafana.MustTool(
 	"Get the values for a specific label name in Prometheus. Allows filtering by series selectors and time range.",
 	listPrometheusLabelValues,
 	mcp.WithTitleAnnotation("List Prometheus label values"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddPrometheusTools(mcp *server.MCPServer) {

tools/search.go

@@ -37,6 +37,8 @@ var SearchDashboards = mcpgrafana.MustTool(
 	"Search for Grafana dashboards by a query string. Returns a list of matching dashboards with details like title, UID, folder, tags, and URL.",
 	searchDashboards,
 	mcp.WithTitleAnnotation("Search dashboards"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 func AddSearchTools(mcp *server.MCPServer) {

tools/sift.go

@@ -178,6 +178,8 @@ var GetSiftInvestigation = mcpgrafana.MustTool(
 	"Retrieves an existing Sift investigation by its UUID. The ID should be provided as a string in UUID format (e.g. '02adab7c-bf5b-45f2-9459-d71a2c29e11b').",
 	getSiftInvestigation,
 	mcp.WithTitleAnnotation("Get Sift investigation"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // GetSiftAnalysisParams defines the parameters for retrieving a specific analysis
@@ -218,6 +220,8 @@ var GetSiftAnalysis = mcpgrafana.MustTool(
 	"Retrieves a specific analysis from an investigation by its UUID. The investigation ID and analysis ID should be provided as strings in UUID format.",
 	getSiftAnalysis,
 	mcp.WithTitleAnnotation("Get Sift analysis"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // ListSiftInvestigationsParams defines the parameters for retrieving investigations
@@ -251,6 +255,8 @@ var ListSiftInvestigations = mcpgrafana.MustTool(
 	"Retrieves a list of Sift investigations with an optional limit. If no limit is specified, defaults to 10 investigations.",
 	listSiftInvestigations,
 	mcp.WithTitleAnnotation("List Sift investigations"),
+	mcp.WithIdempotentHintAnnotation(true),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // FindErrorPatternLogsParams defines the parameters for running an ErrorPatternLogs check
@@ -336,6 +342,7 @@ var FindErrorPatternLogs = mcpgrafana.MustTool(
 	"Searches Loki logs for elevated error patterns compared to the last day's average, waits for the analysis to complete, and returns the results including any patterns found.",
 	findErrorPatternLogs,
 	mcp.WithTitleAnnotation("Find error patterns in logs"),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // FindSlowRequestsParams defines the parameters for running an SlowRequests check
@@ -401,6 +408,7 @@ var FindSlowRequests = mcpgrafana.MustTool(
 	"Searches relevant Tempo datasources for slow requests, waits for the analysis to complete, and returns the results.",
 	findSlowRequests,
 	mcp.WithTitleAnnotation("Find slow requests"),
+	mcp.WithReadOnlyHintAnnotation(true),
 )
 
 // AddSiftTools registers all Sift tools with the MCP server