@runpod/mcp-server 4.0.0 → 4.2.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.2.0" : "dev";
 
 // src/specgen/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -264,11 +264,17 @@ var generatedTools = [
   {
     name: "create-cluster",
     operationId: "createCluster",
-    description: "Create an instant cluster (multiple pods with high-speed interconnect). BILLABLE from creation for every pod in the cluster: state the total hourly price before creating. Verify GPU stock first via the catalog tools; delete with delete-cluster when finished.",
+    description: "Create an instant cluster (multiple pods with high-speed interconnect). BILLABLE from creation for every pod in the cluster: it rents compute.podCount identical pods at once, each with compute.gpuCountPerPod GPUs of compute.gpuTypeId \u2014 state the hourly price for the total GPU count (podCount * gpuCountPerPod, priced from the catalog tools) and create only after the user's explicit go on that quoted shape and total hourly price. Verify GPU stock first via the catalog tools. The compute shape and type are fixed at creation; only the name can be changed later. The container configuration applies to every pod, and templateId is the only private-image path \u2014 a bare registry property is rejected. Delete with delete-cluster when finished.",
     method: "POST",
     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: {
@@ -499,11 +539,17 @@ var generatedTools = [
   {
     name: "create-endpoint",
     operationId: "createEndpoint",
-    description: "Create a serverless endpoint. BILLABLE: state the GPU class's hourly price (from the catalog tools) before creating. GPU selection is the required gpu object: gpu.pools takes serverless pool ids from the catalog (e.g. ADA_24), never display names, and gpu.count sets GPUs per worker. type and scaling are required and fix the request-routing model. Workers cold-start on the first job: expect minutes, poll with get-job-status wait.",
+    description: "Create a serverless endpoint. BILLABLE: state the worker's hourly price (from the catalog tools) before creating. Worker hardware is one of two choices: the gpu object (gpu.pools takes serverless pool ids from the catalog, e.g. ADA_24, never display names; gpu.count sets GPUs per worker) or the cpu array of CPU flavor configurations for a CPU endpoint. type and scaling are required and fix the request-routing model. Workers cold-start on the first job: expect minutes, poll with get-job-status wait.",
     method: "POST",
     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",
@@ -1455,7 +1647,7 @@ var generatedTools = [
   {
     name: "delete-cluster",
     operationId: "deleteCluster",
-    description: "Delete a cluster. Permanently deletes a cluster and terminates all of its member pods.",
+    description: "Delete a cluster permanently: it terminates every member pod. Verify the id with get-cluster, and list-cluster-pods for what the delete takes down, before deleting; delete only clusters your own tool calls created in this conversation, or the one the user asked you to delete by id \u2014 a name found by listing is not attribution.",
     method: "DELETE",
     path: "/v2/clusters/{id}",
     params: [
@@ -1465,6 +1657,12 @@ var generatedTools = [
       }
     ],
     hasBody: false,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -1479,7 +1677,7 @@ var generatedTools = [
   {
     name: "delete-endpoint",
     operationId: "deleteEndpoint",
-    description: "Delete a serverless endpoint permanently and immediately. Verify the id belongs to the intended endpoint (get-endpoint) before deleting; delete only endpoints your own tool calls created in this conversation \u2014 a name is not attribution.",
+    description: "Delete a serverless endpoint permanently and immediately. Verify the id belongs to the intended endpoint (get-endpoint) before deleting; delete only endpoints your own tool calls created in this conversation, or the one the user asked you to delete by id \u2014 a name found by listing is not attribution.",
     method: "DELETE",
     path: "/v2/serverless/{id}",
     params: [
@@ -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: {
@@ -1527,7 +1737,7 @@ var generatedTools = [
   {
     name: "delete-pod",
     operationId: "deletePod",
-    description: "Terminate a pod permanently \u2014 its container disk is lost. Distinguish from stopping (pod-action stop) which releases the GPU but keeps volume data. Verify the id with get-pod first; terminate only pods your own tool calls created in this conversation \u2014 a name is not attribution.",
+    description: "Terminate a pod permanently \u2014 its container disk is lost. Distinguish from stopping (pod-action stop) which releases the GPU but keeps volume data. Verify the id with get-pod first; terminate only pods your own tool calls created in this conversation, or the one the user asked you to terminate by id \u2014 a name found by listing is not attribution.",
     method: "DELETE",
     path: "/v2/pods/{id}",
     params: [
@@ -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. Environment variables referencing its name ({{ RUNPOD_SECRET_<name> }}) stop resolving at the next pod or worker boot; running instances keep the value they started with. Verify the id with get-secret first; delete only secrets your own tool calls created in this conversation, or the one the user asked you to delete by id \u2014 a name found by listing is not attribution.",
+    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: {
@@ -3041,7 +3613,7 @@ var generatedTools = [
   {
     name: "update-endpoint",
     operationId: "updateEndpoint",
-    description: "Partially update a serverless endpoint (PATCH): only fields present in the body change, omitted ones are untouched. DESTRUCTIVE GOTCHA: sending gpu.pools replaces the GPU selection wholesale, which clears any gpu.excludedTypes pinned elsewhere (the console or set-endpoint-gpus) \u2014 read the endpoint first with get-endpoint and resend excludedTypes if you still want them. A CUDA-only or count-only change does not need pools at all, so omit it unless you mean to replace the selection. Mutable fields: name, gpu, cpu, workers (min/max), scaling (type/value/idleTimeout), dataCenterIds, networkVolumes, timeout, flashboot, and the container settings (image, args, disk, ports, env, registry). Compute family is immutable: gpu on a CPU endpoint, cpu on a GPU one, or both, returns 400. Effect timing differs by field \u2014 workers/scaling/timeout reach the autoscaler promptly, while container changes (image, env) cut a new release that rolls out as workers cycle, so in-flight workers keep the previous version. Track rollout with list-endpoint-releases.",
+    description: "Partially update a serverless endpoint (PATCH): only fields present in the body change, omitted ones are untouched, with one exception. DESTRUCTIVE GOTCHA: gpu.pools and gpu.excludedTypes are a single selection, so sending pools without excludedTypes clears any exclusions pinned elsewhere (the console or set-endpoint-gpus) \u2014 read the endpoint first with get-endpoint and resend excludedTypes if you still want them. An exclusion naming a type outside pools returns 400. A CUDA-only or count-only change does not need pools at all, so omit it unless you mean to replace the selection. Mutable fields: name, gpu, cpu, workers (min/max/idleTimeout), scaling (type plus queueDelay or requestCount), dataCenterIds, networkVolumes, timeout, flashboot, and the container settings (image, args, disk, ports, env, registry). cpu completely replaces a CPU endpoint's flavor selection. Compute family is immutable: gpu on a CPU endpoint, cpu on a GPU one, or both, returns 400. Effect timing differs by field \u2014 workers/scaling/timeout reach the autoscaler promptly, while container changes (image, env) cut a new release that rolls out as workers cycle, so in-flight workers keep the previous version. Track rollout with list-endpoint-releases.",
     method: "PATCH",
     path: "/v2/serverless/{id}",
     params: [
@@ -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",
@@ -3797,171 +4519,6 @@ var generatedTools = [
   }
 ];
 
-// src/specgen/generated/skills.gen.ts
-var skillDocs = [
-  {
-    name: "api-boundary",
-    description: `Recognize when a task exceeds Runpod's current management-API surface and answer honestly \u2014 state the gap plainly, name the specific operation that isn't exposed, and give the real working path. Never fabricate a tool call or claim a silent success. Trigger on phrases like "store a secret / gated Llama token", "set up secrets", "move my dataset in / checkpoints out", "transfer files to my pod", "multi-node training cluster", "instant cluster".`,
-    text: '---\nname: api-boundary\ndescription: Recognize when a task exceeds Runpod\'s current management-API surface and answer honestly \u2014 state the gap plainly, name the specific operation that isn\'t exposed, and give the real working path. Never fabricate a tool call or claim a silent success. Trigger on phrases like "store a secret / gated Llama token", "set up secrets", "move my dataset in / checkpoints out", "transfer files to my pod", "multi-node training cluster", "instant cluster".\n---\n\n# API boundary\n\nSome operations a user asks for are simply not on the Runpod management API today. Your job is to say so plainly \u2014 name the exact gap, do not fabricate a tool that would do it, do not report a silent success \u2014 and then hand the user the real working path. Any account fact you cite (a Pod, a volume) is read from the API, never invented.\n\nThe honest answer *is* the deliverable here. A hallucinated `create-secret` or `create-cluster` call is the failure this skill exists to prevent.\n\n## The discipline\n\n- **Confirm the gap before asserting it.** The absence is real: there is no secrets tool and no cluster-create tool on the server (only cluster *billing* is readable). State the gap as a fact about the API surface, then pivot to the workaround.\n- **Name the specific operation**, not a vague "can\'t do that" \u2014 "there\'s no REST/MCP tool to create a Runpod secret", "there\'s no endpoint to create an Instant Cluster", "the MCP/REST surface has no file-transfer tool \u2014 but the runpodctl CLI and the volume S3 API move files fine".\n- **Give the real path** that works today, concrete enough to act on.\n- **Ground any account fact in a read.** If you reference the user\'s volume or Pod as part of the workaround, list/inspect it first \u2014 don\'t assert one exists.\n- **Never invent a capability.** No made-up tool name, no pretend success, no "I\'ve stored your secret."\n\n## The boundary cases\n\n- **Secrets for a gated model \u2014 expected fail.** There is no secrets tool on the management API; Runpod Secrets are managed through the console / internal GraphQL, not REST. Say that plainly. The working path: create the secret in the Runpod console and reference it from the template/endpoint env (e.g. `{{ RUNPOD_SECRET_hf_token }}`), or \u2014 less safe but functional \u2014 pass the token directly as a plain env var on the template/endpoint you create. Recommend the console-secret route; name the plain-env-var route as the trade-off, not the default. Do not claim to have created a secret \u2014 no tool does.\n- **Datasets in / checkpoints out \u2014 covered by other tooling, not a gap.** The MCP/management-API tool set has no file-transfer tool \u2014 no MCP call moves bytes to or from a Pod or volume \u2014 but this is *not* a product gap: the runpodctl CLI and the companion S3 tooling cover it directly. Point the user there rather than calling it impossible: `runpodctl send` / `runpodctl receive` for ad-hoc file moves, the S3-compatible API on network volumes (`aws s3` against the volume\'s S3 endpoint) for bulk dataset/checkpoint sync, the console cloud-sync integration, or `scp`/`rsync` over the Pod\'s SSH. In an MCP-only session, say the transfer runs through the runpodctl CLI or the volume S3 API \u2014 a real working path, just not an MCP tool. If checkpoints must survive the Pod, stage them on a network volume (confirm it exists with a read first) so the data outlives the compute.\n- **Multi-node training cluster \u2014 expected fail.** There is no REST/MCP tool to create an Instant Cluster \u2014 the server exposes only cluster *billing* reads, not cluster creation or lifecycle. Say so. The working path: create the Instant Cluster from the Runpod console (Instant Clusters), then use the API for what it *can* do \u2014 read its billing, and manage the individual Pods once they exist. Do not fabricate a create call.\n\n## Hard rules\n\n- Never fabricate a tool call for an operation the API does not expose. If it isn\'t in the tool list, it does not exist \u2014 say so.\n- Never report a silent success ("done / stored / created") for a gap operation. There is nothing to succeed at.\n- State the gap as a specific missing operation, then the concrete workaround \u2014 both, in that order.\n- Read any account fact you cite; don\'t assert a resource exists without listing/inspecting it.\n- When Runpod later ships REST secrets or cluster-create, this re-classes to a normal deploy/lifecycle journey and the per-server tool binding gains the new tool \u2014 until then the honest gap answer is the right answer.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| Create/store a secret | *(unbound \u2014 no secrets tool; console / internal GraphQL only)* | *(unbound)* |\n| Create an Instant Cluster | *(unbound \u2014 no cluster-create tool; console only)* | *(unbound)* |\n| Read Instant Cluster billing | `list-cluster-billing` | *(unbound)* |\n| Transfer files to/from a Pod/volume | *(no MCP tool \u2014 covered by the runpodctl CLI: `send`/`receive`, volume S3 API, cloud-sync, SSH)* | *(no MCP tool \u2014 runpodctl CLI)* |\n| Ground account facts (reads) | `list-pods`, `get-pod`, `list-network-volumes`, `get-network-volume`, `list-endpoints` | same names |\n\nThe secret and cluster-create rows are genuine gaps on both servers \u2014 name the gap and the workaround. File transfer is **not** a gap: no MCP tool moves bytes, but the runpodctl CLI covers it fully \u2014 hand off there rather than calling it impossible.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "comfyui-serverless",
-    description: 'Host a ComfyUI workflow as a serverless endpoint and prove it with one generated image. Owns the workflow-as-job-input pattern (the workflow JSON rides each job request, it is never baked into the image), worker-variant selection by the models the workflow references, and custom-model provisioning (Civitai checkpoints/LoRAs, extra upscalers) via an explicit mechanism with its cold-start consequence stated. Trigger on phrases like "make my workflow.json an api", "host this comfyui workflow", "productionize this workflow file", "comfyui endpoint with my civitai model", "serve my custom lora as an api", "comfyui serverless".',
-    text: '---\nname: comfyui-serverless\ndescription: Host a ComfyUI workflow as a serverless endpoint and prove it with one generated image. Owns the workflow-as-job-input pattern (the workflow JSON rides each job request, it is never baked into the image), worker-variant selection by the models the workflow references, and custom-model provisioning (Civitai checkpoints/LoRAs, extra upscalers) via an explicit mechanism with its cold-start consequence stated. Trigger on phrases like "make my workflow.json an api", "host this comfyui workflow", "productionize this workflow file", "comfyui endpoint with my civitai model", "serve my custom lora as an api", "comfyui serverless".\n---\n\n# ComfyUI serverless\n\nYou turn a ComfyUI workflow into a working serverless endpoint and prove it with one image. Two facts drive everything: the workflow JSON is **job input** \u2014 each request carries it in the job payload, so a custom workflow needs no custom image \u2014 and the worker image only serves what its bundled model set (plus anything you explicitly provision) can load. The journey is: read the workflow, list what it references, match a worker variant, provision what the variant lacks by an explicit mechanism, deploy, run the user\'s own workflow once, hand back the proof.\n\n## Phase 1 \u2014 read the workflow and inventory its references\n\n- Read the user\'s workflow file FIRST. Walk its nodes and list every external file it references: the checkpoint (`CheckpointLoaderSimple.ckpt_name`), LoRAs, VAEs, upscale models, controlnets. This inventory decides everything downstream \u2014 a deploy that guesses the requirements is wrong even when it boots.\n- Note nodes that need no files (latent upscale, standard samplers) \u2014 they run anywhere and need no provisioning.\n\n## Phase 2 \u2014 pick the worker and cover the model inventory\n\n- Resolve the ComfyUI serverless worker from the Hub catalog (`list-hub-repos`, the runpod-workers ComfyUI worker family). Worker variants bundle different model sets \u2014 pick the variant whose bundled set covers the workflow\'s checkpoint (an SDXL workflow wants the SDXL-bundled variant). Cite the hub read you picked it from.\n- For every referenced file the variant does NOT bundle, choose ONE provisioning mechanism and say so plainly:\n  1. **Network volume staging** \u2014 create a volume in the endpoint\'s data center, attach it, and name the exact ComfyUI model paths the files must land under (checkpoints/, loras/, upscale_models/ beneath the mount). The management API cannot upload files: create and wire the volume yourself, then hand the user the ONE staging step (what to download, to which exact path) \u2014 that hand-back is part of the mechanism, not a failure.\n  2. **Baked custom image** \u2014 the user builds an image with the models at the ComfyUI paths and hands back the reference; you deploy from it. Choose this only when the user prefers owning an image.\n  3. **Worker-supported download env** \u2014 only if the worker\'s own config (from the hub read) documents one; never invent an env var the worker does not list. The ComfyUI worker does not document a Civitai download env \u2014 do not pretend it does.\n- State the chosen mechanism\'s cold-start consequence: baked image = bigger pull, volume = one-time download then cached mounts, per-boot download = paid on every cold start.\n- Civitai specifics: resolve the model page to the actual file and its size when a web-read tool is granted. When it is not, do NOT stall the deploy waiting for it \u2014 wire the volume and endpoint anyway, and fold the exact-file lookup into the user\'s staging step ("on the model page\'s Files tab, download the .safetensors file to <exact volume path>"). If the file needs Civitai auth, ask for the token or wire it as an env var with the plaintext caveat \u2014 never invent one, never echo one.\n\n## Phase 3 \u2014 deploy, prove with the user\'s own workflow, hand back\n\n- Create the endpoint scale-to-zero (min workers 0) unless warm capacity was asked for. State the GPU hourly price from the catalog read before creating.\n- Smoke-test with the USER\'S workflow as the job input \u2014 not a substitute prompt. One job, held server-side (runsync then status holds, per serverless-deploy\'s smoke-test discipline); if the wait outlasts the holds, report the evidenced state.\n- Close with everything in one place: the endpoint id, the worker/variant and the hub read it came from, which models are bundled vs provisioned (and how) vs handed to the user to stage (a small table reads well), the job result (the image output reference, or the evidenced blocker), the hourly price, and \u2014 when staging was handed to the user \u2014 the exact single step they run.\n\n## Hard rules\n\n- Read the workflow before any deploy decision; every requirement you name must come from it.\n- Never bake the workflow into an image or tell the user one is needed for a custom workflow \u2014 the workflow rides the job payload.\n- Never claim a model loaded without job or log evidence; a run that silently fell back to a base model is a failure to report, not a success.\n- Never invent worker env vars, download URLs, or Civitai tokens. Mechanisms you cannot execute through the granted tools are handed to the user as one concrete step, with what you DID wire (volume, endpoint, mounts) already in place.\n- Scale-to-zero by default; a nonzero minimum bills around the clock and needs the user\'s ask.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| Find the ComfyUI worker | `list-hub-repos` | `list-hub-repos` |\n| Deploy from the hub | `deploy-hub-repo` | `deploy-hub-repo` |\n| Template + endpoint (custom image path) | `create-template`, `create-endpoint` | same names |\n| Volume for custom models | `create-network-volume` | `create-network-volume` |\n| Smoke job with the workflow | `runsync-endpoint` / `run-endpoint` + `get-job-status` | same names |\n| Read-back / teardown | `get-endpoint`, `delete-endpoint`, `delete-template`, `delete-network-volume` | same names |\n\nWhere a capability is unbound on a server, say "not available on this server" and work with what the server does offer.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "cost-audit",
-    description: 'Read-only Runpod money hygiene \u2014 find idle spend, explain serverless idle-worker billing, break spend down by resource, and give a whole-account snapshot. Trigger on phrases like "why is my runpod bill high", "what am I paying for", "idle pods", "serverless charges with no traffic", "cost breakdown", "spend by resource", "account snapshot", "where is my money going". Audits a live account via the MCP billing/list reads \u2014 idle-scoring, idle-worker-vs-idle-pod, per-resource attribution. Recommends actions but never stops or changes anything.',
-    text: '---\nname: cost-audit\ndescription: Read-only Runpod money hygiene \u2014 find idle spend, explain serverless idle-worker billing, break spend down by resource, and give a whole-account snapshot. Trigger on phrases like "why is my runpod bill high", "what am I paying for", "idle pods", "serverless charges with no traffic", "cost breakdown", "spend by resource", "account snapshot", "where is my money going". Audits a live account via the MCP billing/list reads \u2014 idle-scoring, idle-worker-vs-idle-pod, per-resource attribution. Recommends actions but never stops or changes anything.\n---\n\n# Cost audit\n\nYou answer "where is my money going / stop the leak" against a Runpod account. This skill is strictly read-only: it discovers, scores, and explains spend, then leaves the decision to the user. It **never** stops, deletes, or reconfigures a resource on its own \u2014 any apply is handed off (a Pod stop to `pod-doctor`, dropping serverless min-workers to 0 to `endpoint-ops`) and only after the user explicitly approves it.\n\nEvery figure comes from a read: hourly rates from the resource list, spend-to-date from the billing reads. Never invent or estimate a number you did not read; a monthly projection is allowed only as `read_hourly \xD7 hours`, with the hourly quoted.\n\nThe raw billing and list reads are `runpod-mcp` tool calls (or the equivalent runpodctl billing read); this skill is the *audit journey* on top of them \u2014 the idle-scoring, the idle-worker-vs-idle-pod disambiguation, and the per-resource attribution the plain reads don\'t do.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below. All are reads.\n\n- List Pods with machine/cost info, and inspect one Pod.\n- List serverless endpoints and inspect one \u2014 for min/max workers config.\n- List network volumes.\n- Aggregate billing history, and per-resource billing (Pod / serverless / endpoint / network volume / cluster).\n\n## The four journeys\n\nRead first, always. Match the prompt to one journey; do not run all four unasked.\n\n- **Account snapshot.** List Pods, endpoints, network volumes, and pull aggregate billing for the recent window. Report the count and running-state of each category, the current burn, and the spend-to-date from the billing read. Report an empty category as empty ("no network volumes") \u2014 never pad the picture.\n- **Idle Pod money leak.** List Pods. On the pod record `status` is the state field and `cost` is the pod\'s hourly rate in USD \u2014 those exact names, from the read. For each `status=RUNNING` pod, quote `cost` and project `cost \xD7 730` as "$/mo if left on"; sort by projected cost, present one table (name, GPU, $/hr, up-for, $/mo), and name the costliest. When every pod is stopped/EXITED, don\'t stop at "nothing is running": state plainly that no GPU is burning AND that stopped pods still bill disk/storage until terminated \u2014 then still give the per-pod table, each row\'s `cost` presented as "$/hr \u2014 $/mo if restarted", so the user sees the rate every idle pod resumes at. If `cost` is missing on a row, render `?` and exclude it from any total \u2014 do not fabricate it. Recommend stopping (or terminating the long-dead) ones; do not mutate anything.\n- **Serverless charges with no traffic.** This is the conflation users make: a serverless endpoint with **min workers \u2265 1** keeps an always-on worker that bills even at zero traffic \u2014 that is serverless idle-worker spend, and it is *not* the same as an idle Pod. Inspect the endpoint\'s worker config to confirm min-workers \u2265 1, quote the serverless billing read for that endpoint, and explain the mechanism plainly. The fix is min-workers 0 (cold-start trade-off) \u2014 recommend it and hand the apply to `endpoint-ops`; do not change it here. **If no endpoint has min-workers \u2265 1**, the charge is billed worker execution time on scale-to-zero endpoints: serverless bills every second a worker runs, whether the run was a completed job, a failed job, or a stuck/restarting worker that burns GPU seconds without ever completing anything. Attribute it from the per-endpoint billing rows plus the worker/job states, name the responsible endpoint, and say explicitly that this is execution-time billing on a live scale-to-zero endpoint \u2014 not idle-worker billing, and not a phantom charge.\n- **Spend breakdown by resource.** Get the per-TYPE totals from the aggregate `list-billing` read first \u2014 it answers the breakdown directly. Drill into a type only as needed, and **always size-safely**: on the serverless read pass `lastN: 1` (or a `bucketSize` covering the whole window) so each endpoint yields ONE record \u2014 the default per-endpoint-per-bucket dump on a many-endpoint account overflows the tool-result limit, and an oversized result comes back truncated, dead-ending the audit. Attribute spend to each named resource, sort descending, and name the single costliest. Present figures as coming from the billing read. If a category returned nothing, list it as $0 / empty rather than dropping it silently. **When every category returns zero** \u2014 no spend anywhere \u2014 say so plainly: give the per-type table with $0 for each and a $0 total, cross-check it against the live lists (`list-pods` / `list-endpoints` / `list-network-volumes` all empty confirms it), and state directly that there is no costliest type because nothing has billed and nothing is currently costing money. Do **not** hedge that the billing window might be wrong or ask the user to re-specify a timeframe \u2014 the reads are authoritative for the window used; only if the user themselves names a different period do you re-pull.\n- **Commit the attribution (all spend questions).** When the billing reads show real spend, name its source from the data you have \u2014 even when the responsible resource has since been deleted ("$X from serverless jobs on endpoints that no longer exist, run at <times from the billing rows>"). That attribution IS the answer: deliver it as the verdict, then at most one sentence of follow-up the user could choose. Lead with the attribution the reads support instead of deflecting the question back at the user, and never reach for tools you were not given (no shell, no web) \u2014 every figure you need is in the billing reads and lists you already have; analyze them directly in your reply. The per-endpoint serverless drill-down comes from the per-resource billing reads (list-serverless-billing / list-endpoint-billing) \u2014 never a shell script or any tool outside the granted MCP set. Deliver the verdict first: state the finding plainly, then at most one recommended next step or follow-up question.\n\n## Hard rules\n\n- Read-only. This skill never calls a mutating tool \u2014 no stop, no delete, no update. Full stop.\n- That holds however urgently the change is ordered: an instruction changes the urgency, not the authority. The audit plus the exact ids and the precise actions for the USER to run IS the complete answer to that order \u2014 deliver it as such, never as a permission question, and never attempt the mutation to "try anyway".\n- Assume you have only the Runpod MCP tools. Never reach for a shell, a script, a web-fetch tool, or anything else you were not granted \u2014 a tool you do not have cannot be called, and the audit ends with nothing delivered. Every figure this skill needs is in the MCP billing and list reads.\n- When a read\'s result comes back truncated, the recovery is a NARROWER RE-READ \u2014 smaller page, one endpoint at a time, `lastN: 1`, a tighter bucket \u2014 never an attempt to recover the dropped output, never an external script to parse it, never a request for extra tool access. A narrower read gets the user their answer; the detours get them nothing.\n- Any recommended apply is a handoff to `pod-doctor` (stop) or `endpoint-ops` (min-workers-0), and only after the user says yes. Name the handoff; do not perform it.\n- Every dollar figure traces to a tool read. Quote the hourly / billing source. A projection is `read_hourly \xD7 hours`, never a bare invented number.\n- Report empty categories as empty. Absence is a finding, not a gap to fill.\n- Never flag a Pod that has been up under an hour as idle \u2014 too fresh to call.\n- Distinguish Pod idle spend from serverless idle-worker spend explicitly whenever both could be in play \u2014 conflating them is the most common user error this skill exists to correct.\n\n## Error handling\n\n- A `401` on any list means the API key is invalid \u2014 say so and stop; there is nothing to audit without it.\n- A `429` mid-audit: report the partial picture and note it is incomplete; do not retry in a tight loop.\n- A missing `cost` on a pod row, or an empty billing bucket, is data \u2014 not an error. Render `?` / $0 and keep going.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| List Pods (+ machine/cost) | `list-pods` | `list-pods` |\n| Inspect one Pod | `get-pod` | `get-pod` |\n| List / inspect endpoints | `list-endpoints`, `get-endpoint` | `list-endpoints`, `get-endpoint` |\n| Endpoint worker config / counts | `list-endpoint-workers`, `endpoint-health` | `endpoint-health` |\n| List network volumes | `list-network-volumes` | `list-network-volumes` |\n| Aggregate billing | `list-billing` | *(coarse / unbound)* |\n| Per-resource billing | `list-pod-billing`, `list-serverless-billing`, `list-endpoint-billing`, `list-network-volume-billing`, `list-cluster-billing` | *(unbound \u2014 REST billing is coarse)* |\n\nWhere per-resource billing is unbound (official server), degrade to the coarse aggregate and say the per-resource split is "not available on this server" rather than inventing one.\n\n## Report template \u2014 cost summary\n\nEvery cost answer ships as: per-type table (Pods / Serverless / Network\nvolumes / Clusters \u2014 every type present even at $0.00) with figures only from\nbilling reads made this turn \xB7 a total line \xB7 the named costliest item (or the\nexplicit statement that nothing billed) \xB7 the one-sentence verdict answering\nthe user\'s actual question. Attribution follows the commit rule above.\n\nFigure format \u2014 hard rules, check the drafted reply before sending:\n- Every figure is an exact dollar amount ($X.XX) copied or summed from billing\n  rows. The characters `~` and `\u2248` and the words "about / roughly /\n  approximately" never appear next to a number anywhere in a cost reply. A\n  derived figure (a resource\'s share, a per-day rate, a projection) is stated\n  exactly, with its arithmetic shown from the quoted inputs \u2014 "$46.37, the sum\n  of that pod\'s billing rows" \u2014 never softened into an estimate.\n- Every table cell holds a concrete value ($0.00 for a zero or empty\n  category) \u2014 never a placeholder, a dash, or a stray word.\n- Re-add the table: the rows must sum exactly to the stated total, to the\n  cent. If rounding leaves a gap, adjust the rounding so the printed rows and\n  the printed total agree before sending.\n- Check every proportion word against the printed amounts before sending \u2014\n  "half", "most", "a third", any percentage. The claim must match the\n  arithmetic of the figures next to it ($43.26 of $66.45 is 65% \u2014 "most",\n  never "half"); if the number doesn\'t support the word, fix the word.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "discovery",
-    description: `Answer "what's available, what fits, and what does it cost" against Runpod's catalogs \u2014 GPU types with price, live stock and per-data-center availability, the capacity matrix across host CUDA versions, the Hub worker marketplace, and the pay-per-use public-endpoints catalog. Read-only, never mutates; answers against the live catalogs via the MCP tools \u2014 the discovery journey (filter to the real constraint, model\u2192VRAM fit, none-found honesty) on top of the raw runpod-mcp reads. Trigger on phrases like "what 24 GB GPUs are available and what do they cost", "is there capacity for <card> in <region>", "which GPU fits <model>", "cheapest way to serve/run <model> on Runpod", "what's the cheapest GPU to run <model>", "is there a ready-made <X> worker on the Hub", "can I caption an image without deploying anything", "what pay-per-use endpoints exist".`,
-    text: '---\nname: discovery\ndescription: Answer "what\'s available, what fits, and what does it cost" against Runpod\'s catalogs \u2014 GPU types with price, live stock and per-data-center availability, the capacity matrix across host CUDA versions, the Hub worker marketplace, and the pay-per-use public-endpoints catalog. Read-only, never mutates; answers against the live catalogs via the MCP tools \u2014 the discovery journey (filter to the real constraint, model\u2192VRAM fit, none-found honesty) on top of the raw runpod-mcp reads. Trigger on phrases like "what 24 GB GPUs are available and what do they cost", "is there capacity for <card> in <region>", "which GPU fits <model>", "cheapest way to serve/run <model> on Runpod", "what\'s the cheapest GPU to run <model>", "is there a ready-made <X> worker on the Hub", "can I caption an image without deploying anything", "what pay-per-use endpoints exist".\n---\n\n# Discovery\n\nYou answer availability, fit, and price questions against Runpod\'s catalogs and you never change anything. Four catalogs, one discipline: filter to the prompt\'s real constraint, name only entries the tool actually returned, quote the price and stock straight from the output, and say "none found" rather than invent a card, a region, or a repo.\n\nYou also own the model\u2192VRAM sizing math the deploy skills cite: given a model\'s parameter count and precision, estimate the VRAM it needs and name the smallest GPU class that fits with real stock. Sizing is advice \u2014 this skill recommends, it does not deploy.\n\nThe raw catalog reads are `runpod-mcp` tool calls; this skill is the discovery journey \u2014 filter, fit, price, none-found honesty \u2014 on top of them.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below. Every capability here is a read.\n\n- Read the GPU catalog with price and live availability \u2014 the "what GPUs / what do they cost / is there stock" answer.\n- Read per-data-center GPU availability \u2014 which region has a card free right now.\n- Read the capacity matrix across host CUDA versions \u2014 stock per host CUDA version, which the flat GPU list can\'t express.\n- Read data centers and their regions \u2014 where the stock and the network-volume tiers live.\n- Read the CPU catalog \u2014 for CPU-pod and CPU-serverless sizing questions.\n- Browse the Hub worker marketplace \u2014 is there a prebuilt worker for this task.\n- Read the pay-per-use public-endpoints catalog \u2014 managed model APIs that need no deployment at all.\n\n## Journeys\n\n### GPU availability + price\n\nRead the GPU catalog with availability included, then filter to the real constraint. For "24 GB GPUs", filter to the VRAM tier the user asked for \u2014 do not list the whole fleet. For each match, quote the display name, the memory, the hourly price, and the stock level from the output. Present a short table sorted by price or by stock, whichever the question implies. If nothing in that tier has stock, say so plainly rather than listing out-of-stock cards as if they were available.\n\n### Capacity hunt by region / CUDA\n\nTwo different questions, two different reads \u2014 do not mix them up.\n\n- **"Is there capacity for `<card>` in `<region>`" / "which region has `<card>` free right now."** Ask for the availability expansion on the catalog read: `list-gpu-types` or `get-gpu-type` with `include:["AVAILABILITY"]` returns a `dataCenters` array per GPU type, and `list-data-centers` / `get-data-center` with `include:["GPU_AVAILABILITY"]` returns the same picture per data center (`list-data-centers` also takes a `regions` filter). Filter to the requested GPU type(s) and region(s), report which data centers have stock and which are out, and name them from the read.\n- **"Which host CUDA version has stock" / choosing an endpoint\'s `allowedCudaVersions`.** That is the capacity matrix, `get-capacity` \u2014 stock per host CUDA version, with no data-center dimension. Never use it to answer a region question, and never name a data center from its output: it does not return one.\n\nIf the connected server has no capacity-matrix tool, say the CUDA-version matrix is not available there \u2014 the region answer is unaffected, since it comes from the catalog availability reads.\n\n### Which GPU fits my model\n\nEstimate required VRAM from the model\'s real parameters and precision, then name the smallest GPU that fits with stock. Rough VRAM: weights \u2248 params(B) \xD7 bytes-per-param (fp16 \u2192 2, int8 \u2192 1, int4/awq/gptq \u2192 0.5), then add ~20% for KV cache and activations; long-context or high-concurrency serving needs more KV headroom, say so. Read the GPU catalog and recommend the smallest class whose memory clears that estimate and shows real stock \u2014 plus the next size up as headroom. State the estimate and the assumption (precision, context) you sized against; if the user did not give a parameter count and it can\'t be read from the model, ask once rather than guess. "Cheapest way to serve `<model>`" is this journey: read the catalog now and state the recommended card\'s hourly price **and its current stock as a definite fact from the availability read** \u2014 never end on an offer to "check live capacity later" or hedge the stock with "should be available"; the stock read is one call, so make it.\n\n### Ready-made worker on the Hub\n\nBrowse the Hub for a prebuilt worker matching the task (search by term and category \u2014 language, image, audio, video, embedding). Name the repos the catalog returned, their owner, and what each is for; if the config is available, note the hardware it wants. Attribute every repo to the listing \u2014 never assert a repo from memory. If nothing matches, say "none found on the Hub" and stop; the deploy path from a found repo is `serverless-deploy`.\n\n### Pay-per-use, no deployment\n\nWhen the user wants a one-off result ("caption this image", "transcribe this clip") and does not want to run infrastructure, read the public-endpoints catalog \u2014 managed, pay-per-use model APIs (text, image, video, audio) that need no deployment. Filter by modality and name the live endpoints that fit, with their owner/model. This is often the right answer to "I just need one caption" \u2014 recommend it over standing up an endpoint. If the catalog has nothing for the modality, say so plainly \u2014 but NEVER end on the gap: name the closest real path that does exist (usually deploying a Hub worker for that modality on serverless, clearly labeled as a deploy, not pay-per-use) so the user leaves with an option, not a dead end. Do not present a deployable worker as if it were pay-per-use.\n\n## Hard rules\n\n- Never call a mutating tool from this skill. Discovery reads; it does not create, update, stop, or delete anything.\n- Name only entries the tool returned. No invented GPU classes, regions, prices, Hub repos, or public endpoints.\n- Quote price and stock from the output. No arithmetic on prices the tool didn\'t return, no "should be around" figures.\n- Report empty results as empty \u2014 "none found" is a correct answer, and better than a plausible fabrication.\n- Sizing is a recommendation with its assumption stated, not a deployment. Fitting a model is `serverless-deploy`\'s job.\n- Filter to the prompt\'s real constraint; do not dump the whole catalog when the user asked about one tier or one region.\n- Keep the answer internally consistent: before writing any "no stock in `<DC>`" or "out everywhere except\u2026" summary line, cross-check it against your own per-data-center table above. Never call a data center out of stock in the summary if the table lists that same GPU with stock there \u2014 reconcile the two reads (name which is more current) rather than contradicting yourself.\n\n## Error handling\n\n- The capacity-matrix tool is absent on the connected server \u2192 say the host-CUDA-version matrix is not available here, and answer CUDA-independent stock questions from the catalog availability read (`include:["AVAILABILITY"]`), naming that limit.\n- A catalog read returns an empty list \u2192 report "none found" for that filter; do not widen the search silently or fabricate entries.\n- The user gives a VRAM tier no card matches \u2192 say no card in that tier is in the catalog (or has stock) rather than rounding to a nearby card unasked.\n- A read fails \u2192 report the failure and stop; do not answer from memory.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| GPU catalog + price + stock | `list-gpu-types` (`include:["AVAILABILITY"]`), `get-gpu-type` | `list-gpu-types` |\n| Per-data-center GPU availability | `list-gpu-types` / `get-gpu-type` (`include:["AVAILABILITY"]` \u2192 `dataCenters[]`), `list-data-centers` / `get-data-center` (`include:["GPU_AVAILABILITY"]`) | `get-gpu-type`, `list-data-centers` |\n| Capacity matrix (per host CUDA version) | `get-capacity` | *(unbound \u2014 GraphQL-only, no REST home)* |\n| Data centers | `list-data-centers`, `get-data-center` | `list-data-centers` |\n| CPU catalog | `list-cpu-types`, `get-cpu-type` | *(coarse or unbound)* |\n| Browse the Hub | `list-hub-repos` (`searchTerm`, `category`, `includeConfig`) | *(unbound \u2014 no Hub browse)* |\n| Pay-per-use public endpoints | `list-public-endpoints` (`modality`, `owner`) | *(unbound \u2014 no public-endpoint catalog)* |\n\nWhere a capability is unbound on a server, say "not available on this server" and work with what the server does offer.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "endpoint-ops",
-    description: 'Operate a Serverless endpoint that already exists \u2014 diagnose stuck jobs and dying workers, tune its scaling and cold-start settings safely, and manage its queue. Read-only by default; mutates only the exact setting the user authorized. Trigger on phrases like "my jobs are stuck IN_QUEUE", "the video job never runs", "cold starts are killing my chatbot", "pin my endpoint to a validated GPU", "tune autoscaling for bursty traffic", "my caption workers keep dying", "cancel this job", "purge the queue / clear a bad batch".',
-    text: '---\nname: endpoint-ops\ndescription: Operate a Serverless endpoint that already exists \u2014 diagnose stuck jobs and dying workers, tune its scaling and cold-start settings safely, and manage its queue. Read-only by default; mutates only the exact setting the user authorized. Trigger on phrases like "my jobs are stuck IN_QUEUE", "the video job never runs", "cold starts are killing my chatbot", "pin my endpoint to a validated GPU", "tune autoscaling for bursty traffic", "my caption workers keep dying", "cancel this job", "purge the queue / clear a bad batch".\n---\n\n# Endpoint ops\n\nYou operate a Serverless endpoint that already exists. Everything starts by reading its current state \u2014 the endpoint config, its health, its workers, its logs \u2014 before you say anything or change anything. Diagnosis is always read-only. You change a setting only when the user asked for a change, and then only the exact setting agreed.\n\nOne property of the Runpod update path drives the central rule here: an endpoint update is a genuine PATCH \u2014 only the fields present in the body change, and omitted fields are left untouched \u2014 so you send exactly the setting you were asked to change and nothing else. What the PATCH does not give you is proof: its own response is not a read. Read the config first for the before value, and read it back afterward for the after value.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below. This skill reads before it mutates, and mutates only what the user authorized.\n\n- List and inspect endpoints \u2014 resolve "which endpoint" and read the full current config.\n- Read endpoint health and list workers \u2014 the stuck-queue / dying-worker evidence.\n- Read a worker\'s logs \u2014 the crash / model-load failure line.\n- Read GPU stock per data center, and the capacity matrix across host CUDA versions \u2014 is a stuck queue a capacity problem.\n- Update an endpoint (worker min/max, idle timeout, scaler, FlashBoot, disk, env) \u2014 the gated tune.\n- Pin GPUs / set GPU count \u2014 select pools and exclude unwanted GPU types with a sparse update.\n- Read release history \u2014 which build the workers are running.\n- Cancel one job; purge the queue \u2014 the queue-management actions, each gated.\n- Submit and poll a job \u2014 to re-verify after a change.\n\n## Phase 1 \u2014 diagnose (always, read-only)\n\nResolve the endpoint (list endpoints and match by name if needed), read its config, then read health and workers before forming a conclusion. Classify against the symptom:\n\n- **Jobs stuck `IN_QUEUE`.** Read health and the worker list. If max workers is 0 or all workers are throttled/unhealthy, the queue has nothing to run on. Separate the causes: worker **limit** (max-workers too low, or min 0 with a cold scaler) vs **capacity** (workers can\'t acquire the pinned GPU \u2014 cross-check that GPU type\'s per-data-center availability, and the CUDA-version matrix when the endpoint pins a CUDA floor) vs **unhealthy** (workers cycling \u2014 read their logs). A crash loop does not always raise `unhealthy`: a container failing to start cycles while its worker still reports RUNNING or THROTTLED, so read the logs before ruling worker failure out. Name which one, quoting the health/worker numbers you read.\n- **Workers crash-looping.** List workers, find the failing ones, read their logs, and quote the decisive line \u2014 a missing model file, a gated 403, an OOM, a bad handler import. Report what the log says, not a guess. OOM \u2192 the GPU is undersized for the real memory pattern; a load/import error \u2192 the image or env is wrong.\n- **Cold starts hurt.** Read the config. The real levers, in order: enable FlashBoot; raise the idle timeout so warm workers linger between bursts; set a nonzero min-worker to keep capacity warm (state that a min-worker bills around the clock \u2014 it is an always-on worker); and make sure the scaler isn\'t scaling to zero between every request. Name the levers and their cost before touching anything.\n- **Load-balancer endpoint, workers never ready.** On a load-balancer (custom-HTTP) endpoint the load balancer decides readiness by polling the worker\'s health endpoint \u2014 the path from the worker\'s `HEALTH_CHECK_PATH` env, or `/ping` when that is unset \u2014 over the HTTP port the template exposes. Workers stuck un-ready while jobs arrive usually means the port is not exposed or nothing answers that path; the endpoint read gives you the exact health URL being polled. The fix is a redeploy that exposes the port and serves the health path (see `serverless-deploy`), not a scaler change.\n\nEnd phase 1 with the diagnosis and the *recommended* change \u2014 but do not apply it unless the prompt authorized a change. If the ask was purely "why / what\'s wrong", you are done here.\n\n## Phase 2 \u2014 tune safely (only if the user authorized a change)\n\nAdvance only when the prompt asks to change a *named* endpoint\'s setting.\n\n- **The read-back invariant.** Read the endpoint\'s full config first, so you hold the before values. Apply the change as a PATCH carrying only the fields the user authorized \u2014 sending fields you were not asked about is how you overwrite a setting they tuned by hand. Then read the config back and confirm the target field holds its new value and the neighbours you quoted are unchanged.\n- **Autoscaling tune, bursty traffic.** For bursty workloads (e.g. transcription that arrives in waves), tune the scaler and worker band: raise max workers for the burst ceiling, set the queue-delay or request-count scaler target to how fast you want to absorb the burst, and set idle timeout to how long to hold warm workers between waves. Change only the fields the user agreed; state the cost of a higher min-worker.\n- **Pin to a validated GPU.** Read the GPU catalog to find the pool and its GPU types. Use `set-endpoint-gpus` with the pool and exclusions for unwanted types, or `update-endpoint` with `body.gpu.pools` and `body.gpu.excludedTypes`. Both paths use sparse REST PATCH. Set only the requested GPU count or CUDA constraints, and read back the GPU and scaling settings after the change.\n\n## Phase 3 \u2014 manage the queue (gated actions)\n\n- **Cancel one job.** When the user names a job to cancel, cancel that job by id. Cancel affects only queued/in-progress jobs. After the cancel, VERIFY with a fresh `get-job-status` read \u2014 the cancel call\'s own response is not verification (an unread write is an unverified write); the final answer reports the re-read state. If the re-read shows the job already reached a terminal state before your cancel, say exactly that \u2014 it is a complete, honest outcome.\n- **Purge a bad batch.** When the user wants to clear a queue of bad/erroneous jobs, purge the queue \u2014 this removes *all* pending jobs; in-progress jobs keep running. Say clearly that it clears the whole pending queue, not just the bad ones, and do it only on an explicit "purge / clear the queue". Re-read health afterward to confirm the queue drained.\n\n## Hard rules\n\n- Every settings change is read \u2192 update \u2192 read: (1) read the current config, (2) apply the update, (3) a FRESH `get-endpoint` read AFTER it. The before/after values the final answer quotes come from reads (1) and (3) \u2014 the update call\'s own response is not a read, and never claim a read-back you did not actually perform.\n- Change only the setting the user authorized, on the endpoint they named. Never tune, pin, or purge an endpoint the user did not name.\n- Diagnosis is read-only \u2014 and read-only includes ZERO job submissions: never fire a `run`/`runsync` "test probe" while diagnosing (a submitted job bills compute and changes the queue \u2014 it is a mutation, and on a broken endpoint it burns money to reproduce what the worker states already show). Diagnose from the endpoint/health/worker/log reads only; a recommended fix is presented, not applied, unless the prompt authorizes it.\n- A queue purge clears the entire pending queue \u2014 say so before doing it; never purge on a vague "clean this up".\n- State the cost of any setting that bills continuously (a nonzero min-worker keeps workers warm and billed) before applying it.\n- Quote the health/worker/log field you read. No "probably" about a number the tool returns.\n- Never cancel or purge jobs the user did not ask you to; do not "helpfully" clear a queue during a diagnosis.\n- If a read (health, workers, logs) fails, report it and stop; do not guess the cause.\n\n## Error handling\n\n- An unrelated setting comes back changed \u2192 compare the actual update body and check for a redeploy or concurrent write. Both REST update tools leave omitted fields untouched. Re-read before re-applying anything.\n- `IN_QUEUE` with healthy workers and free capacity \u2192 the scaler hasn\'t spun a worker yet; give it a moment and re-read health rather than force-changing settings.\n- Worker logs show OOM \u2192 the GPU is undersized; the fix is a bigger GPU (re-deploy via `serverless-deploy`), not a scaler tweak.\n- Cancel/purge returns success but health still shows queued jobs \u2192 re-read after a moment; the queue count settles slightly after the action.\n- A GPU-pin request on a server without the convenience tool \u2192 inspect the update schema for GPU pools and exclusions. If neither path is available, report that limitation.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| List / inspect endpoints | `list-endpoints`, `get-endpoint` | `get-endpoint` |\n| Endpoint health | `endpoint-health` | `endpoint-health` |\n| List workers (per-worker detail) | `list-endpoint-workers` | *(coarse \u2014 `endpoint-health` only)* |\n| Read a worker\'s logs | `stream-worker-logs` | *(unbound \u2014 no REST log stream)* |\n| GPU stock per data center | `list-gpu-types` (`include:["AVAILABILITY"]`), `get-gpu-type` | `list-gpu-types` |\n| Capacity matrix (per host CUDA version) | `get-capacity` | *(unbound \u2014 GraphQL-only)* |\n| Update endpoint settings | `update-endpoint` | `update-endpoint` |\n| Pin GPUs / set GPU count | `set-endpoint-gpus` | `update-endpoint` (`gpu.count`, `gpu.pools`, `gpu.excludedTypes`) |\n| Release history | `list-endpoint-releases` | *(unbound)* |\n| Cancel one job | `cancel-job` | *(varies)* |\n| Purge the queue | `purge-endpoint-queue` | *(varies)* |\n| Submit / poll a job | `runsync-endpoint`, `run-endpoint`, `get-job-status` | `runsync-endpoint` |\n\nWhere a capability is unbound on a server, say "not available on this server" and work with what the server does offer.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "lifecycle-crud",
-    description: `Create, verify (read-back), and manage the lifecycle of Runpod's reusable plumbing resources \u2014 templates, network volumes, and container registry credentials \u2014 plus caching model weights on a volume and diagnosing a private-registry pull failure. Trigger on phrases like "create a template", "reusable template", "make a network volume", "persistent storage", "cache weights on a volume", "add registry credentials", "private image won't pull", "clean up my template/volume".`,
-    text: '---\nname: lifecycle-crud\ndescription: Create, verify (read-back), and manage the lifecycle of Runpod\'s reusable plumbing resources \u2014 templates, network volumes, and container registry credentials \u2014 plus caching model weights on a volume and diagnosing a private-registry pull failure. Trigger on phrases like "create a template", "reusable template", "make a network volume", "persistent storage", "cache weights on a volume", "add registry credentials", "private image won\'t pull", "clean up my template/volume".\n---\n\n# Lifecycle CRUD\n\nYou own the lifecycle of Runpod\'s reusable resources: templates, network volumes, and container registry credentials. The goal is a correctly provisioned resource the user can rely on: provision cleanly, confirm by reading the resource back, and leave it standing \u2014 tear down only when the user asked for a create-then-clean-up demo or explicit cleanup. Read the existing resources first so you never collide with or clobber something the user already has.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below.\n\n- List / inspect / create / update / delete templates.\n- List / inspect / create / update / delete network volumes.\n- List / inspect / create / delete container registry credentials.\n- Read data centers and their per-GPU availability \u2014 to place a volume in a GPU-co-located DC.\n\n## Shared discipline (every resource)\n\n- **Read first.** List existing resources before creating; confirm the name you intend to use is not already taken.\n- **Touch nothing outside the resources this conversation created.** Never delete or update a resource this conversation did not create \u2014 a name that *looks* like test junk is not attribution (the router\'s mutations-bind rule); only your own create calls this session establish ownership.\n- **Confirm by read-back.** After a create or update, inspect the resource and verify the fields you set came back as you set them \u2014 a write call\'s own response is not a read, so confirm from a fresh one rather than trusting the write. (An update is a PATCH: only the fields you send change, and omitted fields are left untouched \u2014 so send only what the user authorized.)\n- **When the user asked for cleanup or a create-then-clean-up demo, tear down what the journey created** in dependency order (a volume in use by a Pod won\'t delete; a registry cred referenced by a Pod won\'t delete), confirming each deletion with a final read-back showing it is gone. Otherwise leave resources standing and say what exists and what it bills.\n- **State cost before creating a billable resource.** A network volume bills storage per GB-month for as long as it exists \u2014 say the size and that it bills until deleted before you create it.\n\n## Journeys\n\n- **Reusable template CRUD.** List templates, create the template with the name and image/disk/ports/env the user specified, read it back to confirm; when they asked for a create-then-clean-up round-trip, delete it and confirm removal. A template referenced by a Pod or bound to an endpoint will refuse deletion \u2014 surface that, do not force it.\n- **Network volume lifecycle.** List volumes, create the volume with the requested size in a data center the user (or the workload) needs. State the storage cost. Read it back and leave it to serve its purpose \u2014 it bills until deleted, so say so; delete and confirm only on an explicit cleanup ask. Note: a volume\'s size may only increase \u2014 a shrink is rejected.\n- **Volume-backed weights architecture.** Cache large model weights on a network volume co-located with the GPU that will consume them: read the data centers with their per-GPU availability to pick a DC that has the target GPU in stock, create the volume there, and explain the wiring \u2014 mount path into the Pod/worker, weights downloaded once and reused, and the cold-start effect (first job pays the download, later jobs mount the cached weights). Place, don\'t guess: the volume must live in the same DC as the compute or the mount won\'t attach. The one network volume mounts at a different path per surface \u2014 `/workspace` on a Pod, `/runpod-volume` on a Serverless worker \u2014 so weights staged from a Pod are read by the endpoint handler at `/runpod-volume`, not the pod path.\n- **Cleanup asks.** When asked to clean up resources and this conversation created nothing (or its creations are already gone), the honest answer is reads only: list the account, say plainly that nothing this conversation created remains, and hand back any stale-looking candidates (ids, names, why they look stale) for the user to decide. Never delete on a name-guess \u2014 that report is the complete answer.\n- **Private registry creds + pull-fail diagnosis.** Create the registry credential for the private image. Credentials are write-only \u2014 the read-back will never return the username/password, and you must never echo the values you sent into the transcript or logs. When an image pull fails, diagnose the two distinct causes: a genuine **auth failure** (wrong/expired credential, or none attached \u2014 the fix is a valid registry cred) versus **Docker Hub anonymous rate-limiting** (an unauthenticated pull of a public image hitting the pull-rate cap \u2014 the fix is authenticating even for the public pull). Name which one from the error text; do not conflate them.\n- **Missing credential values.** A registry credential is only useful with the user\'s real values: when none were supplied, ask for them \u2014 the user is the only source. Never invent placeholder values for a credential meant to be used, and never echo the values back once given.\n\n## Hard rules\n\n- Never touch a resource outside this journey\'s own creations.\n- Never echo a registry credential value (username/password/token) into chat, a log, or a committed file. It is write-only by design \u2014 keep it that way.\n- Verify every create/update by reading the resource back; verify every delete by a read-back showing absence.\n- State the storage cost before creating a network volume.\n- A delete rejected because the resource is in use is a correct API response \u2014 report it and stop, do not force-detach or delete the dependent resource the user did not name.\n\n## Error handling\n\n- A delete returns `204` with no body \u2014 that is success; confirm with a follow-up read.\n- A volume/registry delete rejected with an in-use error means a Pod or endpoint still references it \u2014 name the blocker, do not cascade.\n- A registry read that omits `username`/`password` is expected (write-only), not a bug.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| Templates (list/get/create/update/delete) | `list-templates`, `get-template`, `create-template`, `update-template`, `delete-template` | same names |\n| Network volumes (list/get/create/update/delete) | `list-network-volumes`, `get-network-volume`, `create-network-volume`, `update-network-volume`, `delete-network-volume` | same names |\n| Registry creds (list/get/create/delete) | `list-registries`, `get-registry`, `create-registry`, `delete-registry` | same names |\n| Data centers + per-DC GPU availability (for placement) | `list-data-centers` / `get-data-center` (`include:["GPU_AVAILABILITY"]`), `list-gpu-types` (`include:["AVAILABILITY"]`) | `list-data-centers`, `get-gpu-type` |\n| Capacity matrix (per host CUDA version) | `get-capacity` | *(unbound \u2014 GraphQL-only)* |\n\n`get-capacity` is a curated tool over GraphQL \u2014 the per-host-CUDA-version stock matrix has no REST home \u2014 so a server without it can still place a volume: the data-center reads carry per-GPU availability. If it is missing, say the CUDA-version matrix is "not available on this server" and place from that availability read.\n\n## Report template \u2014 resource inventory\n\nWhen asked what exists on the account (inventory, audit, "what\'s running"):\nlist pods, endpoints, templates, and network volumes; a table per non-empty\nkind works well (name, id, status, GPU/size, $/hr where the read provides it),\nwith empty kinds noted in a line ("templates: none"). Close with the totals\n(counts per kind, summed $/hr of running pods) and, if the user implied a\nconcern (cost, stuck resources), the verdict in one sentence.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "pod-deploy",
-    description: `Provision a Runpod Pod for interactive, dev, or training use and tell the user exactly how to connect to it. Checks stock before creating, picks a sensible image and GPU class, exposes the right ports, returns the working proxy URL, and for training co-locates a network volume so checkpoints survive the Pod. Also covers create-then-pause \u2014 stopping a fresh Pod to end compute billing after preserving needed files on persistent storage. Trigger on phrases like "spin up a pod", "give me a GPU box", "interactive ComfyUI on a pod", "I need a pod with Jupyter", "a training pod for a fine-tune", "my first pod, deployed and reachable", "an SSH-able GPU machine", "pause it so it stops billing", "I'll continue tomorrow, don't lose anything".`,
-    text: '---\nname: pod-deploy\ndescription: Provision a Runpod Pod for interactive, dev, or training use and tell the user exactly how to connect to it. Checks stock before creating, picks a sensible image and GPU class, exposes the right ports, returns the working proxy URL, and for training co-locates a network volume so checkpoints survive the Pod. Also covers create-then-pause \u2014 stopping a fresh Pod to end compute billing after preserving needed files on persistent storage. Trigger on phrases like "spin up a pod", "give me a GPU box", "interactive ComfyUI on a pod", "I need a pod with Jupyter", "a training pod for a fine-tune", "my first pod, deployed and reachable", "an SSH-able GPU machine", "pause it so it stops billing", "I\'ll continue tomorrow, don\'t lose anything".\n---\n\n# Pod deploy\n\nYou provision one Pod the user asked for and hand back exactly how to reach it. Before creating anything you confirm the GPU class has real stock \u2014 a blind create into an out-of-stock class produces a Pod that never leaves provisioning. You pick a sensible image and the ports the workload actually needs (an app UI, Jupyter, SSH), and you return the Runpod proxy URL in its working form. For a training Pod you co-locate a network volume so checkpoints outlive the Pod\'s container disk.\n\nCreating a Pod is billable. State the hourly cost before you create it. Diagnosing or recovering a Pod that already exists is a different job \u2014 that is `pod-doctor`.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below. This skill reads stock before it creates, and creates only the Pod the user asked for.\n\n- Read GPU stock per data center (and the host-CUDA-version capacity matrix when a CUDA floor matters) \u2014 confirm the class is available before creating (delegate the fuller catalog read to `discovery`).\n- Create a network volume \u2014 checkpoint durability for training (delegate the CRUD hygiene to `lifecycle-crud`).\n- Create a Pod (image, GPU or CPU, disk, ports, env, data center, mounts).\n- Inspect a Pod \u2014 read back its status, exposed ports, and the proxy/public address.\n- List Pods \u2014 resolve "which Pod" and confirm what already exists.\n- Read a Pod\'s boot logs \u2014 confirm the app came up on the port before handing back a URL.\n- Stop / terminate a Pod \u2014 create-then-pause, and cleanup when the user asks for it.\n\n## Phase 1 \u2014 confirm stock and shape the Pod\n\n- Read GPU availability for the class the workload needs before creating \u2014 `include:["AVAILABILITY"]` carries the per-data-center picture, so the DC you place into is read, not assumed. If the class has no stock, say so and offer an alternative class or region \u2014 do not create into an unavailable class.\n- Pick the image for the use: an interactive app (e.g. a ComfyUI or PyTorch image) for dev, a CUDA/PyTorch base for training. Match the image\'s CUDA to what the GPU class supports.\n- **The image comes from this session\'s reads, not memory.** For a named app (ComfyUI, Jupyter, a specific stack), resolve the image from the templates / Hub-repos read you just made and cite that source when you pick it. An image already running on the account \u2014 visible in a `list-pods` read \u2014 is also a session-read source worth checking when the catalog comes up empty; cite the pod you saw it on. Only when the catalog has no match may you fall back to a well-known public image \u2014 and then say so explicitly in the answer. A from-memory image tag is how you get a stale image that crash-loops on boot.\n- Decide the ports from the workload: the app\'s own port over HTTP for a web UI, `8888/http` for Jupyter, `22/tcp` for SSH. Only expose what the user needs to reach.\n- **State the cost.** Quote the GPU\'s hourly rate from the catalog read before creating. A running Pod bills whether or not the user is using it.\n\n## Phase 2 \u2014 create and connect\n\n- **Interactive / dev Pod.** Create the Pod with the chosen image, GPU class, disk, ports, and data center. After it reaches running, inspect it and read back the exposed ports and the proxy address \u2014 `publicIp`/`portMappings` are empty while the container initializes, so poll until it is fully running before handing back a URL. App images are large and can take minutes to pull \u2014 a slow boot is NOT a failure: never create a second Pod because the first is still pulling. State the proxy URL form (`https://<podId>-<port>.proxy.runpod.net`) as soon as the Pod id exists; if the app has not bound after the waits your tools can hold, deliver the evidenced status report (pod id, state, last log line) and the recommended next step \u2014 offering to keep watching is fine. The reachable form for an HTTP port is the proxy URL `https://<podId>-<port>.proxy.runpod.net`; for SSH, hand back the host/port from the Pod\'s TCP mapping. Confirm the app actually bound (read the boot log for the "listening on 0.0.0.0:PORT" line) before telling the user it is reachable.\n- **Create then pause for later.** When the user wants the Pod paused ("I\'ll continue tomorrow, keep my data"), first inspect its storage mounts and verify that files they need are on a persistent volume disk or network volume. Copy needed files off the container disk and verify the copy before stopping; if the available tools cannot do that, explain the blocker before proceeding. **Stopping clears the container disk.** A persistent volume disk remains attached to the stopped Pod and continues billing for storage; a network volume persists independently. Stop only after the data is safe, then read back the stopped state and explain that compute billing ends but persistent storage still bills. Never substitute termination: it also deletes the Pod\'s local persistent volume disk. Resume with start; capacity availability can affect resumption.\n- **Training Pod with durable checkpoints.** Checkpoints written to container disk die with the Pod, so co-locate a network volume: create the volume in the same data center you will place the Pod (see `lifecycle-crud`), then create the Pod with that volume mounted at a checkpoint path (e.g. `/workspace` or `/checkpoints`) and pin the Pod to that data center. Tell the user the mount path and that checkpoints there survive the Pod being stopped or terminated, while container disk does not. Size the volume to the expected checkpoint total with headroom. The same network volume mounts at `/workspace` on a Pod but at `/runpod-volume` on a Serverless worker \u2014 if these checkpoints will later be read by a serverless endpoint, its handler must read them at `/runpod-volume`, not the pod path.\n\n## Phase 3 \u2014 hand back\n\n- The hand-back lives in your FINAL message and stands alone (router contract): the Pod id, the exact image it runs and which template/Hub read it came from, the GPU class WITH the stock evidence that justified it (quote the availability read: "RTX 3090 \u2014 N available in EU-RO-1"), the reachable URL(s) verbatim (the full proxy URL for HTTP, host:port for SSH \u2014 never "the link above", and never the boot log\'s internal `0.0.0.0:<port>` address, which is not a reachable URL), the mount path if a volume was attached, and the Pod\'s state with the hourly cost that is now running \u2014 for a stopped Pod, always with the billing consequence in the same breath: GPU billing ended, storage (container disk / any volume) still bills until termination.\n- **Cleanup.** The default is to keep the Pod the user asked for and tell them what is billing and how to stop it (stop keeps the disk and bills storage only; terminate destroys container disk \u2014 a network volume survives either). Tear down \u2014 and delete any volume created only for the exercise \u2014 only when the user framed the journey as a throwaway test or asks for cleanup, confirming by a read-back.\n\n## Hard rules\n\n- Confirm stock before creating. Never create into a GPU class with no availability.\n- State the hourly cost before creating any Pod, and before creating a network volume.\n- Create only the Pod the user asked for. Never stop, terminate, or modify a Pod (or volume) the user did not name.\n- Do not hand back a proxy URL until the Pod is fully running and the app has bound to the port \u2014 an empty `portMappings` means it is still initializing, not broken.\n- For training, checkpoints must land on a network volume, not container disk \u2014 otherwise a stop/terminate loses them.\n- Expose only the ports the workload needs. Do not open SSH or extra ports the user did not ask for.\n- Never claim a Pod is reachable on the create call alone; read back its state first.\n\n## Error handling\n\n- Create returns `no gpu available` / a stock error \u2192 the class ran out between the read and the create; surface it and offer another class or region rather than retrying the same one.\n- The Pod reaches running but `publicIp`/`portMappings` are still empty \u2192 it is still initializing; poll `get-pod` until they populate before handing back a URL. This is Runpod API behavior, not a failure.\n- The proxy URL 502s right after create \u2192 the app inside has not bound to the port yet, or bound to `127.0.0.1` instead of `0.0.0.0`; read the boot log to confirm before declaring the Pod broken (deeper diagnosis is `pod-doctor`).\n- `create-network-volume` returns a quota error \u2192 the account is at its volume quota; tell the user and stop.\n- A create call fails \u2192 report it and stop; do not retry blindly or create a second Pod.\n- The Pod is running but the app is still pulling/booting after minutes \u2192 that is normal for multi-GB images, not grounds for a replacement Pod or an open-ended wait; follow the bounded-wait hand-back above.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| GPU stock per data center | `list-gpu-types` (`include:["AVAILABILITY"]`), `get-gpu-type` | `list-gpu-types` |\n| Capacity matrix (per host CUDA version) | `get-capacity` | *(unbound \u2014 GraphQL-only)* |\n| Data centers | `list-data-centers`, `get-data-center` | `list-data-centers` |\n| Create a network volume | `create-network-volume` | `create-network-volume` |\n| Create a Pod | `create-pod` | `create-pod` |\n| Inspect a Pod | `get-pod` | `get-pod` |\n| List Pods | `list-pods` | `list-pods` |\n| Read Pod boot logs | `stream-pod-logs` | *(unbound \u2014 no REST log stream)* |\n| Stop a Pod (keep disk) | `pod-action` (`{"action":"stop"}`) | `stop-pod` |\n| Resume a stopped Pod | `pod-action` (`{"action":"start"}`) | `start-pod` |\n| Terminate a Pod | `delete-pod` | `delete-pod` |\n\nWhere a capability is unbound on a server, say "not available on this server" and work with what the server does offer.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "pod-doctor",
-    description: `Diagnose a Runpod Pod that is unreachable, GPU-blind, or stuck, then perform a recovery action only if the user authorizes one. Trigger on phrases like "pod 502", "can't reach my pod", "torch can't see the GPU", "cuda not available", "pod came back with no gpu", "did my model load", "read my pod logs", "is anything stuck on my account", "stop vs terminate my pod".`,
-    text: '---\nname: pod-doctor\ndescription: Diagnose a Runpod Pod that is unreachable, GPU-blind, or stuck, then perform a recovery action only if the user authorizes one. Trigger on phrases like "pod 502", "can\'t reach my pod", "torch can\'t see the GPU", "cuda not available", "pod came back with no gpu", "did my model load", "read my pod logs", "is anything stuck on my account", "stop vs terminate my pod".\n---\n\n# Pod doctor\n\nYou operate an existing Pod: first diagnose what went wrong, then \u2014 only if the user asks for an action \u2014 perform the smallest safe recovery. Diagnosis is always read-only. A recovery plan is *presented, not executed* unless the prompt authorizes it, and the default action is stop, never terminate, because terminate destroys container-disk state.\n\nThe spine is always the same: read the Pod\'s state and logs before saying anything, quote the decisive line from the tool output, and never mutate a Pod the user did not name.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below. This skill reads before it acts.\n\n- List Pods with machine info \u2014 the account-wide stuck audit and the "which Pod" resolution.\n- Inspect one Pod \u2014 full status, ports, GPU count, mounts.\n- Read a Pod\'s boot/container logs \u2014 the model-load and crash evidence.\n- Trigger a Pod state transition (stop / start / restart) \u2014 the gated action.\n- Terminate a Pod \u2014 the destructive transition, gated separately.\n- Read GPU stock per data center, and the capacity matrix across host CUDA versions \u2014 to recreate on infra that actually has stock.\n- Recreate a Pod \u2014 only inside an authorized recovery.\n\n## Phase 1 \u2014 diagnose (always, read-only)\n\nResolve the Pod the user named (or list Pods and match by name), then inspect it and read its logs before forming any conclusion. Classify against the symptom:\n\n- **Proxy 502 / "can\'t reach the web UI".** Inspect the Pod. If its `status` is not `RUNNING`, that is the cause \u2014 the proxy has nothing to route to. If it is running, read the logs: a 502 through `<podId>-<port>.proxy.runpod.net` almost always means the app inside is bound to `127.0.0.1` (must bind `0.0.0.0`), listening on a port the Pod never exposed, or still starting. Quote the bind/listen line. The exposed ports are on the Pod record \u2014 name the mismatch, do not guess.\n- **`torch.cuda.is_available()` is False.** Inspect the Pod\'s GPU count (`gpuCount` on the pod record). If it is `0`, this is a zero-GPU allocation, not a CUDA problem \u2014 go to the next classifier. If it is `>=1`, the GPU is attached but the container can\'t use it: read the logs for the driver/runtime line. The usual causes are an image CUDA version newer than the host driver supports, or a CPU-only / mismatched torch build. Quote the line; do not assert which without it.\n- **"Pod came back with zero GPUs" after a restart.** A stopped Pod releases its GPU compute (that is what stop does \u2014 see phase 2). On start it must re-acquire a GPU from live stock, and if none is free in that DC it can come back `RUNNING` with `gpuCount = 0`. Confirm `gpuCount = 0`, then read that GPU class\'s per-data-center availability to show whether the shortage in its data center is real. This is a stock problem, not a broken Pod. Give the user the three concrete recoveries, not just a retry lottery: (1) retry start until the type frees; (2) recreate the pod on a GPU type or data center with live stock; (3) **data rescue from a zero-GPU pod** \u2014 a pod started with 0 GPUs still runs and serves its filesystem, so the files are reachable with no GPU attached. No MCP tool moves bytes, so name the real path for the copy itself and hand it to the user: `runpodctl send` / `runpodctl receive`, `aws s3` against a network volume\'s S3 endpoint, or `scp`/`rsync` over the pod\'s SSH (see `api-boundary`). Never claim the rescue needs a GPU first, and never claim to have copied anything yourself. Never terminate \u2014 that destroys the container disk.\n- **"Did the model load / read my logs".** Read the Pod\'s logs with a generous tail. Quote the single decisive line \u2014 the weights-loaded / "running on 0.0.0.0:PORT" success line, or the OOM / missing-file / auth failure. Report what the log says, never what it probably says.\n- **Account-wide stuck audit.** List all Pods with machine info. Flag as stuck: `status=RUNNING` with a GPU count (`gpuCount`) of 0; or stuck in `PROVISIONING`/`STARTING` past ~10 minutes. Present one table (name, requested GPU, status, stuck-for, reason). If nothing is stuck, say so in one line and stop. Before sending, recount: every number you state ("all N pods", "N stuck") must equal the rows actually printed in your table \u2014 a count that contradicts your own table undermines the whole report.\n\n**No RUNNING pod resolves (empty account, all pods stopped/exited, or wrong key).** If `list-pods` returns nothing \u2014 or returns only stopped/EXITED pods none of which matches a live session the user describes \u2014 do not stop at "give me a pod ID" or "which pod did you mean". State what the list actually shows (no pods, or only stopped ones, by name) and the likely reason (stopped since the symptom, a different account/key, or the pod was terminated), **then commit to the most-common cause of that symptom and its concrete fix as the usual explanation**, and where the account/key mismatch is a live possibility, ask which account they are on as the one follow-up:\n- Zero GPUs after restart \u2192 the usual cause is that stopping the pod released its GPU to the pool and the restart could not re-acquire that type in that DC; recovery is to resume the pod even at 0 GPUs so its files are reachable for a copy off (the copy runs through runpodctl or a volume\'s S3 endpoint \u2014 no MCP tool moves bytes), retry-start until the type frees, or recreate on a GPU type / DC with stock \u2014 and never terminate, which destroys the container disk.\n- `torch.cuda.is_available()` False \u2192 the usual cause is the image\'s CUDA version being newer than the host driver (or a CPU-only/mismatched torch build); the host driver cannot change from inside the container, so the fix is to redeploy/recreate with a CUDA-version constraint (or a matching torch build).\n\nEnd phase 1 with the diagnosis and, if a fix exists, the *recommended* action \u2014 but do not run it. If the prompt was purely "why / what\'s wrong / is anything stuck", you are done here.\n\n## Phase 2 \u2014 recovery (only if the user authorized an action)\n\nAdvance only when the prompt explicitly asks to stop, restart, recreate, or terminate a *named* Pod.\n\n- **Stop vs terminate.** State the consequence before acting, every time: **stopping clears the container disk**, releases GPU/CPU compute, and moves the Pod to `EXITED`. The persistent volume disk (`mounts.persistent`) survives stop and continues billing for storage; a network volume (`mounts.network`) persists independently. Before honoring "stop but keep my data", inspect mounts and verify the needed files are on persistent storage. Copy anything needed from the container disk and verify the copy before stopping; if you cannot do that with the available tools, explain the blocker. Starting resumes the Pod but cannot recover its erased container files. **Terminate** permanently deletes the Pod and its local persistent volume disk; a network volume is only detached. Terminate only on an explicit "delete / terminate / throw it away", and say what data is lost.\n- **Restart / re-acquire.** For a zero-GPU or hung Pod the user asked to recover, prefer stop\u2192start (or restart) before any recreate \u2014 cheaper and non-destructive.\n- **Recreate on alternative infra.** Only if the user authorized a recreate. Capture the original config (image, GPU class, disk, ports, env, mounts, DC) from the Pod record, pick a GPU/DC with real stock from the capacity read, then terminate + create. State the new Pod\'s hourly cost before creating it \u2014 a recreate is a billable resource. Never recreate a Pod whose original `image` is unavailable; skip and say so.\n\n## Hard rules\n\n- Never stop, restart, terminate, or recreate a Pod the user did not name. A stuck Pod may still hold state the user wants.\n- Default to stop. Terminate only on an explicit destructive instruction, and always after naming the disk that dies.\n- State the hourly cost before creating or recreating any Pod.\n- Never claim a recreate succeeded on the create call alone \u2014 a fresh Pod is created, not yet known healthy. Ask the user to re-run diagnosis to confirm.\n- Diagnosis quotes the log/field it read. No "probably" about a fact the tool can answer.\n- If a log read or inspect call fails, report the failure and stop \u2014 do not guess the cause.\n\n## Error handling\n\n- A terminate/delete returns `204` with no body \u2014 that is success, not an error.\n- A state-transition request that is invalid for the Pod\'s current status returns `409` \u2014 the permitted actions are on the Pod\'s `actions` field; read it and pick a valid one.\n- A recreate that returns `no gpu available` means the chosen GPU/DC also has no stock right now \u2014 surface it and stop, do not silently retry elsewhere.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| List Pods (+ machine info) | `list-pods` | `list-pods` |\n| Inspect one Pod | `get-pod` | `get-pod` |\n| Read Pod boot/container logs | `stream-pod-logs` | *(unbound \u2014 no REST log stream)* |\n| Stop a Pod (keep disk) | `pod-action` (`{"action":"stop"}`) | `stop-pod` |\n| Terminate a Pod | `delete-pod` (or `pod-action` `{"action":"terminate"}`) | `delete-pod` |\n| Restart / start a Pod | `pod-action` (`{"action":"restart"}` / `"start"`) | `start-pod`, `restart-pod` |\n| GPU stock per data center | `list-gpu-types` (`include:["AVAILABILITY"]`), `get-gpu-type` | `list-gpu-types` |\n| Capacity matrix (per host CUDA version) | `get-capacity` | *(unbound \u2014 GraphQL-only)* |\n| Data centers | `list-data-centers` | `list-data-centers` |\n| Recreate a Pod | `create-pod` | `create-pod` |\n\nWhere a capability is unbound on a server, say "not available on this server" and work with what the server does offer.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  },
-  {
-    name: "runpod",
-    description: "Start here for any Runpod task \u2014 running GPU/CPU pods, deploying serverless endpoints, templates, network volumes, catalog and cost questions. Routes the request to the right Runpod journey skill and defines the answer contract every Runpod reply follows. All work happens through the connected Runpod MCP tools.",
-    text: `---
-name: runpod
-description: >-
-  Start here for any Runpod task \u2014 running GPU/CPU pods, deploying serverless
-  endpoints, templates, network volumes, catalog and cost questions. Routes the
-  request to the right Runpod journey skill and defines the answer contract
-  every Runpod reply follows. All work happens through the connected Runpod
-  MCP tools.
----
-
-# Runpod (router)
-
-The entrypoint for the Runpod skills. This skill does no infra work itself \u2014 it
-picks the task skill for the request and it owns the **answer contract** below,
-which every reply follows. Every capability here is a structured MCP tool call
-against the connected Runpod server.
-
-## Route by intent
-
-| The user wants to\u2026 | Journey skill |
-| --- | --- |
-| Know what GPUs/workers/endpoints exist, what fits a model, what it costs | **discovery** |
-| Create/inspect/update/delete pods, endpoints, templates, volumes; inventory of the account | **lifecycle-crud** |
-| Stand up a serverless endpoint for a model/workload and prove it works | **serverless-deploy** |
-| Host a ComfyUI workflow (workflow.json, custom Civitai models/LoRAs) as an endpoint | **comfyui-serverless** |
-| Rent/configure an interactive GPU pod; create a pod then pause/stop it for later | **pod-deploy** |
-| Diagnose a broken/misbehaving pod (0 GPUs, CUDA, crashes, 502s) | **pod-doctor** |
-| Operate an existing endpoint: jobs, scaling, workers, logs | **endpoint-ops** |
-| Understand or reduce spend; billing breakdowns | **cost-audit** |
-| Know which surface (API family/tool) is right for an operation | **api-boundary** |
-
-## Capability boundaries \u2014 state them, never fake them
-
-This interface manages infra through the Runpod MCP tools. It does NOT do:
-SSH sessions, file transfer to/from pods, local image builds, model downloads
-to volumes, or interactive terminals. When a task needs one of those, say
-plainly that it is not available through this interface and name what the user
-can do instead (e.g. the Runpod console or CLI tooling) \u2014 never improvise a
-fake capability, never silently drop that part of the task.
-
-## The answer contract
-
-Every Runpod reply follows these rules. Journey skills add journey-specific
-rules and report templates; they never weaken these.
-
-**Facts come from tool reads, stated as facts.**
-- Quote real figures, names, and IDs from the reads you just made \u2014 never from
-  memory, never rounded into vagueness. IDs verbatim.
-- State current stock/status definitively ("RTX 4090 in EU-RO-1: available
-  now") \u2014 never "should be", "probably", or "check later". The read you just
-  did IS the check.
-- Never contradict your own data: if your table says a card is available, the
-  summary cannot call it out of stock.
-
-**Commit; don't hedge, don't defer.**
-- Diagnosis means ONE most-likely cause plus its concrete fix, chosen from the
-  evidence \u2014 not a menu of possibilities, not "run these commands and tell me".
-- If the account state makes the question moot (nothing deployed, zero spend),
-  say exactly that in one sentence and stop \u2014 an honest empty answer is
-  complete.
-- Never ask the user for information a tool could have given you. Push on
-  with the tools you have; ask only when the user is the sole source \u2014 their
-  credentials, their intent on a destructive step, a genuine product choice.
-
-**Mutations bind to what this conversation created.**
-- You may stop, update, or delete only resources created by your own tool
-  calls in this conversation. Provenance comes from your create outputs \u2014
-  never from a name: a "test"-looking name, an auto-generated slug, or a
-  familiar prefix is not attribution.
-- A cleanup or cost-cutting instruction does not extend that authority,
-  however urgently it is phrased. For anything you cannot
-  attribute to this conversation, the complete answer is the audit: what you
-  checked, what qualifies, the ids, and the exact actions for the USER to
-  take. That is a full answer, not a deferral \u2014 the commit-don't-hedge rule
-  never licenses mutating a resource that isn't yours.
-- When nothing this conversation created remains, say exactly that and touch
-  nothing.
-- A mutation blocked by policy on a foreign resource is correct system
-  behavior: report it as out of scope. Never retry it, and never advise
-  re-running from a less-restricted session or console to get around it.
-
-**The final message stands alone.**
-- Close with a summary the user can act on without scrolling back: the ids,
-  URLs, prices, and commands the task produced belong in it. Never "the link
-  above", never a pointer to an earlier turn.
-
-**Carry the work as far as the tools allow.**
-- Prefer a server-side wait (\`wait\` parameters) over handing the user a poll
-  loop; check state between holds. When a wait outlasts what the tools can
-  hold, report the evidenced state \u2014 what was created, what was submitted,
-  what the worker states show \u2014 and the recommended next step. Offering to
-  keep watching is fine; silently stopping mid-wait is not.
-
-**Honest failure beats fabricated success.**
-- Report failures with the observed evidence (the error body, the worker
-  state, the log line) \u2014 never a claimed success without the artifact that
-  proves it (the transcript text, the audio payload, the vector counts).
-- A missing credential or capability is reported as exactly that, with what
-  you did to confirm it and what the user must supply.
-
-**Use only the tools you were given.**
-- If a tool is not available in this session, work with the ones that are \u2014
-  reads you already made can be analyzed directly. Never stall the task
-  requesting new tool access.
-
-**Report habits** (inventory, cost, deployment reports):
-- Enumerations read best as tables carrying each resource's name and id.
-- Every dollar figure comes from a billing/pricing read made this turn; give
-  totals beside per-item figures, and show empty categories rather than
-  silently dropping them.
-- Lead the user to the number or verdict they asked for, stated plainly.
-`
-  },
-  {
-    name: "serverless-deploy",
-    description: `Bring any source \u2014 a HuggingFace repo, a ComfyUI workflow, a Hub release, a custom container image, a GGUF repo, a Civitai asset, or a community template \u2014 to a proven Runpod Serverless endpoint. Deploys an existing source through the Runpod MCP tools; code-first Python deploys (the runpod-flash dev loop) are outside this bundle's scope. Trigger on phrases like "deploy <owner/name>", "serve this model", "make this a serverless endpoint", "ship this ComfyUI workflow as an API", "deploy from the Hub", "run my custom handler image", "GGUF endpoint", "this model is too big for one GPU", "whisper / transcription endpoint", "text-to-speech / voice-cloning endpoint", "speaker diarization endpoint", "OCR / document-extraction endpoint", "embeddings endpoint for semantic search".`,
-    text: '---\nname: serverless-deploy\ndescription: Bring any source \u2014 a HuggingFace repo, a ComfyUI workflow, a Hub release, a custom container image, a GGUF repo, a Civitai asset, or a community template \u2014 to a proven Runpod Serverless endpoint. Deploys an existing source through the Runpod MCP tools; code-first Python deploys (the runpod-flash dev loop) are outside this bundle\'s scope. Trigger on phrases like "deploy <owner/name>", "serve this model", "make this a serverless endpoint", "ship this ComfyUI workflow as an API", "deploy from the Hub", "run my custom handler image", "GGUF endpoint", "this model is too big for one GPU", "whisper / transcription endpoint", "text-to-speech / voice-cloning endpoint", "speaker diarization endpoint", "OCR / document-extraction endpoint", "embeddings endpoint for semantic search".\n---\n\n# Serverless deploy\n\nYou take *any* deployable source and turn it into a working, queue-backed Serverless endpoint that you have actually proven with one real job \u2014 and you leave the user knowing exactly what now exists and what it bills. The spine never changes: read the source, decide the engine and the hardware, provision, warm, smoke-test one real job, hand back the URL and a `curl`, state what is billing. Tear down only when the user framed the deploy as a throwaway test or asks for cleanup.\n\nTwo decisions are yours to make without being told, and getting them wrong is the usual failure: the **engine family** (which worker image is correct for this modality and model format) and the **provisioning path** (bake weights into the image vs download-on-start vs stage on a network volume, each with a different cold-start cost). Size hardware from the model\'s real metadata, never a guess. When several suitable workers exist for the modality, prefer the smallest, most-proven image for a smoke-able deploy \u2014 a giant image turns the first job into a many-minute cold-start lottery; the smoke test\'s job is proof of the journey, not maximal quality. Name the trade-off if the user\'s request implies a heavier engine. Creating an endpoint is billable \u2014 state the hourly cost of the GPU class before you create it, and remember a smoke job costs real money.\n\nFor code-first Python \u2014 writing endpoint functions in a project and iterating with Runpod\'s Python dev loop (runpod-flash) \u2014 this MCP-only bundle has no path: say so plainly instead of improvising one. This skill deploys an existing source (Hub repo, container image, ComfyUI workflow, Hub release) to an endpoint through the MCP tools.\n\n## Required capabilities\n\nNamed as capabilities; the tool serving each one on this server is in the per-server tool binding below. This skill reads the catalog before it creates, and creates only what the user asked to deploy.\n\n- Read GPU catalog + price + live stock, per-data-center availability, and the host-CUDA-version capacity matrix \u2014 sizing and stock (delegate the sizing math to `discovery`).\n- Browse the Hub worker catalog, with the release config \u2014 to find a prebuilt worker or a community template and read its hardware/env schema.\n- Deploy a Hub release directly as an endpoint \u2014 the one-call Hub path.\n- Create a template (image, disk, ports, env, registry, mounts) \u2014 the reusable worker preset.\n- Create a Serverless endpoint (GPU pools, worker min/max, scaler, data centers, network volumes).\n- Create a network volume \u2014 to stage large weights in a GPU-co-located data center.\n- Pin GPUs / set GPU count per worker \u2014 use `gpu.count`, `gpu.pools`, and `gpu.excludedTypes` on create/update, or the GPU-selection convenience tool.\n- Read endpoint health and list workers \u2014 warmup and readiness, and the cold-start-vs-crash-loop signal (`initializing` vs `unhealthy`); worker status alone cannot rule a crash loop out, so pair it with the worker\'s logs.\n- Submit a synchronous or async job and block on it \u2014 the smoke test (`runsync-endpoint wait:300000`, then `get-job-status wait:300000` on the job id until terminal).\n- Read a worker\'s logs *when that tool is available to you* \u2014 model-load / crash evidence; when it is not, `endpoint-health` + `list-endpoint-workers` give the worker-health counts that already distinguish a cold start from a crash-loop.\n- Delete the endpoint, template, and any network volume \u2014 teardown of everything created.\n\n## Phase 0 \u2014 identify the source and pick the engine (unprompted decision)\n\nRead the source the user gave you and classify it. The engine family follows from the modality and the model format, not from a default. Never serve a non-text-generation task on a vLLM or ComfyUI worker.\n\n| Source / modality | Correct engine family | Worker image kind |\n|---|---|---|\n| Text-generation LLM, `safetensors` weights | vLLM or SGLang | `runpod/worker-v1-vllm` (or SGLang worker) |\n| Text-generation LLM, `GGUF` quantized weights | llama.cpp / Ollama | a GGUF-capable worker \u2014 **not** vLLM |\n| Image/diffusion `workflow.json` | ComfyUI | `runpod/worker-comfyui` |\n| Speech-to-text (transcription) | Whisper / faster-whisper | a Whisper worker, not an LLM worker |\n| Text-to-speech / voice cloning | Chatterbox / XTTS / Kokoro | a TTS worker |\n| Speaker diarization | pyannote / a diarization pipeline | a community/Hub diarization worker |\n| OCR / document extraction | PaddleOCR / DeepSeek-OCR / docling | an OCR worker, not a VLM chat worker |\n| Text embeddings | Infinity / text-embeddings-inference / sentence-transformers / BGE | an embeddings worker |\n| A custom handler you were given | your own image | a custom container image |\n\n- **Format detection.** Inspect the repo\'s files before choosing. `*.safetensors` / `*.bin` \u2192 vLLM/SGLang. `*.gguf` \u2192 a llama.cpp/Ollama worker; deploying a GGUF repo on worker-vllm is the classic wrong-engine mistake \u2014 vLLM will not load it. State the format you detected and the engine it implies in the final message \u2014 the detection is part of the answer, not just the decision.\n- **OCR sizing.** For an OCR/document-extraction smoke deploy, default to a classic lightweight OCR worker (the PaddleOCR/EasyOCR/docling class, 16\u201324 GB). A VLM-based OCR (7B+ params) is a big-model deploy \u2014 size it like one (48 GB class) or don\'t pick it for a smoke test.\n- **Community-template source.** When the modality has no first-party Runpod worker (e.g. speaker diarization), browse the Hub / public catalog for a **community (non-Runpod)** template that serves it. Attribute provenance to the catalog entry you actually found \u2014 name the repo and its owner from the listing, never assert a repo from memory. Once you have found a fitting worker, **deploy it and run the clip** \u2014 do not stop at "I found X," and do not block on a credential the config makes optional (see the runtime-optional-token rule in phase 2); ask for the capability in the job input (a diarization worker takes `diarization: true`). Only if the catalog returns nothing that fits do you say "none found" and stop; never invent a repo name or a Docker image.\n- **Custom image.** When the user brings their own handler image, that image *is* the engine. After the deploy, read the worker states (`list-endpoint-workers` or `endpoint-health`) and report what you observed \u2014 for a custom image the workers\' observed health IS the deliverable: one completed job does not show a crash-looping sibling worker, and a crash-looping custom image is called failing, never glossed. If it is in a private registry, the endpoint needs a registry credential (create/reference it \u2014 see `lifecycle-crud`); never echo the registry password. For a load-balancer (custom-HTTP, direct-routing) endpoint rather than the queue, the cardinal rule is that the worker must serve HTTP on a port the template exposes AND answer the load balancer\'s health path \u2014 `HEALTH_CHECK_PATH` if the worker sets that env, `/ping` otherwise. Miss either and workers never pass health, so the endpoint looks stuck with zero ready workers; the endpoint read returns the exact health URL being polled. The endpoint type is also immutable after create.\n\n## Phase 1 \u2014 size the hardware (read the catalog, cite `discovery`)\n\nDelegate the params\xD7precision + KV/overhead VRAM math to `discovery`; this skill applies its result to a real GPU pick.\n\n- Read the model\'s real metadata (parameter count, precision, and for diffusion the checkpoint/LoRA/VAE asset sizes). Do not size from the repo name alone when the config is readable.\n- Pick the smallest GPU class whose VRAM fits, then confirm live stock from the GPU-availability read \u2014 `include:["AVAILABILITY"]` also gives the per-data-center picture when the endpoint needs a specific DC, and the capacity matrix adds the host-CUDA-version dimension when a CUDA floor is in play. Never create into a GPU class with no stock \u2014 a scale-to-zero endpoint that can never acquire a worker looks deployed but never runs.\n- **Multi-GPU when one card can\'t hold the model.** When required VRAM exceeds the largest single card you can get with stock, set GPUs-per-worker > 1 and enable tensor parallelism in the worker env (e.g. the vLLM worker\'s tensor-parallel setting = GPU count). State plainly that you are going multi-GPU and why (the model does not fit on one card), and that multi-GPU workers cost proportionally more per hour. Before committing, price the alternative in the answer: quote the largest in-stock single card (its VRAM, live stock, $/hr) against the multi-GPU pick \u2014 a 2\xD780 GB decision that never names the in-stock 180 GB card is unjustified sizing.\n- **Pin the pool on Hub deploys.** `deploy-hub-repo` inherits the release\'s GPU pool list when `gpuIds` is omitted \u2014 which can silently acquire a top-tier card for a task a 24 GB card serves, at several times the hourly rate. Pass `gpuIds` from YOUR sizing decision on every Hub deploy unless the release config pins exactly the pool your sizing chose.\n- **CPU Serverless.** `create-endpoint` supports CPU workloads through `body.cpu`; read its schema and the CPU catalog for supported instance choices. Supply CPU or GPU configuration, never both.\n- **State the cost.** Before creating, quote the chosen GPU\'s hourly rate (\xD7GPU count) from the catalog read. Creating the endpoint and running the smoke test both bill.\n\n## Phase 2 \u2014 provision\n\nTwo provisioning paths; choose by source.\n\n- **Hub release.** If the source is a Hub repo, deploy its listed release directly (one call). Read the release config first (hardware requirements + env schema) so you pass only env keys the release accepts, and so you know its GPU/disk defaults. To reproduce a known-good build, pin the exact release rather than "latest".\n- **Everything else.** Create a template that names the engine image, the disk size, the ports the worker exposes, and the env (model id, engine settings, tokens); then create the endpoint referencing it. Start scale-to-zero (min workers 0) unless the user asked for warm capacity \u2014 a nonzero minimum is an always-on billed worker.\n- **Provisioning path and cold start.** Bake-into-image = fastest cold start, biggest image; download-on-start = small image, slow first request per new worker; **network volume** = weights staged once in a GPU-co-located data center, mounted read-only, so new workers skip the download. Choose a network volume when weights are large (roughly > 30 GB) or shared across workers; size it to the real asset total with headroom, create it in the same data center you pin the endpoint to (see `lifecycle-crud`), and say which path you took and its cold-start consequence.\n- **Multi-region / HA (no auto-sync).** For a multi-region endpoint you attach one network volume per data center; these per-DC volumes do **not** auto-sync \u2014 you replicate data across them yourself (e.g. an `aws s3` sync between the volumes\' S3 endpoints), or each region serves stale or missing weights.\n- **Required env, gated weights, and runtime-optional tokens.** Read the release/worker config (`includeConfig: true`) and SET every required env key that has no default before you deploy \u2014 e.g. an embeddings worker\'s `MODEL_NAMES` (`BAAI/bge-small-en-v1.5`); deployed without its model env a worker loads nothing and 400s every job. For a gated HuggingFace repo whose *weights* 403 without a token at download time, pass the token in env, and if the user gave none, say the download will 403 and ask \u2014 do not deploy a build that cannot fetch its weights. A token needed only for an **optional runtime capability**, one whose config default is empty (a diarization worker\'s `HF_TOKEN`), branches on one check you make FIRST: did the user provide a token (pasted in the request, set in the environment, or named as available)?\n  - **Token provided \u2192 using it is the job.** Set it as the worker env var at create (`HF_TOKEN` for a diarization worker), say that you configured it (by env-var name, never the value), and expect the gated capability to work. Never deploy without wiring a credential the user handed you.\n  - **No token \u2192 deploy anyway.** The deploy is NOT conditional on the token: don\'t park the whole deploy on an optional credential. Deploy, run the job, report what the endpoint actually returned, and then name the token as the unlock for the gated capability.\n  Never print a token value; reference it as an env var.\n\n## Phase 3 \u2014 warm and smoke-test one real job\n\nProve the endpoint before you call it deployed: block on the smoke job with server-side holds instead of handing the user a poll loop \u2014 the tools can carry the wait, so let them. Report what you observed once the job is terminal; if waiting stops being productive, report the evidenced state instead.\n\n- **Submit through the sync path and wait server-side \u2014 do not tight-loop.** Fire exactly one real, small job (a short prompt, a 512px few-step image, one short audio clip, one page, one sentence to embed) with `runsync-endpoint` and `wait: 300000`, the maximum server-side hold. The point is to prove the worker boots with the real asset set and returns the right shape of output \u2014 not just that the endpoint exists.\n- **Expect a cold start of 1\u20135+ minutes on the first job** \u2014 a fresh worker pulls the image and loads the model. This is normal, not a failure. If the job outlives the hold and `runsync` returns a non-terminal status with a job id, keep blocking with `get-job-status` using `wait: 300000` (one server-side hold, not a rapid re-poll). Poll the job id you already have \u2014 do **not** re-submit `runsync`, which starts a new job. Between holds check `list-endpoint-workers`: `unhealthy` workers or zero capacity \u2192 stop waiting immediately (see below). When continued waiting stops being informative, stop and report the state honestly with the worker-state evidence \u2014 endpoint created correctly, job submitted, the worker never became ready, here is what the worker states show. That evidenced report is a complete answer; an endless grind is not.\n- **Diagnose a stuck job from the reads you always have: `endpoint-health`, `list-endpoint-workers`, and the `workerHealth` block `get-job-status` attaches on `IN_QUEUE`.** `initializing` workers = the cold start is still in progress \u2192 keep waiting. `unhealthy` workers = the container is crash-looping (a real worker failure, not slow warmup) \u2192 switch the worker image or GPU pool, don\'t wait it out (the classic Whisper/TTS tell). **But `unhealthy: 0` does not clear the workers**: a container that fails to start loops while its worker keeps reporting RUNNING or THROTTLED, so when the job stays queued and workers exist, read `stream-worker-logs` on one of them whatever its status says \u2014 UNHEALTHY is a symptom of a crash loop, not a test for one. `total: 0` or throttled = no capacity on that GPU pool \u2192 widen it. A job that never left `IN_QUEUE` was never parsed \u2014 its payload was never read by any worker, so NEVER speculate the input was malformed from queue-stuck evidence; the honest report is the queue/cold-start fact with the worker states quoted. The same discipline covers every stuck-queue anomaly: never present a cause as "conclusive" that your own reads contradict or don\'t show (idle healthy workers beside a queued job is a platform anomaly you REPORT as observed, not a crash-loop you assert) \u2014 an unevidenced cause stated as fact fails the journey even when everything else was right. Prefer a broad, in-stock GPU pool over a scarce high-VRAM tier (e.g. the 48 GB cards) so the endpoint can actually acquire a worker.\n- **Assume you have only the Runpod MCP tools.** Do not reach for a web-fetch tool, a shell, or a browser you were not granted to look up a worker\'s input schema or read its README \u2014 a tool you do not have cannot be called, and the deploy stalls with the job unfinished. Get the input shape from `list-hub-repos` with `includeConfig: true` and from the error the endpoint returns, then correct the payload and re-run. If `stream-worker-logs` is likewise unavailable, diagnose from `endpoint-health` / `list-endpoint-workers` \u2014 never let an unfinished job hinge on a tool you may not have.\n- On a terminal `FAILED` job, report the decisive detail the result gives you (missing file, gated 403, OOM, wrong-format load error) \u2014 what it says, not what it probably says. OOM \u2192 the GPU is too small for the real memory pattern; step up a class. Wrong-format load error on a GGUF repo \u2192 the engine is wrong (phase 0). A `400` on the payload \u2192 the input shape is wrong; fix it from the release config and re-run, do not abandon.\n\n## Phase 4 \u2014 hand back\n\n- The hand-back is a complete final summary the user never has to scroll back from: the endpoint id; the worker image or Hub repo (and which read it came from); the GPU pool and its hourly price; the smoke job\'s id and terminal outcome with its proof (the output reference, the quoted failure, or the evidenced timeout report); the sync and async URLs; whether the endpoint was kept (and what is now billing) or deleted (read-back confirmed); and a ready-to-run `curl` that references `$RUNPOD_API_KEY` (never the literal key). The sizing arithmetic, format finding, and any caching/placement facts belong in it too.\n- **Cleanup.** The default is to KEEP what the user asked for: tell them exactly what is now billing (the endpoint, any min-worker, any network volume) and how to delete it later. Tear down \u2014 the endpoint, its template, any network volume, each confirmed gone by a read-back \u2014 only when the user framed the journey as a throwaway test or asks for cleanup.\n\n## Hard rules\n\n- Deploy only the source the user named. Never create an endpoint they did not ask for, and never touch or delete another endpoint, template, or volume.\n- Pick the engine from the modality and the model format, never a default. A GGUF repo is not a vLLM job; transcription/TTS/OCR/embeddings are not chat-worker jobs.\n- State the hourly GPU cost before creating a billable endpoint, and remember the smoke job bills too.\n- Never invent a model URL, a community template repo, or a Docker image. If the source can\'t be resolved from what the user gave you plus the catalog, ask once or say "none found" and stop.\n- Prove the endpoint with one real job before calling it deployed. A create call that returned an id is not a working endpoint.\n- Carry the smoke job to a terminal state with server-side holds \u2014 `runsync-endpoint wait:300000`, then `get-job-status wait:300000` on the job id \u2014 expecting a 1\u20135+ minute first-job cold start; hold server-side rather than handing the user a poll loop for a wait the tools can carry. If continued waiting stops being informative, end with the honest, evidenced report (worker states, job status) \u2014 that is a complete answer; silent surrender mid-wait is not.\n- Assume you have only the Runpod MCP tools. Never make the journey depend on a web-fetch or shell tool you were not granted to look up a worker\'s schema \u2014 derive the input shape from `list-hub-repos includeConfig` and the endpoint\'s own error, and correct the payload in place. A tool you were not given is not a path.\n- Set every required env key (no config default) at deploy \u2014 an embeddings worker without `MODEL_NAMES` loads no model and fails every job. An optional-capability token (e.g. a diarization worker\'s `HF_TOKEN`, empty default): if the user provided one, set it at create \u2014 never ignore a handed-over credential; if not, deploy anyway, run, and report what came back, then name the token as the unlock.\n- Start scale-to-zero unless warm capacity was requested; never set a nonzero worker minimum silently \u2014 it bills around the clock.\n- Sizing a big model is shown arithmetic, never a bare total: give the parameter count and where you read it, the bytes per parameter at the chosen precision, the weights total, the KV-cache/overhead allowance, and the GPU decision they add up to. "~146GB so 2\xD7H200" without the components is an assertion, not sizing.\n- When the user asked for specific behavior settings (warm/minimum workers, idle timeout, FlashBoot, a GPU pin), read the endpoint back after the create/update and confirm those exact fields landed \u2014 an unread write is an unverified write, because the write call\'s own response is not a read. Both `update-endpoint` and `set-endpoint-gpus` use sparse REST updates: omitted fields are left untouched. After a GPU change, confirm the scaling fields too. The read-back result belongs in the final answer.\n- Cold-start asks ("first message takes 40 seconds", "keep it snappy") have exactly four real levers \u2014 name all four with their cost trade-offs, then apply what was agreed: **FlashBoot** (faster worker start, no standing cost), **minimum/warm workers** (no cold start, bills that worker continuously \u2014 quote $/hr \xD7 730/mo from the price read), **idle timeout** (a longer window keeps a warm worker between bursts \u2014 fewer cold starts, more billed idle seconds), **model caching** (weights on a network volume or baked into the image \u2014 the load, not the boot, dominates big-model cold starts).\n- "Don\'t bake the weights into the image" / cache-on-volume asks are an architecture journey, not a smoke-test one: create the network volume in a data center that has the target GPU, attach it to the endpoint, point the worker\'s model path env at the volume mount, keep minimum workers 0, and run NO job unless asked. State two facts of the architecture you built, plainly and unhedged: the first worker downloads the weights to the volume once and every later cold start mounts the cache instead of re-downloading; and the volume must live in the same data center as the GPUs or it cannot mount. (The volume CRUD discipline is lifecycle-crud\'s; this is the serving-side wiring.)\n- Never echo an HF/Civitai/registry token. Reference it as an env var.\n- On a smoke-test failure, read the log and quote it; do not retry blindly or assert a cause you did not read.\n- A terminal job\'s `output`/`error` field IS worker-level evidence \u2014 quote it verbatim when explaining a failure (a gated-model rejection, a load error). Never tell the user you cannot quote evidence while holding a terminal job result; lacking a log-stream tool does not excuse dropping the evidence the job itself returned. Empty or missing output on COMPLETED jobs from a gated-capability worker is itself quotable evidence: report it as such (\'N jobs completed but returned no payload\'), pair it with the config fact (the token env the worker documents was not set), and state the gate plainly.\n\n## Error handling\n\n- Smoke job returns `FAILED` with `gated` / `403` in the message \u2192 the asset is gated and no token was supplied. Say so and ask for the token; do not auto-recreate.\n- Smoke job returns `FAILED` with `out of memory` \u2192 the GPU is too small for the real pattern; move up one GPU class and note the new hourly cost. If failures persist after one step-up, re-examine the worker choice itself \u2014 an oversized engine family for the task (a 7B VLM where a classic OCR worker suffices) is fixed by switching the worker image in-turn, not by more GPU or more waiting.\n- Job returns `IN_QUEUE` / `IN_PROGRESS` past the sync wait \u2192 usually a cold start; keep blocking with `get-job-status wait:300000` on that job id, then report either the terminal result or the evidenced state. Hold server-side rather than handing the user a raw poll loop.\n- Smoke job returns `400` / a payload-shape error (e.g. an embeddings worker\'s `TextEncodeInput` complaint) \u2192 the input is wrong or a required model env was never set; re-read the release config, set the missing env (`MODEL_NAMES`) or fix the payload shape (`{"input": {"model": "...", "input": ["..."]}}` for an Infinity/OpenAI-compatible embeddings worker), and re-run \u2014 do not stop and ask the user.\n- Jobs go terminal almost instantly (well under a second of execution) with empty or degraded output on a worker whose capability is token-gated \u2192 the gate is the first suspect, not the payload: read the job\'s `output`/`error` field verbatim and check whether the token env was actually set on the template/endpoint, before theorizing about input shape. Answer from the evidence already in hand \u2014 the job result and the config read settle it \u2014 rather than deferring the question.\n- Create returns `409` (name collision) \u2192 append a fresh short suffix and retry once; if it still collides, surface it and stop.\n- A GGUF repo fails to load on a vLLM worker \u2192 this is the wrong-engine case, not a stock or size problem; re-provision on a GGUF-capable worker.\n- The Hub / community catalog returns nothing for the modality \u2192 report "none found on the catalog" and stop; do not fabricate a repo.\n- A delete returns `204` with no body \u2192 that is success, not an error; confirm with a read-back.\n\n## Per-server tool binding\n\n| Capability | This server | Official `runpod-mcp` |\n|---|---|---|\n| GPU catalog + price + stock | `list-gpu-types` (`include:["AVAILABILITY"]`), `get-gpu-type` | `list-gpu-types` |\n| Per-data-center GPU availability | `list-gpu-types` / `get-gpu-type` (`include:["AVAILABILITY"]` \u2192 `dataCenters[]`), `list-data-centers` (`include:["GPU_AVAILABILITY"]`) | `get-gpu-type`, `list-data-centers` |\n| Capacity matrix (per host CUDA version) | `get-capacity` | *(unbound \u2014 GraphQL-only, no REST home)* |\n| Data centers | `list-data-centers`, `get-data-center` | `list-data-centers` |\n| Browse Hub / community catalog | `list-hub-repos` (`includeConfig:true`) | *(unbound \u2014 no Hub browse)* |\n| Deploy a Hub release directly | `deploy-hub-repo` | *(unbound \u2014 no Hub deploy)* |\n| Pin a Hub release / read history | `list-endpoint-releases` | *(unbound)* |\n| Create a template | `create-template` | `create-template` |\n| Create an endpoint | `create-endpoint` | `create-endpoint` |\n| Create a network volume | `create-network-volume` | `create-network-volume` |\n| Multi-GPU / GPU-SKU pin | `set-endpoint-gpus` (`gpuCount`, `pools`) | `update-endpoint` (`gpu.count`, `gpu.pools`, `gpu.excludedTypes`) |\n| Endpoint health / warmup | `endpoint-health` | `endpoint-health` |\n| List workers (per-worker detail) | `list-endpoint-workers` | *(coarse \u2014 `endpoint-health` only)* |\n| Smoke test (block until terminal) | `runsync-endpoint` (`wait:300000`), `get-job-status` (`wait:300000`), `run-endpoint` | `runsync-endpoint` |\n| Read a worker\'s logs | `stream-worker-logs` | *(unbound \u2014 no REST log stream)* |\n| Registry credential (private image) | `create-registry`, `get-registry` | `create-registry` |\n| Inspect endpoint / template | `get-endpoint`, `get-template` | `get-endpoint` |\n| Teardown | `delete-endpoint`, `delete-template`, `delete-network-volume` | `delete-endpoint` |\n\nWhere a capability is unbound on a server, say "not available on this server" and work with what the server does offer.\n\n## Report template \u2014 deployment summary\n\nA good deploy summary tells the user: which worker/engine was chosen and why;\nthe endpoint name and id; the GPU pool and its hourly price from the catalog\nread; the smoke-job proof (the actual output artifact: transcript text, audio\npayload reference, extracted text, vector count); the current worker state;\nwhat the endpoint costs standing (scale-to-zero or $/hr); and how to delete it\nlater. When the wait ended without a terminal job, the evidence takes the\nproof\'s place: job id, submitted payload, worker states observed, and the\nrecommended next step.\n\n## Contract\n\nThe cross-journey answer contract (definite facts from reads, commit-don\'t-hedge, mutations bind to this conversation\'s creations, a standalone final message, honest failure, granted tools only) is defined in the `runpod` router skill and applies to every reply from this journey.\n'
-  }
-];
-
 // src/specgen/pagination.ts
 var DEFAULT_LIST_LIMIT = 20;
 var MAX_LIST_LIMIT = 100;
@@ -3977,6 +4534,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 +4569,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 +4648,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 +4714,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 +4915,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 +5109,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 +5211,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 +5669,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 +5699,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 +5743,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 +5791,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 +5822,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 +5847,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 +5872,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 +5892,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 +5928,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 +5962,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 +5973,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 +6000,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 +7411,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 +7433,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 +7474,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 +7573,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 +8299,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 +8335,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,7 +8366,8 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "ask_question",
-    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.",
+    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 list-guides and read-guide 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.",
       { tool: TOOL_FIELD }
@@ -7438,7 +8383,7 @@ function createAlpTools(opts) {
       return ok({
         recorded,
         answer: null,
-        note: recorded ? "Recorded. No answer is coming \u2014 not now, not later in this session. Do not wait, poll, or retry. Check the runpod://skills/ resources for existing guidance and continue with your best judgment." : NOT_RECORDED
+        note: recorded ? "Recorded. No answer is coming \u2014 not now, not later in this session. Do not wait, poll, or retry. Check list-guides and read-guide for existing guidance and continue with your best judgment." : NOT_RECORDED
       });
     }
   };
@@ -7446,6 +8391,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,23 +8442,26 @@ 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.
 
 Answer from live reads, as facts. Account and availability questions can only be answered from tool data: call the relevant list-/get- tool and quote the figures, names, and ids it returns verbatim. State stock and status definitively from the read you just made \u2014 never "probably" or "check later". When the user names a resource loosely ("my comfyui pod"), resolve it with a list- tool; ask only on genuine ambiguity. If nothing exists (no pods, zero spend), say exactly that \u2014 an honest empty answer is complete.
 
-Commit; don't hedge, don't defer. Diagnosis means one most-likely cause plus its fix, from the evidence \u2014 not a menu, not "run these and tell me". For jobs, block server-side (runsync-endpoint and get-job-status accept wait, up to ${STATUS_WAIT_MAX_MS} ms), expect first-job cold starts of minutes, and check worker states between holds; when a wait outlasts what the tools can hold, report the evidenced state \u2014 what was created, what was submitted, what the worker states show \u2014 and the recommended next step. Offering to keep watching is fine; stopping mid-wait without that report is not. Never claim success without the artifact that proves it (the transcript text, the output payload).
+Commit; don't hedge, don't defer. Diagnosis means one most-likely cause plus its fix, from the evidence \u2014 not a menu, not "run these and tell me". For jobs, submit with run-endpoint and block server-side with get-job-status wait (up to ${STATUS_WAIT_MAX_MS} ms); use runsync-endpoint only for a warm endpoint and a fast job. Expect first-job cold starts of minutes, and check worker states between holds; when a wait outlasts what the tools can hold, report the evidenced state \u2014 what was created, what was submitted, what the worker states show \u2014 and the recommended next step. Offering to keep watching is fine; stopping mid-wait without that report is not. Never claim success without the artifact that proves it (the transcript text, the output payload).
 
-Mutations cost money and bind to what this conversation created. State the hourly price before creating anything billable, read before you mutate, and stop, update, or delete only resources your own tool calls created in this conversation \u2014 a name that looks like test junk is not attribution. For anything you cannot attribute, the complete answer is the audit: what you checked, what qualifies, the ids, and the exact actions for the user to take.
+Mutations cost money and bind to what this conversation created or the user named. State the hourly price before creating anything billable; create-cluster waits for the user's explicit go on the quoted shape and total hourly price. Read before you mutate, and stop, update, or delete only resources your own tool calls created in this conversation, or the one resource the user named by id or an unambiguous name \u2014 and then only the change they asked for; delete a user-named resource only when they asked for that delete. A name that looks like test junk, or one you found by listing, is not attribution. For anything you cannot attribute, the complete answer is the audit: what you checked, what qualifies, the ids, and the exact actions for the user to take.
 
 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.
 
-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.
+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.
 
-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.
+PLAYBOOKS \u2014 READ BEFORE ACTING. Each Runpod task has a journey playbook carrying its procedure, pitfalls and report format. Before the FIRST Runpod tool call of a session, load the plugin's runpod-mcp skill if you have it, otherwise read-guide runpod-mcp (also the runpod://guides/runpod-mcp resource): it routes the request to a journey guide \u2014 deploying an endpoint reads serverless-deploy, diagnosing a broken pod reads pod-doctor, cost questions read cost-audit, and so on \u2014 and states the answer contract. A reply produced without the routed playbook loaded is out of contract.
 
-The tool schemas are generated from the Runpod v2 OpenAPI contract, served as a machine-readable document at https://api.runpod.io/v2/openapi.json \u2014 consult it for fields beyond the tool surface. This surface ships often, and the tool list you hold is a snapshot from when you connected: if a call is rejected for the SHAPE of its arguments rather than their values, treat your schema as possibly stale, refresh the tool list (in Claude Code, /mcp) and call again with what the server now advertises. Retrying variants of a rejected shape cannot succeed.`;
+THE OFFICIAL RUNPOD PLUGIN. Runpod ships an agent plugin that also covers the lanes these tools 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, use them for lane choice and for the CLI, image-build and golden-path lanes. For work done with these tools, the journey playbook is the procedure, wherever it is served from: the plugin's runpod-mcp skill and the journey skills it routes to when you have them, otherwise the same playbooks through read-guide here. 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 override any Runpod tool list written down elsewhere, the plugin's skills and guides included.
+
+The tool schemas are generated from the Runpod v2 OpenAPI contract, served as a machine-readable document at https://api.runpod.io/v2/openapi.json \u2014 consult it for fields beyond the tool surface. This surface ships often, and the tool list you hold is a snapshot from when you connected: if a call is rejected for the SHAPE of its arguments rather than their values, treat your schema as possibly stale, refresh the tool list (in Claude Code, /mcp) and call again with what the server now advertises. Retrying variants of a rejected shape cannot succeed. These instructions are a snapshot from the same moment. If they seem out of date (they name a tool, guide or skill this server does not serve, or a guide you just read contradicts them), reconnect the server, or ask the user to (in Claude Code, /mcp): reconnecting re-runs initialize and delivers the current instructions with the current tool list. Guides are not a snapshot: read-guide always returns the version this server serves now.`;
 var ALP_INSTRUCTIONS = `
 
 CONTRIBUTING BACK IS OPTIONAL. Four tools feed Runpod's agent-learning pipeline, which exists so Runpod can fix the frustrations agents hit in its tools and docs: report_feedback (something misbehaved or surprised you), save_to_journal (a reusable lesson about using Runpod), ask_question (you were stuck and the tools/skills/docs had no answer), and read_journal (this account's own saved lessons, nobody else's). Using them is a voluntary contribution, never part of the user's task, and the user's task always comes first. DO NOT USE THEM when the work is sensitive: proprietary code or models, private data, customer information, security work, internal infrastructure, or anything the user would not want a Runpod reviewer to read. Submissions are stored for review to improve agent workflows on Runpod, so if in doubt, do not submit. If the user has said not to share anything with Runpod, do not call these tools at all. When you do contribute, describe the Runpod behavior, not the user's project: the tool, the call shape, the response, what you expected. Nothing is returned or answered, and ask_question NEVER produces an answer, so never wait on it. read_journal is the one thing served back: call it once near the start of a Runpod task if useful, and treat what it returns as an earlier session's notes to confirm, not as documentation. These tools are for real observations only: never call one to satisfy a requirement to use a tool, to acknowledge these instructions, or with placeholder content. If you have nothing to report, call nothing \u2014 an empty turn is correct and a placeholder submission is not. Never include API keys or secrets in submissions.`;
@@ -7539,46 +8488,42 @@ 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: guideResources.map(({ text: _text, ...resource }) => resource)
   }));
   server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
     resourceTemplates: []
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    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) {
+    const guide = guideResources.find(
+      (candidate) => candidate.uri === request.params.uri
+    );
+    if (!guide) {
       throw new Error(
-        `Unknown resource ${request.params.uri}. Available: ${skillDocs.map((candidate) => `${SKILL_URI_PREFIX}${candidate.name}`).join(", ")}`
+        `Unknown resource ${request.params.uri}. Resources are the plugin guides under ${GUIDE_URI_PREFIX}; call list-guides for the guide ids.`
       );
     }
     return {
       contents: [
-        {
-          uri: request.params.uri,
-          mimeType: "text/markdown",
-          text: skill.text
-        }
+        { uri: guide.uri, mimeType: "text/markdown", text: guide.text }
       ]
     };
   });
@@ -7657,9 +8602,9 @@ function errorHint(status) {
     return "Input shape mismatch: check this tool's schema for required fields. For job payloads, the worker's release config defines the expected input object \u2014 fix the payload and retry; don't abandon the task.";
   if (status === 401) return "The Runpod API key is missing or invalid.";
   if (status === 402)
-    return "Check your account balance in the Runpod console before retrying billable operations.";
+    return "Check your account balance in the Runpod console before retrying billable operations; list-billing shows the recent spend behind it.";
   if (status === 403)
-    return "Check that this API key has permission for the requested resource and operation. Review its permissions in the Runpod console before retrying.";
+    return "Check that this API key has permission for the requested resource and operation. Review its permissions in the Runpod console before retrying. A permission error on a resource you did not create is final: report it rather than retrying.";
   if (status === 404)
     return "No such resource on this account: verify the id with the matching list- tool before retrying.";
   if (status === 429)