docs: clarify UTC default for naive timestamps via server instructions (#755)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sd2k

cmd/mcp-grafana/main.go

@@ -213,6 +213,8 @@ Available Capabilities:
 - Rendering: Export dashboard panels or full dashboards as PNG images (requires Grafana Image Renderer plugin).
 - Proxied Tools: Access tools from external MCP servers (like Tempo) through dynamic discovery.
 
+Timestamp parameters without a timezone offset are interpreted as UTC. Include an offset like '-05:00' or use relative syntax like 'now-1h' to query in a different timezone.
+
 Note that some of these capabilities may be disabled. Do not try to use features that are not available via tools.
 `),
 		server.WithHooks(hooks),

tools/time_helpers.go

@@ -1,11 +1,20 @@
 package tools
 
 import (
+	"fmt"
 	"time"
 
 	"github.com/grafana/grafana-plugin-sdk-go/backend/gtime"
 )
 
+// timeParamHint returns the canonical phrase appended to time-parameter parse
+// errors. It warns callers that naive timestamps (no timezone offset) are
+// interpreted as UTC by the server, and suggests including an explicit offset
+// like '-05:00' or using the relative 'now-Xh' syntax accepted by gtime.
+func timeParamHint() string {
+	return "Timestamps without a timezone offset are interpreted as UTC; include an offset like '-05:00' or use relative syntax like 'now-1h'"
+}
+
 // parseStartTime parses start time strings in various formats.
 // Supports: "now", "now-Xs/m/h/d/w", RFC3339, ISO dates, and Unix timestamps.
 func parseStartTime(timeStr string) (time.Time, error) {
@@ -17,7 +26,11 @@ func parseStartTime(timeStr string) (time.Time, error) {
 		From: timeStr,
 		Now:  time.Now(),
 	}
-	return tr.ParseFrom()
+	t, err := tr.ParseFrom()
+	if err != nil {
+		return time.Time{}, fmt.Errorf("%w. %s", err, timeParamHint())
+	}
+	return t, nil
 }
 
 // parseEndTime parses end time strings in various formats.
@@ -31,5 +44,9 @@ func parseEndTime(timeStr string) (time.Time, error) {
 		To:  timeStr,
 		Now: time.Now(),
 	}
-	return tr.ParseTo()
+	t, err := tr.ParseTo()
+	if err != nil {
+		return time.Time{}, fmt.Errorf("%w. %s", err, timeParamHint())
+	}
+	return t, nil
 }