improvement(grafana): align tools and block with official Grafana API spec

Validates and corrects the Grafana integration against the official API
docs: fixes wire-format field naming for provisioned alert rules
(missing_series_evals_to_resolve, keepFiringFor, orgID), adds
X-Disable-Provenance support, expands alert-rule params (isPaused,
notificationSettings, record, annotations, labels), corrects defaults
(execErrState=Error, dashboard overwrite=false), and centralizes alert-rule
output mapping in a shared utils module.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: waleedlatif1

apps/docs/content/docs/en/tools/grafana.mdx

@@ -2,6 +2,7 @@ import type {
   GrafanaCreateAlertRuleParams,
   GrafanaCreateAlertRuleResponse,
 } from '@/tools/grafana/types'
+import { alertRuleOutputFields, mapAlertRule } from '@/tools/grafana/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const createAlertRuleTool: ToolConfig<
@@ -52,9 +53,10 @@ export const createAlertRuleTool: ToolConfig<
     },
     condition: {
       type: 'string',
-      required: true,
+      required: false,
       visibility: 'user-or-llm',
-      description: 'The refId of the query or expression to use as the alert condition',
+      description:
+        'The refId of the query or expression to use as the alert condition (required for alerting rules; omit for recording rules)',
     },
     data: {
       type: 'string',
@@ -78,7 +80,7 @@ export const createAlertRuleTool: ToolConfig<
       type: 'string',
       required: false,
       visibility: 'user-only',
-      description: 'State on execution error (Alerting, OK)',
+      description: 'State on execution error (Error, Alerting, OK)',
     },
     annotations: {
       type: 'string',
@@ -92,6 +94,48 @@ export const createAlertRuleTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'JSON object of labels',
     },
+    uid: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional custom UID for the alert rule',
+    },
+    isPaused: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-only',
+      description: 'Whether the rule is paused on creation',
+    },
+    keepFiringFor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Duration to keep firing after the condition stops (e.g., 5m)',
+    },
+    missingSeriesEvalsToResolve: {
+      type: 'number',
+      required: false,
+      visibility: 'user-only',
+      description: 'Number of missing series evaluations before resolving',
+    },
+    notificationSettings: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'JSON object of per-rule notification settings (overrides)',
+    },
+    record: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'JSON object configuring this as a recording rule (omit for alerting rules)',
+    },
+    disableProvenance: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-only',
+      description: 'Set X-Disable-Provenance header so the rule remains editable in the Grafana UI',
+    },
   },
 
   request: {
@@ -105,25 +149,36 @@ export const createAlertRuleTool: ToolConfig<
       if (params.organizationId) {
         headers['X-Grafana-Org-Id'] = params.organizationId
       }
+      if (params.disableProvenance) {
+        headers['X-Disable-Provenance'] = 'true'
+      }
       return headers
     },
     body: (params) => {
-      let dataArray: any[] = []
+      let dataArray: unknown[] = []
       try {
         dataArray = JSON.parse(params.data)
       } catch {
         throw new Error('Invalid JSON for data parameter')
       }
 
-      const body: Record<string, any> = {
+      const body: Record<string, unknown> = {
+        orgID: params.organizationId ? Number(params.organizationId) : 1,
         title: params.title,
         folderUID: params.folderUid,
         ruleGroup: params.ruleGroup,
-        condition: params.condition,
         data: dataArray,
-        for: params.forDuration || '5m',
-        noDataState: params.noDataState || 'NoData',
-        execErrState: params.execErrState || 'Alerting',
+      }
+
+      if (params.condition) body.condition = params.condition
+      if (params.uid) body.uid = params.uid
+      if (params.forDuration) body.for = params.forDuration
+      if (params.noDataState) body.noDataState = params.noDataState
+      if (params.execErrState) body.execErrState = params.execErrState
+      if (params.isPaused !== undefined) body.isPaused = params.isPaused
+      if (params.keepFiringFor) body.keepFiringFor = params.keepFiringFor
+      if (params.missingSeriesEvalsToResolve !== undefined) {
+        body.missing_series_evals_to_resolve = params.missingSeriesEvalsToResolve
       }
 
       if (params.annotations) {
@@ -142,53 +197,30 @@ export const createAlertRuleTool: ToolConfig<
         }
       }
 
+      if (params.notificationSettings) {
+        try {
+          body.notification_settings = JSON.parse(params.notificationSettings)
+        } catch {
+          // skip invalid notification settings JSON
+        }
+      }
+
+      if (params.record) {
+        try {
+          body.record = JSON.parse(params.record)
+        } catch {
+          // skip invalid record JSON
+        }
+      }
+
       return body
     },
   },
 
   transformResponse: async (response: Response) => {
     const data = await response.json()
-
-    return {
-      success: true,
-      output: {
-        uid: data.uid,
-        title: data.title,
-        condition: data.condition,
-        data: data.data,
-        updated: data.updated,
-        noDataState: data.noDataState,
-        execErrState: data.execErrState,
-        for: data.for,
-        annotations: data.annotations || {},
-        labels: data.labels || {},
-        isPaused: data.isPaused || false,
-        folderUID: data.folderUID,
-        ruleGroup: data.ruleGroup,
-        orgId: data.orgId,
-        namespace_uid: data.namespace_uid,
-        namespace_id: data.namespace_id,
-        provenance: data.provenance || '',
-      },
-    }
+    return { success: true, output: mapAlertRule(data) }
   },
 
