@runpod/mcp-server 4.0.0 → 4.1.0

package/dist/stdio.mjs

@@ -11,7 +11,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "4.0.0" : "dev";
+var SERVER_VERSION = true ? "4.1.0" : "dev";
 
 // src/specgen/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -269,6 +269,12 @@ var generatedTools = [
     path: "/v2/clusters",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -280,12 +286,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -361,7 +389,7 @@ var generatedTools = [
             {
               type: "object",
               required: ["name", "type", "compute"],
-              description: "Request body for creating a cluster. `compute` defines the\nhomogeneous pod shape; the container configuration (image, env, ports,\n\u2026) applies to every pod and can be spread from a template response.\nPrivate registries are not yet supported for clusters \u2014 there is no\n`registry` field here, unlike the other create requests.\n",
+              description: "Request body for creating a cluster. `compute` defines the\nhomogeneous pod shape; the container configuration (image, env, ports,\n\u2026) applies to every pod. Pass `templateId` to provision every member\npod from a pod template instead of inline container fields \u2014 the\ntemplate also supplies the container registry credential, the only\nprivate-image path for clusters (a bare `registry` property on this\nbody is rejected).\n",
               properties: {
                 compute: {
                   $ref: "#/$defs/ClusterCompute"
@@ -374,6 +402,12 @@ var generatedTools = [
                 type: {
                   $ref: "#/$defs/ClusterType"
                 },
+                templateId: {
+                  type: "string",
+                  minLength: 1,
+                  description: "ID of a pod template to provision every member pod from. The\ntemplate supplies the container settings (image, args, disk,\nenv, ports) and the container registry credential for private\nimages \u2014 the only private-image path for clusters. Mutually\nexclusive with `image`, `args`, `entrypoint`, `cmd`, `disk`,\n`env`, `ports`, and `mounts` (rejected with 400). The cluster\nretains the link: the `template` response field is set. Must be\na non-serverless pod template accessible to the caller.\n",
+                  examples: ["30zmvf89kd"]
+                },
                 dataCenterIds: {
                   type: "array",
                   items: {
@@ -465,6 +499,12 @@ var generatedTools = [
     path: "/v2/registries/delegations",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -504,6 +544,12 @@ var generatedTools = [
     path: "/v2/serverless",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -515,12 +561,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -579,7 +647,7 @@ var generatedTools = [
             pools: {
               type: "array",
               minItems: 1,
-              description: "Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\nNarrow a pool down to specific cards with `excludedTypes`.\n",
+              description: 'Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\nNarrow a pool down to specific cards with `excludedTypes`.\n\nOn `PATCH`, `pools` and `excludedTypes` are one selection and are\nreplaced together, so sending `pools` by itself **clears the\nexclusions**. Two cases:\n\n- **Changing pools, keeping exclusions** \u2014 send both fields in one\n  request: `{"gpu": {"pools": ["ADA_24"], "excludedTypes":\n  ["NVIDIA L40"]}}`. `GET` the endpoint first to read the current\n  `excludedTypes` and resend the ones that still apply to the new\n  pools; an exclusion naming a type outside `pools` is a 400.\n- **Changing only `count` or a CUDA constraint** \u2014 omit `pools`:\n  `{"gpu": {"minCudaVersion": "12.4"}}`. The pool list and the\n  exclusions are both left exactly as they are.\n\n`excludedTypes` documents the full rule.\n',
               items: {
                 type: "string"
               },
@@ -883,6 +951,12 @@ var generatedTools = [
     path: "/v2/network-volumes",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -942,6 +1016,12 @@ var generatedTools = [
     path: "/v2/pods",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -953,12 +1033,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -1244,6 +1346,12 @@ var generatedTools = [
     path: "/v2/registries",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1261,16 +1369,19 @@ var generatedTools = [
             name: {
               type: "string",
               minLength: 1,
+              maxLength: 191,
               examples: ["my-private-registry"]
             },
             password: {
               type: "string",
               minLength: 1,
+              maxLength: 16384,
               description: "Registry password (write-only, not returned in responses)"
             },
             username: {
               type: "string",
               minLength: 1,
+              maxLength: 191,
               description: "Registry username (write-only, not returned in responses)"
             }
           }
@@ -1278,6 +1389,59 @@ var generatedTools = [
       }
     }
   },
+  {
+    name: "create-secret",
+    operationId: "createSecret",
+    description: "Create a secret. Stores a new account-scoped encrypted string. `name` must be unique across the account's secrets and is immutable; `value` is write-only and can never be read back through the API. Use the secret from pods, serverless endpoints, and templates by setting an environment variable's value to `{{ RUNPOD_SECRET_<name> }}` \u2014 Runpod substitutes the stored value when the pod or worker boots. Returns `201` with the created secret's metadata, or `409` when the name is already taken.",
+    method: "POST",
+    path: "/v2/account/secrets",
+    params: [],
+    hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        body: {
+          $ref: "#/$defs/CreateSecretRequest"
+        }
+      },
+      required: ["body"],
+      $defs: {
+        CreateSecretRequest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["name", "value"],
+          properties: {
+            name: {
+              type: "string",
+              minLength: 1,
+              maxLength: 191,
+              pattern: "^[a-zA-Z_][a-zA-Z0-9_.\\-/]*$",
+              description: "Unique name for the secret \u2014 referenced from environment variables as `{{ RUNPOD_SECRET_<name> }}`; immutable after creation. Maximum 191 characters, must start with a letter or underscore, and may contain letters, digits, and `_.-/`. Names beginning with the reserved prefix `RUNPOD` are rejected (case-insensitive).",
+              examples: ["hf-token"]
+            },
+            value: {
+              type: "string",
+              minLength: 1,
+              maxLength: 16777216,
+              description: "The secret value. Write-only \u2014 never returned by the API. Must be smaller than 16 MiB of UTF-8 text (strictly under 16,777,216 bytes)."
+            },
+            description: {
+              type: "string",
+              maxLength: 65535,
+              description: "Optional human-readable description, at most 65,535 bytes of UTF-8 text.",
+              examples: ["Hugging Face read token"]
+            }
+          }
+        }
+      }
+    }
+  },
   {
     name: "create-template",
     operationId: "createTemplate",
@@ -1286,6 +1450,12 @@ var generatedTools = [
     path: "/v2/templates",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1297,12 +1467,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -1465,6 +1657,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1489,6 +1687,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1513,6 +1717,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1537,6 +1747,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1561,6 +1777,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1571,6 +1793,36 @@ var generatedTools = [
       required: ["id"]
     }
   },
+  {
+    name: "delete-secret",
+    operationId: "deleteSecret",
+    description: "Delete a secret. Permanently deletes a secret. Environment variables referencing the deleted secret's name will no longer resolve to a value.",
+    method: "DELETE",
+    path: "/v2/account/secrets/{id}",
+    params: [
+      {
+        name: "id",
+        location: "path"
+      }
+    ],
+    hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Secret identifier"
+        }
+      },
+      required: ["id"]
+    }
+  },
   {
     name: "delete-template",
     operationId: "deleteTemplate",
@@ -1584,6 +1836,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1607,6 +1865,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1645,6 +1909,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1706,6 +1976,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1744,6 +2020,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1758,7 +2040,7 @@ var generatedTools = [
   {
     name: "get-endpoint-build",
     operationId: "getEndpointBuild",
-    description: "Get a serverless endpoint build. Returns one of the endpoint's GitHub builds by id, regardless of age \u2014 unlike the list, which is capped to recent history.",
+    description: "Get a serverless endpoint build. Returns one of the endpoint's GitHub builds by id, regardless of age \u2014 no need to page through `GET /v2/serverless/{id}/builds` to reach it.",
     method: "GET",
     path: "/v2/serverless/{id}/builds/{buildId}",
     params: [
@@ -1772,6 +2054,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1832,6 +2120,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1918,6 +2212,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1942,6 +2242,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1966,6 +2272,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1976,6 +2288,36 @@ var generatedTools = [
       required: ["id"]
     }
   },
+  {
+    name: "get-secret",
+    operationId: "getSecret",
+    description: "Get a secret. Returns a single secret's metadata by ID. The value is write-only and never returned.",
+    method: "GET",
+    path: "/v2/account/secrets/{id}",
+    params: [
+      {
+        name: "id",
+        location: "path"
+      }
+    ],
+    hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Secret identifier"
+        }
+      },
+      required: ["id"]
+    }
+  },
   {
     name: "get-ssh-keys",
     operationId: "getSshKeys",
@@ -1984,6 +2326,12 @@ var generatedTools = [
     path: "/v2/account/ssh-keys",
     params: [],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {}
@@ -2002,6 +2350,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2037,6 +2391,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2107,6 +2467,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2165,6 +2531,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2184,6 +2556,12 @@ var generatedTools = [
     path: "/v2/clusters",
     params: [],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {}
@@ -2212,6 +2590,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2284,6 +2668,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2380,6 +2770,12 @@ var generatedTools = [
     path: "/v2/registries/delegations",
     params: [],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {}
@@ -2410,6 +2806,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2454,22 +2856,47 @@ var generatedTools = [
   {
     name: "list-endpoint-builds",
     operationId: "listEndpointBuilds",
-    description: "List serverless endpoint builds. Returns the endpoint's GitHub build history, newest first (Runpod GitHub-build integration). At most the 100 most recent builds are returned; any older build can still be fetched by id via `GET /v2/serverless/{id}/builds/{buildId}`. Stream a build's logs via `/v2/serverless/{id}/builds/{buildId}/logs`.",
+    description: "List serverless endpoint builds. Returns the endpoint's GitHub build history, newest first (Runpod GitHub-build integration), cursor-paginated; an omitted `limit` defaults to 100, so a bare request returns at most the 100 most recent builds. Any build can also be fetched by id via `GET /v2/serverless/{id}/builds/{buildId}`. Stream a build's logs via `/v2/serverless/{id}/builds/{buildId}/logs`.",
     method: "GET",
     path: "/v2/serverless/{id}/builds",
     params: [
       {
         name: "id",
         location: "path"
+      },
+      {
+        name: "cursor",
+        location: "query"
+      },
+      {
+        name: "limit",
+        location: "query"
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
         id: {
           type: "string",
           description: "Serverless endpoint identifier"
+        },
+        cursor: {
+          type: "string",
+          minLength: 1,
+          description: "Opaque resume cursor \u2014 pass the previous response's `pagination.nextCursor` through verbatim; omit for the first page. A cursor is only valid for the operation and parameters that issued it; a malformed or foreign cursor is rejected with 422.\n"
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Page size, 1\u2013100. Defaults to 100 when omitted."
         }
       },
       required: ["id"]
@@ -2478,22 +2905,47 @@ var generatedTools = [
   {
     name: "list-endpoint-releases",
     operationId: "listEndpointReleases",
-    description: "List serverless endpoint releases. Returns the endpoint's release history (newest first) plus a rollout summary of how many workers are running the current version. Each release is a versioned configuration snapshot with a `diff` of what changed; build-driven releases carry a `buildId` (fetch build detail via the builds sub-routes).",
+    description: "List serverless endpoint releases. Returns the endpoint's release history (newest first) plus a rollout summary of how many workers are running the current version. Each release is a versioned configuration snapshot with a `diff` of what changed; build-driven releases carry a `buildId` (fetch build detail via the builds sub-routes). Releases are cursor-paginated newest-first; an omitted `limit` defaults to 1000. The rollout summary always describes the endpoint's current state, independent of the page requested.",
     method: "GET",
     path: "/v2/serverless/{id}/releases",
     params: [
       {
         name: "id",
         location: "path"
+      },
+      {
+        name: "cursor",
+        location: "query"
+      },
+      {
+        name: "limit",
+        location: "query"
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
         id: {
           type: "string",
           description: "Serverless endpoint identifier"
+        },
+        cursor: {
+          type: "string",
+          minLength: 1,
+          description: "Opaque resume cursor \u2014 pass the previous response's `pagination.nextCursor` through verbatim; omit for the first page. A cursor is only valid for the operation and parameters that issued it; a malformed or foreign cursor is rejected with 422.\n"
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 1e3,
+          description: "Page size, 1\u20131000. Defaults to 1000 when omitted."
         }
       },
       required: ["id"]
@@ -2512,6 +2964,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2564,6 +3022,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2662,6 +3126,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2715,6 +3185,12 @@ var generatedTools = [
     path: "/v2/network-volumes",
     params: [],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {}
@@ -2749,6 +3225,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2797,16 +3279,30 @@ var generatedTools = [
   {
     name: "list-pods",
     operationId: "listPods",
-    description: "List pods. Returns pods owned by the authenticated user. Cluster member pods are excluded by default; set `includeClusterPods=true` to include them (each carries a non-null `cluster` membership block).",
+    description: "List pods. Returns pods owned by the authenticated user. Cluster member pods are excluded by default; set `includeClusterPods=true` to include them (each carries a non-null `cluster` membership block). Results are cursor-paginated newest-first; an omitted `limit` defaults to 1000. When cluster member pods are excluded, the exclusion applies to each page after it is cut, so a page may hold fewer than `limit` pods \u2014 follow `pagination.nextCursor` until `hasNextPage` is false rather than counting items.",
     method: "GET",
     path: "/v2/pods",
     params: [
       {
         name: "includeClusterPods",
         location: "query"
+      },
+      {
+        name: "cursor",
+        location: "query"
+      },
+      {
+        name: "limit",
+        location: "query"
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2814,6 +3310,17 @@ var generatedTools = [
           type: "boolean",
           default: false,
           description: "Include cluster member pods in the result. Defaults to false."
+        },
+        cursor: {
+          type: "string",
+          minLength: 1,
+          description: "Opaque resume cursor \u2014 pass the previous response's `pagination.nextCursor` through verbatim; omit for the first page. A cursor is only valid for the operation and parameters that issued it; a malformed or foreign cursor is rejected with 422.\n"
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 1e3,
+          description: "Page size, 1\u20131000. Defaults to 1000 when omitted."
         }
       }
     }
@@ -2821,7 +3328,7 @@ var generatedTools = [
   {
     name: "list-public-templates",
     operationId: "listPublicTemplates",
-    description: "List public templates. Returns the public template catalog. `source` selects which slice: `official` (the default) is Runpod-curated templates, `verified` is community templates Runpod has verified, and `community` is everything else other users have shared publicly. Both pod and serverless templates appear \u2014 use each entry's `serverless` flag to tell them apart. `registry` is always null for templates you don't own. Your own templates (public or private) are managed under `/v2/templates`; fetch any individual template \u2014 catalog or owned \u2014 via `/v2/templates/{id}`. At most 100 templates are returned. Pagination is not yet supported.",
+    description: "List public templates. Returns the public template catalog. `source` selects which slice: `official` (the default) is Runpod-curated templates, `verified` is community templates Runpod has verified, and `community` is everything else other users have shared publicly. Both pod and serverless templates appear \u2014 use each entry's `serverless` flag to tell them apart. `registry` is always null for templates you don't own. Your own templates (public or private) are managed under `/v2/templates`; fetch any individual template \u2014 catalog or owned \u2014 via `/v2/templates/{id}`. At most 100 templates are returned. Cursor pagination is not yet supported here; `pagination` is always the exhausted marker (`nextCursor: null`, `hasNextPage: false`).",
     method: "GET",
     path: "/v2/catalog/templates",
     params: [
@@ -2831,6 +3338,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2851,11 +3364,46 @@ var generatedTools = [
     path: "/v2/registries",
     params: [],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {}
     }
   },
+  {
+    name: "list-secrets",
+    operationId: "listSecrets",
+    description: "List secrets. Returns the account's secrets \u2014 encrypted strings referenced from pod, serverless, and template environment variables with the `{{ RUNPOD_SECRET_<name> }}` placeholder syntax, substituted with the secret's value when the pod or worker boots. Secret values are write-only and are never returned.",
+    method: "GET",
+    path: "/v2/account/secrets",
+    params: [
+      {
+        name: "name",
+        location: "query"
+      }
+    ],
+    hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "When provided, returns only the secret with this name (case-insensitive)."
+        }
+      }
+    }
+  },
   {
     name: "list-serverless-billing",
     operationId: "listServerlessBilling",
@@ -2885,6 +3433,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2943,6 +3497,12 @@ var generatedTools = [
       }
     ],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -2986,6 +3546,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3009,6 +3575,12 @@ var generatedTools = [
       }
     ],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3051,6 +3623,12 @@ var generatedTools = [
       }
     ],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3066,12 +3644,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -3130,7 +3730,7 @@ var generatedTools = [
             pools: {
               type: "array",
               minItems: 1,
-              description: "Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\nNarrow a pool down to specific cards with `excludedTypes`.\n",
+              description: 'Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\nNarrow a pool down to specific cards with `excludedTypes`.\n\nOn `PATCH`, `pools` and `excludedTypes` are one selection and are\nreplaced together, so sending `pools` by itself **clears the\nexclusions**. Two cases:\n\n- **Changing pools, keeping exclusions** \u2014 send both fields in one\n  request: `{"gpu": {"pools": ["ADA_24"], "excludedTypes":\n  ["NVIDIA L40"]}}`. `GET` the endpoint first to read the current\n  `excludedTypes` and resend the ones that still apply to the new\n  pools; an exclusion naming a type outside `pools` is a 400.\n- **Changing only `count` or a CUDA constraint** \u2014 omit `pools`:\n  `{"gpu": {"minCudaVersion": "12.4"}}`. The pool list and the\n  exclusions are both left exactly as they are.\n\n`excludedTypes` documents the full rule.\n',
               items: {
                 type: "string"
               },
@@ -3375,6 +3975,12 @@ var generatedTools = [
       }
     ],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3425,6 +4031,12 @@ var generatedTools = [
       }
     ],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3440,12 +4052,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -3588,6 +4222,60 @@ var generatedTools = [
       }
     }
   },
+  {
+    name: "update-secret",
+    operationId: "updateSecret",
+    description: "Update a secret. Rotates a secret's value and/or updates its description. Only the provided fields are changed and at least one field is required; the `name` is immutable. Pods and workers receive the new value at their next boot \u2014 running instances keep the value they were started with. When both fields are sent, the value is applied first, then the description. The two updates are not atomic: if the description update fails after the value was rotated, the response is an error but the new value has already taken effect. Send the fields in separate requests when that partial outcome matters.",
+    method: "PATCH",
+    path: "/v2/account/secrets/{id}",
+    params: [
+      {
+        name: "id",
+        location: "path"
+      }
+    ],
+    hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Secret identifier"
+        },
+        body: {
+          $ref: "#/$defs/UpdateSecretRequest"
+        }
+      },
+      required: ["id", "body"],
+      $defs: {
+        UpdateSecretRequest: {
+          type: "object",
+          additionalProperties: false,
+          minProperties: 1,
+          description: "Only the provided fields are updated; at least one field is required.\nThe secret's `name` is immutable.\n",
+          properties: {
+            value: {
+              type: "string",
+              minLength: 1,
+              maxLength: 16777216,
+              description: "New secret value, replacing the current one. Write-only. Must be smaller than 16 MiB of UTF-8 text (strictly under 16,777,216 bytes)."
+            },
+            description: {
+              type: "string",
+              maxLength: 65535,
+              description: 'New human-readable description, at most 65,535 bytes of UTF-8 text. Send `""` to clear.'
+            }
+          }
+        }
+      }
+    }
+  },
   {
     name: "update-ssh-keys",
     operationId: "updateSshKeys",
@@ -3596,6 +4284,12 @@ var generatedTools = [
     path: "/v2/account/ssh-keys",
     params: [],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3641,6 +4335,12 @@ var generatedTools = [
       }
     ],
     hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -3655,12 +4355,34 @@ var generatedTools = [
       $defs: {
         BaseContainerConfig: {
           type: "object",
-          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential).\n",
+          description: "Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support a direct registry credential (clusters \u2014 there the registry credential arrives via a pod template, see CreateClusterRequest.templateId).\n",
           properties: {
             args: {
               type: "string",
-              description: "Arguments passed to the container entrypoint",
-              examples: [""]
+              description: 'The container\'s command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console\'s "Container start command" field writes. A JSON object of the form `{"entrypoint":[...],"cmd":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `""` to clear, omit to leave unchanged.\n',
+              examples: [
+                "--model meta-llama/Llama-3-8B --max-model-len 8192",
+                '{"entrypoint":["/bin/bash","-c"],"cmd":["python -u main.py"]}',
+                ""
+              ]
+            },
+            cmd: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [
+                ["--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192"]
+              ]
+            },
+            entrypoint: {
+              type: "array",
+              items: {
+                type: "string"
+              },
+              description: "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n",
+              examples: [["/bin/bash", "-c"]]
             },
             disk: {
               type: "integer",
@@ -3977,6 +4699,26 @@ var listPaginationProperties = {
     description: "Opaque pagination cursor from a previous response (nextCursor). Omit to start from the beginning."
   }
 };
+function clampListLimit(limit) {
+  const requested = Number(limit);
+  return Math.min(
+    Number.isFinite(requested) && requested >= 1 ? Math.floor(requested) : DEFAULT_LIST_LIMIT,
+    MAX_LIST_LIMIT
+  );
+}
+function serverPageQuery(args) {
+  const cursor = typeof args.cursor === "string" && args.cursor !== "" ? args.cursor : void 0;
+  return { limit: clampListLimit(args.limit), ...cursor ? { cursor } : {} };
+}
+function serverPagination(pagination, returned) {
+  const hasNextPage = pagination?.hasNextPage === true;
+  return {
+    returned,
+    hasNextPage,
+    nextCursor: pagination?.nextCursor ?? null,
+    ...hasNextPage ? { note: "More results exist. Pass cursor=nextCursor to fetch them." } : {}
+  };
+}
 function decodeCursorOffset(cursor) {
   if (!cursor) return 0;
   try {
@@ -3992,11 +4734,7 @@ function encodeCursorOffset(offset) {
   return Buffer.from(String(offset), "utf8").toString("base64");
 }
 function capList(items, options, extra) {
-  const requested = Number(options.limit);
-  const limit = Math.min(
-    Number.isFinite(requested) && requested >= 1 ? Math.floor(requested) : DEFAULT_LIST_LIMIT,
-    MAX_LIST_LIMIT
-  );
+  const limit = clampListLimit(options.limit);
   const offset = decodeCursorOffset(options.cursor);
   const total = items.length;
   const page = items.slice(offset, offset + limit);
@@ -4075,6 +4813,38 @@ async function runTool(body) {
   }
 }
 
+// src/specgen/tools/annotations.ts
+var readOnly = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var bundledRead = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var write = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var idempotentWrite = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var destructive = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,
+  openWorldHint: true
+};
+
 // src/specgen/tools/capacity.ts
 var CUDA_VERSION_REGEX = /^\d{1,2}\.\d{1,2}$/;
 var MAX_PROBE_VERSIONS = 12;
@@ -4109,6 +4879,7 @@ function rankByStock(rows, stats, includeUnavailable) {
 }
 var getCapacity = {
   name: "get-capacity",
+  annotations: readOnly,
   description: "GPU capacity across host CUDA versions, as a matrix. Use this to choose an endpoint's allowedCudaVersions/minCudaVersion (or diagnose/widen a capacity-starved one) and to distinguish capacity problems from compatibility problems. Default mode is one call returning, per GPU type, overall stock plus AVAILABLE/UNAVAILABLE per host-reported CUDA version. Pass cudaVersions to deep-probe instead: one stock lookup per listed version, returning graded stock (High/Medium/Low/Out) and the lowest on-demand price per version; a probe that fails transiently reports a per-version error instead of failing the call. Nothing is hidden by default \u2014 set includeUnavailable:false to drop GPUs with no stock on any listed version. Credential-free public catalog data. Stock is live, so page cursors can shift between calls.",
   inputSchema: {
     type: "object",
@@ -4309,6 +5080,7 @@ function formatGpuIds(gpu) {
 }
 var setEndpointGpus = {
   name: "set-endpoint-gpus",
+  annotations: idempotentWrite,
   description: "Set which GPUs a Serverless endpoint's workers run on \u2014 including pinning specific GPU SKUs. Provide either a raw gpuIds string, or pools plus optional excludeGpuTypeIds (GPU type ids from list-gpu-types) and the exclusion string is built for you: a pool allows every SKU in it, and excluding all but one SKU pins that SKU exactly. Updates only GPU settings through REST v2, preserving other endpoint settings. create-endpoint/update-endpoint also support gpu.excludedTypes.",
   inputSchema: {
     type: "object",
@@ -4502,6 +5274,7 @@ function randomSuffix() {
 }
 var listHubRepos = {
   name: "list-hub-repos",
+  annotations: readOnly,
   description: "List repos published to the Runpod Hub (prebuilt Serverless workers and Pod templates, e.g. vLLM, ComfyUI). Public catalog \u2014 no auth required. Each result includes the currently listed release with its hubReleaseId and prebuilt image name. Results are sorted by deploy count (most popular first). Set includeConfig:true to also return the release config (hardware requirements and environment-variable schema) \u2014 it is large, so prefer requesting it for a single repo via the repoOwner/searchTerm filters.",
   inputSchema: {
     type: "object",
@@ -4603,6 +5376,7 @@ var listHubRepos = {
 };
 var deployHubRepo = {
   name: "deploy-hub-repo",
+  annotations: write,
   description: "Deploy a Runpod Hub repo's listed release as a new Serverless endpoint (the same as clicking Deploy on the Hub). Identify the repo by `repo` (\"owner/name\" from list-hub-repos) or by `hubReleaseId`. The release supplies the prebuilt image, container disk, CUDA constraints, and env-var defaults; pass `env` to override or fill in values (required keys without a default must be provided \u2014 check list-hub-repos with includeConfig:true for the schema). GPU selection comes from the release config when it specifies one; otherwise pass gpuIds (GPU pool names, e.g. 'ADA_24' or 'ADA_80_PRO,AMPERE_80'). Uses the authenticated GraphQL API (no REST home for Hub deploys yet).",
   inputSchema: {
     type: "object",
@@ -5060,6 +5834,7 @@ function validateWait(wait) {
 }
 var runEndpoint = {
   name: "run-endpoint",
+  annotations: write,
   description: "Submit an asynchronous job to a Serverless endpoint. Returns a job ID immediately \u2014 use get-job-status to poll for results (pass its `wait` to block through a cold start instead of tight-looping). Async results are available for 30 minutes after completion.",
   inputSchema: {
     type: "object",
@@ -5089,6 +5864,7 @@ var runEndpoint = {
 };
 var runsyncEndpoint = {
   name: "runsync-endpoint",
+  annotations: write,
   description: "Submit a synchronous job to a Serverless endpoint and wait for the result. Best for fast tasks: if the job outlives the wait, the response returns a job ID and a non-terminal status (IN_QUEUE or IN_PROGRESS) to poll with get-job-status. Max payload 20 MB; results expire after 1 minute. The wait parameter extends the server-side wait" + (HOSTED ? ` \u2014 this server runs behind a 60-second gateway deadline, so waits clamp to ${HTTP_LONG_POLL_BUDGET_MS} ms, which is also the effective default. For longer jobs use run-endpoint + get-job-status.` : " to up to 5 minutes (300000 ms); it defaults to 90000 (90 seconds)."),
   inputSchema: {
     type: "object",
@@ -5132,6 +5908,7 @@ var runsyncEndpoint = {
 };
 var getJobStatus = {
   name: "get-job-status",
+  annotations: readOnly,
   description: "Check the status of a Serverless job. Returns the current status and output when complete. Job statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT. Pass `wait` (milliseconds, up to " + STATUS_WAIT_MAX_MS + ") to BLOCK server-side, polling until the job reaches a terminal status or the budget expires \u2014 use it to ride out a cold start (a first job on a fresh worker pulls the image and loads the model, commonly 1\u20135+ minutes) in a single call instead of returning on the first IN_QUEUE and tight-looping the tool. Without `wait` it returns the current status immediately (a single check). If the budget expires before a terminal status, it returns the latest non-terminal status with pollingTimedOut:true \u2014 call again (with `wait`) to keep blocking. IMPORTANT: a job stuck IN_QUEUE does not necessarily mean a capacity shortage \u2014 a worker may have spun up and crash-looped. When the job is IN_QUEUE this tool attaches a workerHealth summary and a hint. To dig deeper call list-endpoint-workers, then read stream-worker-logs regardless of the status a worker reports: a container failing to start loops while its worker still shows RUNNING or THROTTLED and unhealthy stays 0, so UNHEALTHY is one symptom of a crash loop and not a test for it. The logs are the authority.",
   inputSchema: {
     type: "object",
@@ -5179,6 +5956,7 @@ var getJobStatus = {
 };
 var streamJob = {
   name: "stream-job",
+  annotations: readOnly,
   description: `Retrieve streaming output from a Serverless job. The worker must support streaming output. Polls /stream/{jobId} and collects chunks until the status is COMPLETED, FAILED, CANCELLED, or TIMED_OUT, for up to ${formatBudget(STREAM_BUDGET_MS)}. If the budget expires first, returns the chunks collected so far with pollingTimedOut: true \u2014 call stream-job again to resume where it left off, or get-job-status to check without streaming.`,
   inputSchema: {
     type: "object",
@@ -5209,6 +5987,7 @@ var streamJob = {
 };
 var cancelJob = {
   name: "cancel-job",
+  annotations: destructive,
   description: "Cancel a Serverless job that is queued or in progress.",
   inputSchema: {
     type: "object",
@@ -5233,6 +6012,7 @@ var cancelJob = {
 };
 var retryJob = {
   name: "retry-job",
+  annotations: write,
   description: "Retry a failed or timed-out Serverless job. Only works for jobs with FAILED or TIMED_OUT status. The previous output is removed and the job is requeued.",
   inputSchema: {
     type: "object",
@@ -5257,6 +6037,7 @@ var retryJob = {
 };
 var endpointHealth = {
   name: "endpoint-health",
+  annotations: readOnly,
   description: "Get the endpoint-level health rollup for a Serverless endpoint: worker counts by state plus job queue statistics. This is the runtime plane's own /health view and it can lag or disagree with the per-worker truth \u2014 when a job is stuck IN_QUEUE, prefer list-endpoint-workers over this rollup for per-worker state \u2014 but treat neither as the authority on crash loops, because a container failing to start loops while its worker reports RUNNING or THROTTLED and unhealthy stays 0; stream-worker-logs is what settles it, and note that get-job-status already attaches that worker summary and a hint on every IN_QUEUE result. Zero workers here means the endpoint is waiting for GPU capacity.",
   inputSchema: {
     type: "object",
@@ -5276,6 +6057,7 @@ var endpointHealth = {
 };
 var purgeEndpointQueue = {
   name: "purge-endpoint-queue",
+  annotations: destructive,
   description: "Remove all pending jobs from a Serverless endpoint queue. Only affects queued jobs \u2014 in-progress jobs continue running. Use this for error recovery or clearing outdated requests.",
   inputSchema: {
     type: "object",
@@ -5311,13 +6093,16 @@ var jobTools = [
 // src/specgen/tools/list-endpoints.ts
 var listEndpoints = {
   name: "list-endpoints",
+  annotations: readOnly,
   description: "List serverless endpoints owned by the account (trimmed: id, name, image, compute config, worker counts, scaling, data centers per endpoint \u2014 env vars and request URLs are omitted; use get-endpoint for the full object). Returns a page; pass cursor=nextCursor for more.",
   inputSchema: {
     type: "object",
     properties: { ...listPaginationProperties }
   },
   async handler(ctx, args) {
-    const { data, error, response } = await ctx.sdk.GET("/v2/serverless");
+    const { data, error, response } = await ctx.sdk.GET("/v2/serverless", {
+      params: { query: serverPageQuery(args) }
+    });
     if (!response.ok) return restError(response, error);
     if (!data || !Array.isArray(data.endpoints)) {
       return {
@@ -5342,10 +6127,10 @@ var listEndpoints = {
     return {
       ok: true,
       status: response.status,
-      payload: capList(trimmed, {
-        limit: args.limit,
-        cursor: args.cursor
-      })
+      payload: {
+        items: trimmed,
+        pagination: serverPagination(data.pagination, trimmed.length)
+      }
     };
   }
 };
@@ -5353,10 +6138,16 @@ var listEndpoints = {
 // src/specgen/tools/list-templates.ts
 var listTemplates = {
   name: "list-templates",
-  description: "List templates visible to the account. Returns id, name, image, and serverless flag per template; use get-template for full detail.",
-  inputSchema: { type: "object", properties: {} },
-  async handler(ctx) {
-    const { data, error, response } = await ctx.sdk.GET("/v2/templates");
+  annotations: readOnly,
+  description: "List templates visible to the account. Returns id, name, image, and serverless flag per template; use get-template for full detail. Returns 20 templates per page by default. To find a template, follow `pagination.nextCursor` until `hasNextPage` is false: a name missing from one page may be on a later one.",
+  inputSchema: {
+    type: "object",
+    properties: { ...listPaginationProperties }
+  },
+  async handler(ctx, args) {
+    const { data, error, response } = await ctx.sdk.GET("/v2/templates", {
+      params: { query: serverPageQuery(args) }
+    });
     if (!response.ok) return restError(response, error);
     if (!data || !Array.isArray(data.templates)) {
       return {
@@ -5374,13 +6165,14 @@ var listTemplates = {
           name: template.name,
           image: template.image,
           serverless: template.serverless
-        }))
+        })),
+        pagination: serverPagination(data.pagination, data.templates.length)
       }
     };
   }
 };
 
-// node_modules/.pnpm/@runpod+typescript-api-sdk@0.1.1/node_modules/@runpod/typescript-api-sdk/dist/index.js
+// node_modules/.pnpm/@runpod+typescript-api-sdk@0.2.0/node_modules/@runpod/typescript-api-sdk/dist/index.js
 var PATH_PARAM_RE = /\{[^{}]+\}/g;
 var supportsRequestInitExt = () => {
   return typeof process === "object" && Number.parseInt(process?.versions?.node?.substring(0, 2)) >= 18 && process.versions.undici;
@@ -6784,6 +7576,7 @@ function logParams(args) {
 }
 var streamPodLogs = {
   name: "stream-pod-logs",
+  annotations: readOnly,
   description: "Read a bounded snapshot of a Pod's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the byte cap cut the output. Use `since` to resume from a timestamp.",
   inputSchema: {
     type: "object",
@@ -6805,6 +7598,7 @@ var streamPodLogs = {
 };
 var streamWorkerLogs = {
   name: "stream-worker-logs",
+  annotations: readOnly,
   description: "Read a bounded snapshot of a Serverless worker's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the byte cap cut the output. Get worker IDs from list-endpoint-workers. Use this whenever a job stays IN_QUEUE while workers exist, whatever status they report \u2014 a crash-looping container often still shows RUNNING or THROTTLED with unhealthy 0, so these logs, not the worker status, are what identify a crash loop.",
   inputSchema: {
     type: "object",
@@ -6845,6 +7639,7 @@ function parseMetadata(metadata) {
 }
 var listPublicEndpoints = {
   name: "list-public-endpoints",
+  annotations: readOnly,
   description: "List Runpod Public Endpoints \u2014 managed, pay-per-use model APIs (text, image, video, audio) that require no deployment. Public catalog, no auth required. Each result includes the endpointId to call with run-endpoint/runsync-endpoint (or via https://api.runpod.ai/v2/{endpointId}), the model name, modality, owner, and pricing. Only live endpoints are returned by default; set includeOffline:true to also list ones that are not currently live.",
   inputSchema: {
     type: "object",
@@ -6943,6 +7738,318 @@ var listPublicEndpoints = {
   })
 };
 
+// src/specgen/tools/knowledge.ts
+import {
+  loadKnowledge
+} from "@runpod/plugin-knowledge";
+var knowledge = loadKnowledge();
+var GUIDE_KINDS = ["skill", "reference", "golden-path"];
+var STOPWORDS = new Set(
+  "a an and are as at be by can do does for from how i in is it my of on or the to what when why with you your".split(
+    " "
+  )
+);
+var singular = (word) => {
+  if (word.length > 4 && word.endsWith("ies")) return `${word.slice(0, -3)}y`;
+  if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss"))
+    return word.slice(0, -1);
+  return word;
+};
+var words = (text) => text.toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length > 1 && !STOPWORDS.has(word)).map(singular);
+function editDistance(a, b, max) {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    if (Math.min(...current) > max) return max + 1;
+    previous = current;
+  }
+  return previous[b.length];
+}
+var typoBudget = (text) => text.length >= 8 ? 2 : text.length >= 4 ? 1 : 0;
+var oneTypo = (word, term) => term.length >= 5 && editDistance(word, term, 1) <= 1;
+var termMatches = (word, term) => word.startsWith(term) || oneTypo(word, term);
+var nameMatches = (name, term) => name === term || oneTypo(name, term);
+var guideSummary = ({
+  id,
+  kind,
+  title,
+  description,
+  lanes,
+  mcp,
+  needs_shell,
+  concepts
+}) => ({
+  id,
+  kind,
+  title,
+  description,
+  lanes,
+  mcp,
+  needs_shell,
+  concepts
+});
+function linkedGuides(conceptId) {
+  const byId = new Map(knowledge.guides.map((guide) => [guide.id, guide]));
+  const seen = /* @__PURE__ */ new Set();
+  const examples = [];
+  const docs = [];
+  for (const link of knowledge.links) {
+    if (link.to !== conceptId || seen.has(link.from)) continue;
+    seen.add(link.from);
+    const guide = byId.get(link.from);
+    if (!guide) continue;
+    if (guide.kind === "golden-path")
+      examples.push({ id: guide.id, title: guide.title, mcp: guide.mcp });
+    else
+      docs.push({
+        id: guide.id,
+        title: guide.title,
+        ...link.rules ? { rules: link.rules } : {}
+      });
+  }
+  return { examples, docs };
+}
+var conceptIndex = /* @__PURE__ */ new Map();
+for (const concept of knowledge.concepts) {
+  for (const key of [concept.id, concept.name, ...concept.aliases]) {
+    if (!conceptIndex.has(key.toLowerCase()))
+      conceptIndex.set(key.toLowerCase(), concept);
+  }
+}
+var conceptKey = (text) => text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map(singular).join(" ");
+var conceptKeyIndex = /* @__PURE__ */ new Map();
+for (const [key, concept] of conceptIndex) {
+  if (!conceptKeyIndex.has(conceptKey(key)))
+    conceptKeyIndex.set(conceptKey(key), concept);
+}
+function resolveConcept(input) {
+  const exact = conceptIndex.get(input.trim().toLowerCase());
+  if (exact) return { concept: exact };
+  const key = conceptKey(input);
+  const plural = conceptKeyIndex.get(key);
+  if (plural) return { concept: plural, matchedAs: key };
+  const budget = typoBudget(key);
+  let best;
+  let tied = false;
+  for (const [candidate, concept] of conceptKeyIndex) {
+    const distance = editDistance(key, candidate, budget);
+    if (distance > budget) continue;
+    if (!best || distance < best.distance) {
+      best = { concept, key: candidate, distance };
+      tied = false;
+    } else if (distance === best.distance && concept.id !== best.concept.id) {
+      tied = true;
+    }
+  }
+  return best && !tied ? { concept: best.concept, matchedAs: best.key } : void 0;
+}
+var ruleIndex = /* @__PURE__ */ new Map();
+for (const concept of knowledge.concepts) {
+  for (const rule of concept.rules) ruleIndex.set(rule.id, { rule, concept });
+}
+var source = {
+  plugin_version: knowledge.version,
+  plugin_commit: knowledge.commit
+};
+var listGuides = {
+  name: "list-guides",
+  annotations: bundledRead,
+  description: "List the official Runpod guides: skills (how to work with each tool), reference docs (how Runpod works), and golden paths (live-verified end-to-end walkthroughs such as a dev pod, a Whisper endpoint or a fine-tune-to-serverless pipeline). Read one with read-guide. For a golden path, mcp says whether an agent with only these MCP tools can finish it: full (follow it with tool calls), partial (use it for the plan and facts; name the step the user must run in a terminal), none (reference only). Skills and reference docs have mcp null. concepts lists the concept ids it works with (see lookup-concept). Filter with kind, query or concept.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      kind: {
+        type: "string",
+        enum: [...GUIDE_KINDS],
+        description: "Only this kind of guide."
+      },
+      query: {
+        type: "string",
+        description: "Words to match against the id, title and description."
+      },
+      concept: {
+        type: "string",
+        description: 'Only guides linked to this concept id, for example "network-volume".'
+      }
+    },
+    additionalProperties: false
+  },
+  handler: async (_ctx, args) => {
+    const kind = args.kind;
+    const terms = words(String(args.query ?? ""));
+    const concept = args.concept ? String(args.concept).trim() : void 0;
+    const guides = knowledge.guides.filter((guide) => !kind || guide.kind === kind).filter((guide) => !concept || guide.concepts.includes(concept)).filter((guide) => {
+      if (!terms.length) return true;
+      const haystack = `${guide.id} ${guide.title} ${guide.description}`.toLowerCase();
+      return terms.some((term) => haystack.includes(term));
+    }).map(guideSummary);
+    return ok({ ...source, count: guides.length, guides });
+  }
+};
+var readGuide = {
+  name: "read-guide",
+  annotations: bundledRead,
+  description: 'Read one official Runpod guide in full, by the id list-guides returns (for example "runpod-usage/storage" or "golden-path/06-dev-pod").',
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "The guide id from list-guides." }
+    },
+    required: ["id"],
+    additionalProperties: false
+  },
+  handler: async (_ctx, args) => {
+    const id = String(args.id).trim();
+    const guide = knowledge.guides.find((candidate) => candidate.id === id);
+    if (!guide) {
+      const close = knowledge.guides.filter(
+        (candidate) => candidate.id.includes(id) || id.includes(candidate.id)
+      ).map((candidate) => candidate.id);
+      return {
+        ok: false,
+        status: 404,
+        payload: {
+          error: `No guide with id "${id}".`,
+          hint: close.length ? `Did you mean: ${close.join(", ")}?` : "Call list-guides for the ids."
+        }
+      };
+    }
+    return ok({
+      ...source,
+      ...guideSummary(guide),
+      parent: guide.parent,
+      path: guide.path,
+      body: guide.body
+    });
+  }
+};
+var lookupConcept = {
+  name: "lookup-concept",
+  annotations: bundledRead,
+  description: 'Look up one Runpod concept (pod, network volume, machine, worker, template, \u2026) by id, name or alias; case, plurals and small typos are tolerated, and `matched_as` shows the key used when the match was not exact. Returns its summary, fields, states, relations and rules, each rule with the public source it comes from, the concepts that point at it, and the linked guides: examples (golden paths that use it, with their mcp level) and docs (skills and reference docs that explain it). Use it for exact facts, for example "is a volume disk tied to one machine" or "what happens to a stopped pod\'s GPU".',
+  inputSchema: {
+    type: "object",
+    properties: {
+      concept: {
+        type: "string",
+        description: 'An id, name or alias, such as "pod", "Network volume" or "volume disk".'
+      }
+    },
+    required: ["concept"],
+    additionalProperties: false
+  },
+  handler: async (_ctx, args) => {
+    const resolved = resolveConcept(String(args.concept));
+    if (!resolved) {
+      const ref = conceptKey(String(args.concept));
+      const close = [...conceptKeyIndex.keys()].filter(
+        (key) => key.includes(ref) || editDistance(key, ref, typoBudget(ref) + 1) <= typoBudget(ref) + 1
+      ).slice(0, 10);
+      return {
+        ok: false,
+        status: 404,
+        payload: {
+          error: `No concept matches "${args.concept}".`,
+          hint: close.length ? `Close matches: ${close.join(", ")}.` : "Try search-concepts with a few words instead."
+        }
+      };
+    }
+    const { concept, matchedAs } = resolved;
+    const pointedAtBy = knowledge.concepts.flatMap((other) => [
+      ...other.is_a === concept.id ? [{ concept: other.id, type: "is_a" }] : [],
+      ...other.part_of === concept.id ? [{ concept: other.id, type: "part_of" }] : [],
+      ...other.relations.filter((relation) => relation.target === concept.id).map((relation) => ({ concept: other.id, type: relation.type }))
+    ]);
+    const linkedRules = [...new Set(concept.rules.flatMap((rule) => rule.see))].map((id) => ruleIndex.get(id)).filter((entry) => entry !== void 0).map(({ rule, concept: owner }) => ({
+      concept: owner.id,
+      id: rule.id,
+      statement: rule.statement.trim()
+    }));
+    return ok({
+      ...source,
+      ...matchedAs ? { matched_as: matchedAs } : {},
+      ...concept,
+      pointed_at_by: pointedAtBy,
+      linked_rules: linkedRules,
+      ...linkedGuides(concept.id)
+    });
+  }
+};
+var searchConcepts = {
+  name: "search-concepts",
+  annotations: bundledRead,
+  description: 'Search the rules of the Runpod concept graph by words, for example "restart stopped pod no gpu" or "network volume data center". Returns the best-matching rules with their concept and public evidence. Follow up with lookup-concept for the full concept.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "A few words describing the question."
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 25,
+        description: "Most rules to return. Default 8."
+      }
+    },
+    required: ["query"],
+    additionalProperties: false
+  },
+  handler: async (_ctx, args) => {
+    const terms = words(String(args.query));
+    if (!terms.length) return badRequest("query needs at least one word.");
+    const limit = Math.min(Math.max(Number(args.limit) || 8, 1), 25);
+    const hits = [...ruleIndex.values()].map(({ rule, concept }) => {
+      const statement = words(rule.statement);
+      const names = words(
+        [concept.id, concept.name, ...concept.aliases].join(" ")
+      );
+      const ruleId = words(rule.id);
+      const score = terms.reduce(
+        (total, term) => total + statement.filter((word) => termMatches(word, term)).length + (names.some((name) => nameMatches(name, term)) ? 3 : 0) + (ruleId.includes(term) ? 1 : 0),
+        0
+      );
+      const matched = terms.filter(
+        (term) => statement.some((word) => termMatches(word, term)) || names.some((name) => nameMatches(name, term))
+      ).length;
+      return { rule, concept, score: score * matched };
+    }).filter((hit) => hit.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map(({ rule, concept }) => ({
+      concept: concept.id,
+      concept_name: concept.name,
+      id: rule.id,
+      statement: rule.statement.trim(),
+      status: rule.status,
+      conflict: rule.conflict,
+      evidence: rule.evidence
+    }));
+    return ok({ ...source, count: hits.length, rules: hits });
+  }
+};
+var knowledgeTools = [
+  listGuides,
+  readGuide,
+  lookupConcept,
+  searchConcepts
+];
+var GUIDE_URI_PREFIX = "runpod://guides/";
+var guideResources = knowledge.guides.map((guide) => ({
+  uri: `${GUIDE_URI_PREFIX}${guide.id}`,
+  name: guide.id,
+  title: guide.title,
+  description: guide.description,
+  mimeType: "text/markdown",
+  text: guide.body
+}));
+
 // src/specgen/analytics.ts
 import { createHmac } from "crypto";
 var CAPTURE_TIMEOUT_MS = 3e3;
@@ -7357,6 +8464,7 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "report_feedback",
+    annotations: write,
     description: "Report a problem or friction with Runpod or these tools: a wrong result, a confusing error, a docs gap, an API behavior that surprised you. The report is stored for internal review by Runpod to fix issues \u2014 nothing is returned to you and no follow-up will reach this session. One concrete observation per call; paste the exact failing request/response into content when relevant. Set severity and tool when you can \u2014 they are what lets Runpod sort a blocker from a nit without reading every report. Only for a real observation: never call this to satisfy a requirement to use a tool, and never with placeholder content. Never include API keys or secrets.",
     inputSchema: alpInputSchema(
       "The observation: what happened, what you expected, and the exact error or response text if you have it.",
@@ -7392,6 +8500,7 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "save_to_journal",
+    annotations: write,
     description: "Save something you learned about using Runpod that a future session would benefit from (e.g. 'image X needs CUDA 12.8', 'endpoint type cannot be changed after create'). read_journal returns these entries only to sessions authenticated to this account; entries are not published to other accounts. Runpod stores and reviews submissions to improve agent workflows. Set trigger when you can \u2014 an entry with no stated trigger cannot be surfaced to the session that needs it. Never include API keys or secrets.",
     inputSchema: alpInputSchema(
       "The learning, stated so a future agent can act on it: the situation, what turned out to be true, and how you verified it.",
@@ -7422,6 +8531,7 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "ask_question",
+    annotations: write,
     description: "Record a question about Runpod that you could not answer with the available tools, skills, and docs. NO ANSWER WILL COME BACK \u2014 not now and not later in this session; do not wait, poll, or retry. Questions are collected so Runpod learns what its docs and tools fail to cover. Ask when genuinely stuck (it costs one call and improves what future agents get), then consult the runpod://skills/ resources and continue with your best judgment. Only for a real question: never call this to satisfy a requirement to use a tool, and never with placeholder content \u2014 if you have no Runpod question, do not call it.",
     inputSchema: alpInputSchema(
       "The question, with enough context that someone reading it later understands what you were blocked on.",
@@ -7446,6 +8556,7 @@ function createAlpTools(opts) {
   const readJournalTool = {
     lenientArguments: true,
     name: "read_journal",
+    annotations: readOnly,
     description: "Read back this account's private journal: the lessons earlier sessions on this account saved with save_to_journal, newest first. Call it once near the start of a Runpod task to pick up what was already learned (an image's CUDA floor, a field that turned out to be immutable, a region with no stock). Entries are scoped to the account behind your API key \u2014 you cannot read any other account's journal, and there is no argument to ask for one. Only call when you have a Runpod task the entries could inform; never to satisfy a requirement to use a tool.",
     inputSchema: {
       type: "object",
@@ -7496,7 +8607,8 @@ var curatedTools = [
   getCapacity,
   ...hubTools,
   setEndpointGpus,
-  listPublicEndpoints
+  listPublicEndpoints,
+  ...knowledgeTools
 ];
 var SERVER_INSTRUCTIONS = `These tools cover the Runpod v2 REST surface: compute catalog (GPUs, CPUs, data centers, capacity), pods, serverless endpoints and jobs, templates, network volumes, container registries, billing, public endpoints, and the Hub.
 
@@ -7508,6 +8620,8 @@ Mutations cost money and bind to what this conversation created. State the hourl
 
 These tools manage infrastructure only. They do not do SSH sessions, file transfer to or from pods, local image builds, or interactive terminals \u2014 say plainly when a task needs one of those and name the real path (the Runpod console, runpodctl) instead of improvising.
 
+OFFICIAL GUIDES AND FACTS. list-guides and read-guide serve the official Runpod plugin's skills, reference docs and live-verified golden paths, so you have them even without the plugin installed. For a multi-step or billable task, look for a matching golden path first. lookup-concept and search-concepts answer exact questions about how Runpod works (what a stopped pod keeps, where a volume lives) with the public source for each fact.
+
 SKILLS \u2014 READ BEFORE ACTING. This server publishes its task playbooks as MCP resources under runpod://skills/. Before the FIRST Runpod tool call of a session, read runpod://skills/runpod (the router): it maps the request to a journey skill \u2014 deploying an endpoint reads runpod://skills/serverless-deploy, diagnosing a broken pod reads runpod://skills/pod-doctor, cost questions read runpod://skills/cost-audit, and so on \u2014 and each journey skill carries the procedure, pitfalls, and report format for that task. A reply produced without the routed skill loaded is out of contract. List them all with resources/list.
 
 THE OFFICIAL RUNPOD PLUGIN. Runpod ships an agent plugin that covers the lanes these resources do not: the runpodctl and flash CLIs, image builds and model downloads, the official pod templates, and verified end-to-end golden paths. Check once per session whether skills named runpod, runpod-usage, or runpodctl are available to you \u2014 read what you already have, never shell out to look. If they are there, prefer them for procedure and lane choice and treat runpod://skills/ as the fallback. If you do not see them, recommend the plugin to the user, and recommend updating to the latest if what they have is missing something you need. Point them at https://github.com/runpod/runpod-plugins-official \u2014 its README carries the install, update, and clone commands for each client, so read it yourself when you need the exact one rather than guessing a command. This is a recommendation, never a prerequisite: make it once, briefly, and get on with the task. Either way this server is the source of truth for its OWN tool surface: the live tool schemas and the runpod:// resources override any Runpod tool list written down elsewhere, the plugin's included.
@@ -7539,32 +8653,56 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
   };
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
-      ...servedCuratedTools.map(({ name, description, inputSchema }) => ({
-        name,
-        description,
-        inputSchema
-      })),
-      ...generatedTools.map(({ name, description, inputSchema }) => ({
-        name,
-        description,
-        inputSchema
-      }))
+      ...servedCuratedTools.map(
+        ({ name, description, inputSchema, annotations }) => ({
+          name,
+          description,
+          inputSchema,
+          annotations
+        })
+      ),
+      ...generatedTools.map(
+        ({ name, description, inputSchema, annotations }) => ({
+          name,
+          description,
+          inputSchema,
+          annotations
+        })
+      )
     ]
   }));
   const SKILL_URI_PREFIX = "runpod://skills/";
   server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: skillDocs.map((skill) => ({
-      uri: `${SKILL_URI_PREFIX}${skill.name}`,
-      name: skill.name,
-      title: `Runpod skill: ${skill.name}`,
-      description: skill.description,
-      mimeType: "text/markdown"
-    }))
+    resources: [
+      ...skillDocs.map((skill) => ({
+        uri: `${SKILL_URI_PREFIX}${skill.name}`,
+        name: skill.name,
+        title: `Runpod skill: ${skill.name}`,
+        description: skill.description,
+        mimeType: "text/markdown"
+      })),
+      ...guideResources.map(({ text: _text, ...resource }) => resource)
+    ]
   }));
   server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
     resourceTemplates: []
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri.startsWith(GUIDE_URI_PREFIX)) {
+      const guide = guideResources.find(
+        (candidate) => candidate.uri === request.params.uri
+      );
+      if (!guide) {
+        throw new Error(
+          `Unknown resource ${request.params.uri}. Call list-guides for the guide ids.`
+        );
+      }
+      return {
+        contents: [
+          { uri: guide.uri, mimeType: "text/markdown", text: guide.text }
+        ]
+      };
+    }
     const name = request.params.uri.startsWith(SKILL_URI_PREFIX) ? request.params.uri.slice(SKILL_URI_PREFIX.length) : void 0;
     const skill = skillDocs.find((candidate) => candidate.name === name);
     if (!skill) {