-  outputs: {
-    uid: {
-      type: 'string',
-      description: 'The UID of the created alert rule',
-    },
-    title: {
-      type: 'string',
-      description: 'Alert rule title',
-    },
-    folderUID: {
-      type: 'string',
-      description: 'Parent folder UID',
-    },
-    ruleGroup: {
-      type: 'string',
-      description: 'Rule group name',
-    },
-  },
+  outputs: alertRuleOutputFields,
 }

apps/sim/blocks/blocks/grafana.ts

@@ -46,9 +46,10 @@ export const createAnnotationTool: ToolConfig<
     },
     dashboardUid: {
       type: 'string',
-      required: true,
+      required: false,
       visibility: 'user-or-llm',
-      description: 'UID of the dashboard to add the annotation to (e.g., abc123def)',
+      description:
+        'UID of the dashboard to add the annotation to (e.g., abc123def). Omit to create a global organization annotation.',
     },
     panelId: {
       type: 'number',
@@ -84,30 +85,22 @@ export const createAnnotationTool: ToolConfig<
       return headers
     },
     body: (params) => {
-      const body: Record<string, any> = {
+      const body: Record<string, unknown> = {
         text: params.text,
-        time: params.time || Date.now(),
       }
 
+      if (params.time) body.time = params.time
+      if (params.timeEnd) body.timeEnd = params.timeEnd
+      if (params.dashboardUid) body.dashboardUID = params.dashboardUid
+      if (params.panelId) body.panelId = params.panelId
+
       if (params.tags) {
         body.tags = params.tags
           .split(',')
           .map((t) => t.trim())
           .filter((t) => t)
       }
 
-      if (params.dashboardUid) {
-        body.dashboardUID = params.dashboardUid
-      }
-
-      if (params.panelId) {
-        body.panelId = params.panelId
-      }
-
-      if (params.timeEnd) {
-        body.timeEnd = params.timeEnd
-      }
-
       return body
     },
   },

apps/sim/tools/grafana/create_alert_rule.ts

@@ -39,6 +39,12 @@ export const createFolderTool: ToolConfig<GrafanaCreateFolderParams, GrafanaCrea
         visibility: 'user-or-llm',
         description: 'Optional UID for the folder (auto-generated if not provided)',
       },
+      parentUid: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Parent folder UID for nested folders (requires nested folders enabled)',
+      },
     },
 
     request: {
@@ -55,13 +61,12 @@ export const createFolderTool: ToolConfig<GrafanaCreateFolderParams, GrafanaCrea
         return headers
       },
       body: (params) => {
-        const body: Record<string, any> = {
+        const body: Record<string, unknown> = {
           title: params.title,
         }
 
-        if (params.uid) {
-          body.uid = params.uid
-        }
+        if (params.uid) body.uid = params.uid
+        if (params.parentUid) body.parentUid = params.parentUid
 
         return body
       },
@@ -73,80 +78,80 @@ export const createFolderTool: ToolConfig<GrafanaCreateFolderParams, GrafanaCrea
       return {
         success: true,
         output: {
-          id: data.id,
-          uid: data.uid,
-          title: data.title,
-          url: data.url,
-          hasAcl: data.hasAcl || false,
-          canSave: data.canSave || false,
-          canEdit: data.canEdit || false,
-          canAdmin: data.canAdmin || false,
-          canDelete: data.canDelete || false,
-          createdBy: data.createdBy || '',
-          created: data.created || '',
-          updatedBy: data.updatedBy || '',
-          updated: data.updated || '',
-          version: data.version || 0,
+          id: (data.id as number) ?? null,
+          uid: (data.uid as string) ?? null,
+          title: (data.title as string) ?? null,
+          url: (data.url as string) ?? null,
+          parentUid: (data.parentUid as string) ?? null,
+          parents: (data.parents as { uid: string; title: string; url: string }[]) ?? [],
+          hasAcl: (data.hasAcl as boolean) ?? null,
+          canSave: (data.canSave as boolean) ?? null,
+          canEdit: (data.canEdit as boolean) ?? null,
+          canAdmin: (data.canAdmin as boolean) ?? null,
+          createdBy: (data.createdBy as string) ?? null,
+          created: (data.created as string) ?? null,
+          updatedBy: (data.updatedBy as string) ?? null,
+          updated: (data.updated as string) ?? null,
+          version: (data.version as number) ?? null,
         },
       }
     },
 
     outputs: {
-      id: {
-        type: 'number',
-        description: 'The numeric ID of the created folder',
-      },
-      uid: {
+      id: { type: 'number', description: 'The numeric ID of the created folder' },
+      uid: { type: 'string', description: 'The UID of the created folder' },
+      title: { type: 'string', description: 'The title of the created folder' },
+      url: { type: 'string', description: 'The URL path to the folder', optional: true },
+      parentUid: {
         type: 'string',
-        description: 'The UID of the created folder',
+        description: 'Parent folder UID (nested folders only)',
+        optional: true,
       },
-      title: {
-        type: 'string',
-        description: 'The title of the created folder',
-      },
-      url: {
-        type: 'string',
-        description: 'The URL path to the folder',
+      parents: {
+        type: 'array',
+        description: 'Ancestor folder hierarchy (nested folders only)',
+        optional: true,
       },
       hasAcl: {
         type: 'boolean',
         description: 'Whether the folder has custom ACL permissions',
+        optional: true,
       },
       canSave: {
         type: 'boolean',
         description: 'Whether the current user can save the folder',
+        optional: true,
       },
       canEdit: {
         type: 'boolean',
         description: 'Whether the current user can edit the folder',
+        optional: true,
       },
       canAdmin: {
         type: 'boolean',
         description: 'Whether the current user has admin rights on the folder',
-      },
-      canDelete: {
-        type: 'boolean',
-        description: 'Whether the current user can delete the folder',
+        optional: true,
       },
       createdBy: {
         type: 'string',
         description: 'Username of who created the folder',
+        optional: true,
       },
       created: {
         type: 'string',
         description: 'Timestamp when the folder was created',
+        optional: true,
       },
       updatedBy: {
         type: 'string',
         description: 'Username of who last updated the folder',
+        optional: true,
       },
       updated: {
         type: 'string',
         description: 'Timestamp when the folder was last updated',
+        optional: true,
       },
-      version: {
-        type: 'number',
-        description: 'Version number of the folder',
-      },
+      version: { type: 'number', description: 'Version number of the folder', optional: true },
     },
   }