@runpod/mcp-server 4.3.0 → 4.5.0

package/dist/stdio.cjs

@@ -46,6 +46,9 @@ function publicGraphqlBase(env) {
 function authedGraphqlBase(env) {
   return pick(env.RUNPOD_AUTHED_GRAPHQL_URL, "https://api.runpod.io/graphql");
 }
+function hostedMcpBase(env) {
+  return pick(env.RUNPOD_MCP_URL, "https://mcp.getrunpod.io");
+}
 var init_hosts = __esm({
   "src/_shared/hosts.ts"() {
     "use strict";
@@ -736,9 +739,10 @@ var init_clients = __esm({
     path = __toESM(require("path"), 1);
     import_child_process = require("child_process");
     jsonc = __toESM(require("jsonc-parser"), 1);
+    init_hosts();
     SERVER_NAME2 = "runpod";
     NPM_PACKAGE = "@runpod/mcp-server@latest";
-    HOSTED_URL = process.env.RUNPOD_MCP_URL ?? "https://mcp.getrunpod.io/";
+    HOSTED_URL = `${hostedMcpBase(process.env)}/`;
     PROJECT_BOUNDARY_MARKERS = [
       ".git",
       "package.json",
@@ -1179,7 +1183,7 @@ var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "4.3.0" : "dev";
+var SERVER_VERSION = true ? "4.5.0" : "dev";
 
 // src/specgen/server.ts
 var import_server3 = require("@modelcontextprotocol/sdk/server/index.js");
@@ -1506,6 +1510,7 @@ function coerceScalars(value, schema, defs, depth = 0) {
 var generatedTools = [
   {
     name: "create-cluster",
+    title: "Create cluster",
     operationId: "createCluster",
     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",
@@ -1743,6 +1748,7 @@ var generatedTools = [
   },
   {
     name: "create-delegation",
+    title: "Create ECR delegation",
     operationId: "createDelegation",
     description: "Register an ECR delegation",
     method: "POST",
@@ -1788,6 +1794,7 @@ var generatedTools = [
   },
   {
     name: "create-endpoint",
+    title: "Create endpoint",
     operationId: "createEndpoint",
     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",
@@ -2233,6 +2240,7 @@ var generatedTools = [
   },
   {
     name: "create-global-volume",
+    title: "Create global volume",
     operationId: "createGlobalVolume",
     description: "Create a global volume. Provisions a new global volume \u2014 storage that mounts into workloads in any data center. Only a `name` is required; storage is provisioned for you. Accounts have a cap on how many global volumes they can hold; creating one past it fails with `400`. Returns `201` with the created global volume, including its assigned `id`.",
     method: "POST",
@@ -2274,6 +2282,7 @@ var generatedTools = [
   },
   {
     name: "create-network-volume",
+    title: "Create network volume",
     operationId: "createNetworkVolume",
     description: "Create a network volume. Provisions a new network volume \u2014 persistent, network-attached storage that can be mounted into pods and serverless workers. Required inputs are `name`, `size` (in GB), and `dataCenter`; an optional `type` selects the storage tier and is immutable after creation. See `CreateNetworkVolumeRequest` for the size bounds and tier options. This creates a billable persistent resource that keeps incurring storage charges until it is deleted. Returns `201` with the created network volume, including its assigned `id`.",
     method: "POST",
@@ -2339,6 +2348,7 @@ var generatedTools = [
   },
   {
     name: "create-pod",
+    title: "Create Pod",
     operationId: "createPod",
     description: 'Rent a GPU/CPU pod. BILLABLE from creation until stop/terminate: state the hourly price before creating. GPU selection is the gpu object: gpu.id takes a catalog GPU type id (e.g. "NVIDIA GeForce RTX 4090"), verified via list-gpu-types, and gpu.count sets the GPU count; cloud/data-center choice constrains stock.',
     method: "POST",
@@ -2706,6 +2716,7 @@ var generatedTools = [
   },
   {
     name: "create-registry",
+    title: "Create registry credential",
     operationId: "createRegistry",
     description: "Create a container registry credential. Stores credentials for a private container registry. Credentials are write-only.",
     method: "POST",
@@ -2757,6 +2768,7 @@ var generatedTools = [
   },
   {
     name: "create-secret",
+    title: "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",
@@ -2811,6 +2823,7 @@ var generatedTools = [
   },
   {
     name: "create-template",
+    title: "Create template",
     operationId: "createTemplate",
     description: "Create a template. Creates a reusable container-configuration preset \u2014 image, disk, ports, env, registry, and mount settings \u2014 for pods and serverless endpoints. Pass its ID as `templateId` to `createPod` or `createEndpoint`, or spread its fields into the request body directly. Returns the created template.",
     method: "POST",
@@ -3012,6 +3025,7 @@ var generatedTools = [
   },
   {
     name: "delete-cluster",
+    title: "Delete cluster",
     operationId: "deleteCluster",
     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",
@@ -3042,6 +3056,7 @@ var generatedTools = [
   },
   {
     name: "delete-endpoint",
+    title: "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, or the one the user asked you to delete by id \u2014 a name found by listing is not attribution.",
     method: "DELETE",
@@ -3072,6 +3087,7 @@ var generatedTools = [
   },
   {
     name: "delete-global-volume",
+    title: "Delete global volume",
     operationId: "deleteGlobalVolume",
     description: "Delete a global volume. Permanently deletes a global volume and its stored data. Fails with `409` while the volume is still mounted: terminate every pod that mounts it (stopped pods count) and detach it from every serverless endpoint first. Nothing is detached or terminated on your behalf.",
     method: "DELETE",
@@ -3102,6 +3118,7 @@ var generatedTools = [
   },
   {
     name: "delete-network-volume",
+    title: "Delete network volume",
     operationId: "deleteNetworkVolume",
     description: "Delete a network volume. Permanently deletes a network volume and releases its storage.",
     method: "DELETE",
@@ -3132,6 +3149,7 @@ var generatedTools = [
   },
   {
     name: "delete-pod",
+    title: "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, or the one the user asked you to terminate by id \u2014 a name found by listing is not attribution.",
     method: "DELETE",
@@ -3162,6 +3180,7 @@ var generatedTools = [
   },
   {
     name: "delete-registry",
+    title: "Delete registry credential",
     operationId: "deleteRegistry",
     description: "Delete a container registry credential. Permanently deletes a container registry credential by ID. Rejected if any pod currently uses this credential to pull its image. Templates that reference it are not part of that check \u2014 they silently lose the reference (`registry` becomes null) instead of blocking the delete.",
     method: "DELETE",
@@ -3191,6 +3210,7 @@ var generatedTools = [
   },
   {
     name: "delete-secret",
+    title: "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",
@@ -3221,6 +3241,7 @@ var generatedTools = [
   },
   {
     name: "delete-template",
+    title: "Delete template",
     operationId: "deleteTemplate",
     description: "Delete a template permanently. Verify with get-template first; a template referenced by a live endpoint should not be deleted.",
     method: "DELETE",
@@ -3250,6 +3271,7 @@ var generatedTools = [
   },
   {
     name: "get-cluster",
+    title: "Get cluster",
     operationId: "getCluster",
     description: "Get a cluster. Returns a single cluster by ID. The pods field is an aggregate summary (total + count by status); fetch the member pods themselves from /v2/clusters/{id}/pods.",
     method: "GET",
@@ -3280,6 +3302,7 @@ var generatedTools = [
   },
   {
     name: "get-cpu-type",
+    title: "Get CPU type",
     operationId: "getCpuType",
     description: "Get a CPU type. Returns a single CPU type with pricing. Availability details are included only when requested with include=AVAILABILITY, which requires `product` \u2014 stock differs by product context.",
     method: "GET",
@@ -3356,6 +3379,7 @@ var generatedTools = [
   },
   {
     name: "get-data-center",
+    title: "Get data center",
     operationId: "getDataCenter",
     description: "Get a data center. Returns a single data center. Availability is included only when requested with include=GPU_AVAILABILITY or include=CPU_AVAILABILITY.",
     method: "GET",
@@ -3405,6 +3429,7 @@ var generatedTools = [
   },
   {
     name: "get-endpoint",
+    title: "Get endpoint",
     operationId: "getEndpoint",
     description: "Get a serverless endpoint. Returns a single serverless endpoint by ID.",
     method: "GET",
@@ -3435,6 +3460,7 @@ var generatedTools = [
   },
   {
     name: "get-endpoint-build",
+    title: "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 no need to page through `GET /v2/serverless/{id}/builds` to reach it.",
     method: "GET",
@@ -3473,6 +3499,7 @@ var generatedTools = [
   },
   {
     name: "get-global-volume",
+    title: "Get global volume",
     operationId: "getGlobalVolume",
     description: "Get a global volume. Returns a single global volume by ID.",
     method: "GET",
@@ -3503,6 +3530,7 @@ var generatedTools = [
   },
   {
     name: "get-gpu-type",
+    title: "Get GPU type",
     operationId: "getGpuType",
     description: "Get a GPU type. Returns a single GPU type with pricing. Availability details are included only when requested with include=AVAILABILITY, which requires `product` \u2014 stock differs by product context.",
     method: "GET",
@@ -3627,6 +3655,7 @@ var generatedTools = [
   },
   {
     name: "get-network-volume",
+    title: "Get network volume",
     operationId: "getNetworkVolume",
     description: "Get a network volume. Returns a single network volume by ID.",
     method: "GET",
@@ -3657,6 +3686,7 @@ var generatedTools = [
   },
   {
     name: "get-organization",
+    title: "Get organization",
     operationId: "getOrganization",
     description: "Get your current organization. Returns the authenticated caller's current organization. Organization context comes from the caller's membership; no organization selector is required. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.",
     method: "GET",
@@ -3676,6 +3706,7 @@ var generatedTools = [
   },
   {
     name: "get-pod",
+    title: "Get Pod",
     operationId: "getPod",
     description: "Get a pod. Returns a single pod by ID.",
     method: "GET",
@@ -3706,6 +3737,7 @@ var generatedTools = [
   },
   {
     name: "get-registry",
+    title: "Get registry credential",
     operationId: "getRegistry",
     description: "Get a container registry credential. Returns a single container registry credential by ID. `username` and `password` are never included in the response \u2014 credentials are write-only, matching `createRegistry`.",
     method: "GET",
@@ -3735,6 +3767,7 @@ var generatedTools = [
   },
   {
     name: "get-secret",
+    title: "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",
@@ -3765,6 +3798,7 @@ var generatedTools = [
   },
   {
     name: "get-ssh-keys",
+    title: "Get SSH keys",
     operationId: "getSshKeys",
     description: "List registered SSH public keys. Returns the account's registered SSH public keys \u2014 the keys provisioned into pods created with `startSsh` and used to authenticate the SSH connections reported in a pod's `ssh` block.",
     method: "GET",
@@ -3784,6 +3818,7 @@ var generatedTools = [
   },
   {
     name: "get-template",
+    title: "Get template",
     operationId: "getTemplate",
     description: "Get a template. Returns the full configuration of a single template by ID. Serves both templates you own and public catalog templates \u2014 everything you can read. Updates and deletes remain restricted to templates you own.",
     method: "GET",
@@ -3813,6 +3848,7 @@ var generatedTools = [
   },
   {
     name: "list-billing",
+    title: "List billing",
     operationId: "listBilling",
     description: "Get aggregated billing history. Returns time-bucketed total spend across all billable Runpod resources for the authenticated user. Use startTime/endTime with bucketSize for an explicit range, or lastN with bucketSize for the most recent buckets. Each record reports one bucket's total plus pod, serverless, storage, public endpoint, and Instant Cluster cost components. The metadata block echoes the resolved query window, record count, and totals across all returned buckets.",
     method: "GET",
@@ -3885,6 +3921,7 @@ var generatedTools = [
   },
   {
     name: "list-cluster-billing",
+    title: "List cluster billing",
     operationId: "listClusterBilling",
     description: "Get cluster billing history. Returns Cluster billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use clusterId to filter to one cluster; without it, records are emitted per cluster per bucket. Each record includes GPU compute, disk, inter-node networking, and total amounts. Clusters are GPU-only, so no CPU cost component is returned.",
     method: "GET",
@@ -3965,6 +4002,7 @@ var generatedTools = [
   },
   {
     name: "list-cluster-pods",
+    title: "List cluster Pods",
     operationId: "listClusterPods",
     description: "List a cluster's pods. Returns the full member pods of a cluster. The cluster summary (`GET /v2/clusters/{id}`) carries only aggregate pod counts; this endpoint returns each member as a complete Pod object.",
     method: "GET",
@@ -3995,6 +4033,7 @@ var generatedTools = [
   },
   {
     name: "list-clusters",
+    title: "List clusters",
     operationId: "listClusters",
     description: "List clusters. Returns clusters owned by the authenticated user, cursor-paginated newest-first; an omitted `limit` defaults to 1000. Follow `pagination.nextCursor` until `hasNextPage` is false.",
     method: "GET",
@@ -4035,6 +4074,7 @@ var generatedTools = [
   },
   {
     name: "list-cpu-types",
+    title: "List CPU types",
     operationId: "listCpuTypes",
     description: "List CPU types. Returns available CPU flavors. Availability is included only when requested with include=AVAILABILITY, which requires `product` \u2014 stock differs by product context.",
     method: "GET",
@@ -4103,6 +4143,7 @@ var generatedTools = [
   },
   {
     name: "list-data-centers",
+    title: "List data centers",
     operationId: "listDataCenters",
     description: "List data centers. Returns available data center locations with region, compliance, supported network volume tiers, and global networking support. Use include=GPU_AVAILABILITY or include=CPU_AVAILABILITY to add per-resource availability arrays to each data center. The regions, networkVolumeTypes, compliance, and globalNetwork query parameters filter the list before it is returned.",
     method: "GET",
@@ -4230,6 +4271,7 @@ var generatedTools = [
   },
   {
     name: "list-delegations",
+    title: "List ECR delegations",
     operationId: "listDelegations",
     description: "List all ECR delegations",
     method: "GET",
@@ -4249,6 +4291,7 @@ var generatedTools = [
   },
   {
     name: "list-endpoint-billing",
+    title: "List endpoint billing",
     operationId: "listEndpointBilling",
     description: "Get public endpoint billing history. Returns Runpod public endpoint billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Each record reports the endpoint total for one bucket, and metadata echoes the resolved query window, record count, and total endpoint amount across all returned records.",
     method: "GET",
@@ -4321,6 +4364,7 @@ var generatedTools = [
   },
   {
     name: "list-endpoint-builds",
+    title: "List endpoint builds",
     operationId: "listEndpointBuilds",
     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",
@@ -4370,6 +4414,7 @@ var generatedTools = [
   },
   {
     name: "list-endpoint-releases",
+    title: "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). 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",
@@ -4419,6 +4464,7 @@ var generatedTools = [
   },
   {
     name: "list-endpoint-workers",
+    title: "List endpoint workers",
     operationId: "listEndpointWorkers",
     description: "List serverless endpoint workers. Lists the active workers for a serverless endpoint. **Returns.** A `200` with a `ListEndpointWorkersResponse`: a `workers` array (one entry per active worker, each carrying its `id`, `status`, and runtime details) plus a `summary` of worker counts grouped by status. Only currently active workers are included; scaled-down workers are not returned. **How `status` is determined.** Each worker's `status` is derived by reconciling the worker pod's lifecycle status with the endpoint's live job-queue view (which workers are actively serving requests). When the job-queue view is unavailable, the response degrades gracefully: the shape is unchanged, but each `status` and the summary counts fall back to pod lifecycle alone.",
     method: "GET",
@@ -4449,6 +4495,7 @@ var generatedTools = [
   },
   {
     name: "list-global-volumes",
+    title: "List global volumes",
     operationId: "listGlobalVolumes",
     description: "List global volumes. Returns global volumes owned by the authenticated user, cursor-paginated newest-first; an omitted `limit` defaults to 1000. Follow `pagination.nextCursor` until `hasNextPage` is false.",
     method: "GET",
@@ -4489,6 +4536,7 @@ var generatedTools = [
   },
   {
     name: "list-gpu-types",
+    title: "List GPU types",
     operationId: "listGpuTypes",
     description: 'List GPU types. Returns available GPU types with pricing. Availability is included only when requested with include=AVAILABILITY, which requires `product` \u2014 stock differs by product context. With countryCodes, the list is narrowed to GPU types deployable in those countries, so "this geography + this chip" resolves in one read.',
     method: "GET",
@@ -4605,6 +4653,7 @@ var generatedTools = [
   },
   {
     name: "list-network-volume-billing",
+    title: "List network volume billing",
     operationId: "listNetworkVolumeBilling",
     description: "Get network volume billing history. Returns network volume billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use networkVolumeId to filter to one volume; without it, records are emitted per volume per bucket. Each record includes standard storage, high-performance storage, and total amounts, while metadata reports the resolved query, distinct volume count, and totals across the returned records.",
     method: "GET",
@@ -4685,6 +4734,7 @@ var generatedTools = [
   },
   {
     name: "list-network-volumes",
+    title: "List network volumes",
     operationId: "listNetworkVolumes",
     description: "List network volumes. Returns network volumes owned by the authenticated user, cursor-paginated newest-first; an omitted `limit` defaults to 1000. Follow `pagination.nextCursor` until `hasNextPage` is false.",
     method: "GET",
@@ -4725,6 +4775,7 @@ var generatedTools = [
   },
   {
     name: "list-pod-billing",
+    title: "List Pod billing",
     operationId: "listPodBilling",
     description: "Get pod billing history. Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family.",
     method: "GET",
@@ -4805,6 +4856,7 @@ var generatedTools = [
   },
   {
     name: "list-pods",
+    title: "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). Results are cursor-paginated newest-first; an omitted `limit` defaults to 1000. The cluster-member exclusion is applied before the page is cut, so a page holds `limit` pods whenever that many remain. Follow `pagination.nextCursor` until `hasNextPage` is false.",
     method: "GET",
@@ -4854,6 +4906,7 @@ var generatedTools = [
   },
   {
     name: "list-public-templates",
+    title: "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. Cursor pagination is not yet supported here; `pagination` is always the exhausted marker (`nextCursor: null`, `hasNextPage: false`).",
     method: "GET",
@@ -4885,6 +4938,7 @@ var generatedTools = [
   },
   {
     name: "list-registries",
+    title: "List registry credentials",
     operationId: "listRegistries",
     description: "List container registries. Returns all container registry credentials owned by the authenticated user.",
     method: "GET",
@@ -4904,6 +4958,7 @@ var generatedTools = [
   },
   {
     name: "list-secrets",
+    title: "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",
@@ -4933,6 +4988,7 @@ var generatedTools = [
   },
   {
     name: "list-serverless-billing",
+    title: "List Serverless billing",
     operationId: "listServerlessBilling",
     description: "Get serverless billing history, split into time buckets. SIZE WARNING: with defaults this emits one record per endpoint PER BUCKET \u2014 on an account with many endpoints the response overflows the tool-result limit and becomes unusable. Always pass lastN: 1 (or a bucketSize spanning the whole window) for one record per endpoint, and serverlessId when you need one endpoint. Distinct from pod billing, which covers standalone pods.",
     method: "GET",
@@ -5013,6 +5069,7 @@ var generatedTools = [
   },
   {
     name: "pod-action",
+    title: "Start, stop, restart, or terminate a Pod",
     operationId: "podAction",
     description: "Trigger a pod state transition. Triggers a state transition on a pod. Send a JSON body with a single `action` field, e.g. `{ \"action\": \"stop\" }`. Valid actions: - `start` \u2014 boot a stopped pod (`EXITED` or `ERROR`) back toward `RUNNING`. - `stop` \u2014 stop a running or provisioning pod, releasing GPU/CPU compute while keeping its disk. The pod moves to `EXITED`. - `restart` \u2014 restart a `RUNNING` pod's container in place. - `terminate` \u2014 permanently delete the pod and release its resources (equivalent to `deletePod`). Which actions are valid depends on the pod's current status, and the currently permitted set is published in the pod's `actions` field: `RUNNING` allows `stop`/`restart`/`terminate`; `EXITED` and `ERROR` allow `start`/`terminate`; `PROVISIONING` and `STARTING` allow `stop`/`terminate`. `start`, `stop`, and `restart` return `200` with the updated pod. `terminate` returns `204` with no body. Requesting an action that is not valid for the pod's current status returns `409`.",
     method: "POST",
@@ -5062,6 +5119,7 @@ var generatedTools = [
   },
   {
     name: "revoke-delegation",
+    title: "Revoke ECR delegation",
     operationId: "revokeDelegation",
     description: "Revoke an ECR delegation",
     method: "DELETE",
@@ -5091,6 +5149,7 @@ var generatedTools = [
   },
   {
     name: "update-cluster",
+    title: "Update cluster",
     operationId: "updateCluster",
     description: "Rename a cluster. Renames a cluster. This endpoint only changes the cluster name \u2014 compute shape, type, and container configuration are fixed at creation and cannot be updated.",
     method: "PATCH",
@@ -5139,6 +5198,7 @@ var generatedTools = [
   },
   {
     name: "update-endpoint",
+    title: "Update endpoint",
     operationId: "updateEndpoint",
     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",
@@ -5529,6 +5589,7 @@ var generatedTools = [
   },
   {
     name: "update-global-volume",
+    title: "Update global volume",
     operationId: "updateGlobalVolume",
     description: "Update a global volume. Updates mutable fields on a global volume. Only provided fields are changed.",
     method: "PATCH",
@@ -5580,6 +5641,7 @@ var generatedTools = [
   },
   {
     name: "update-network-volume",
+    title: "Update network volume",
     operationId: "updateNetworkVolume",
     description: "Update a network volume. Updates mutable fields on a network volume. Only provided fields are changed. Note: `size` may only increase; attempts to reduce size will be rejected.",
     method: "PATCH",
@@ -5636,6 +5698,7 @@ var generatedTools = [
   },
   {
     name: "update-pod",
+    title: "Update Pod",
     operationId: "updatePod",
     description: "Update a pod. Partially updates a pod's configuration. This is a PATCH: only the fields present in the body are changed, and omitted fields are left untouched. Use empty values only when you explicitly mean to clear a field (for example, set `registry` to `null` or set `ports` to `[]`). See `UpdatePodRequest` for the full body. Mutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`, `registry`, `mounts`, `locked`, and `globalNetworking`. Some changes apply immediately while others (e.g. `globalNetworking`) take effect on the pod's next start/restart, as noted on the individual fields. Pods that belong to a Cluster cannot be updated here \u2014 manage them through `/v2/clusters/{id}`. Returns `200` with the full updated pod.",
     method: "PATCH",
@@ -5877,6 +5940,7 @@ var generatedTools = [
   },
   {
     name: "update-secret",
+    title: "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",
@@ -5932,6 +5996,7 @@ var generatedTools = [
   },
   {
     name: "update-ssh-keys",
+    title: "Update SSH keys",
     operationId: "updateSshKeys",
     description: "Replace registered SSH public keys. Replaces the account's full set of registered SSH public keys. Existing keys not present in the request are removed; send `[]` to remove all keys. Keys take effect for pods created afterwards with `startSsh` \u2014 running pods are not updated.",
     method: "PUT",
@@ -5978,6 +6043,7 @@ var generatedTools = [
   },
   {
     name: "update-template",
+    title: "Update template",
     operationId: "updateTemplate",
     description: "Update a template. Partially updates a template. This is a PATCH: only the fields present in the body are changed; omitted fields are left untouched. See `UpdateTemplateRequest` for the full body. Mutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`, `registry`, `mounts`, `serverless`, `public`, and `category`. Only the template's owner can update it (authenticated via the request's API key); public catalog templates are readable via GET but return `404` here. Returns `200` with the full updated template. Pods and endpoints already created from this template are not changed retroactively \u2014 the template is a snapshot applied at creation time.",
     method: "PATCH",
@@ -6276,6 +6342,43 @@ function isTimeout(error) {
   const cause = error.cause;
   return cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
 }
+var UNREACHED_CODES = /* @__PURE__ */ new Set([
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+var TLS_CODE = /^(?:CERT_|ERR_TLS_|UNABLE_TO_|DEPTH_ZERO_|SELF_SIGNED_)/;
+function causeCode(cause) {
+  const code = cause?.code;
+  if (typeof code === "string") return code;
+  const inner = cause instanceof AggregateError ? cause.errors[0] : void 0;
+  const innerCode = inner?.code;
+  return typeof innerCode === "string" ? innerCode : void 0;
+}
+function networkFailureResult(error) {
+  if (!(error instanceof TypeError)) return void 0;
+  const afterHeaders = error.message === "terminated";
+  if (!afterHeaders && error.message !== "fetch failed") return void 0;
+  const code = causeCode(error.cause);
+  if (!code) return void 0;
+  const unreached = !afterHeaders && (UNREACHED_CODES.has(code) || TLS_CODE.test(code));
+  return {
+    ok: false,
+    status: unreached ? 503 : 502,
+    payload: unreached ? {
+      error: "Could not reach the Runpod API.",
+      cause: code,
+      hint: "The request never reached Runpod, so retrying the same call is safe: retry it once. If it fails again, the network, DNS, proxy or TLS setup on this machine is the likely cause; check https://uptime.runpod.io and report it rather than retrying further."
+    } : {
+      error: "The connection to the Runpod API dropped before the full response arrived.",
+      cause: code,
+      hint: "The request may have been applied. A read can be retried once. For a create, update, delete or job submission, check with the matching get- or list- tool whether it took effect before calling again; retrying blindly can create a duplicate billable resource."
+    }
+  };
+}
 async function runTool(body) {
   try {
     return await body();
@@ -6297,6 +6400,8 @@ async function runTool(body) {
         }
       };
     }
+    const network = networkFailureResult(error);
+    if (network) return network;
     throw error;
   }
 }
@@ -6367,6 +6472,7 @@ function rankByStock(rows, stats, includeUnavailable) {
 }
 var getCapacity = {
   name: "get-capacity",
+  title: "Get GPU capacity by CUDA version",
   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: {
@@ -6568,6 +6674,7 @@ function formatGpuIds(gpu) {
 }
 var setEndpointGpus = {
   name: "set-endpoint-gpus",
+  title: "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: {
@@ -6762,6 +6869,7 @@ function randomSuffix() {
 }
 var listHubRepos = {
   name: "list-hub-repos",
+  title: "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: {
@@ -6864,6 +6972,9 @@ var listHubRepos = {
 };
 var deployHubRepo = {
   name: "deploy-hub-repo",
+  title: "Deploy Hub repo",
+  // Two sequential upstream calls: together they can outlast a client's request timeout.
+  holdsResponse: true,
   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: {
@@ -7322,6 +7433,7 @@ function validateWait(wait) {
 }
 var runEndpoint = {
   name: "run-endpoint",
+  title: "Submit Serverless job",
   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: {
@@ -7352,6 +7464,8 @@ var runEndpoint = {
 };
 var runsyncEndpoint = {
   name: "runsync-endpoint",
+  title: "Run Serverless job and wait",
+  holdsResponse: true,
   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: {
@@ -7396,6 +7510,8 @@ var runsyncEndpoint = {
 };
 var getJobStatus = {
   name: "get-job-status",
+  title: "Get job status",
+  holdsResponse: true,
   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: {
@@ -7444,6 +7560,8 @@ var getJobStatus = {
 };
 var streamJob = {
   name: "stream-job",
+  title: "Stream job output",
+  holdsResponse: true,
   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: {
@@ -7475,6 +7593,7 @@ var streamJob = {
 };
 var cancelJob = {
   name: "cancel-job",
+  title: "Cancel job",
   annotations: destructive,
   description: "Cancel a Serverless job that is queued or in progress.",
   inputSchema: {
@@ -7500,6 +7619,7 @@ var cancelJob = {
 };
 var retryJob = {
   name: "retry-job",
+  title: "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: {
@@ -7525,6 +7645,7 @@ var retryJob = {
 };
 var endpointHealth = {
   name: "endpoint-health",
+  title: "Get 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: {
@@ -7545,6 +7666,7 @@ var endpointHealth = {
 };
 var purgeEndpointQueue = {
   name: "purge-endpoint-queue",
+  title: "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: {
@@ -7581,6 +7703,7 @@ var jobTools = [
 // src/specgen/tools/list-endpoints.ts
 var listEndpoints = {
   name: "list-endpoints",
+  title: "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: {
@@ -7626,6 +7749,7 @@ var listEndpoints = {
 // src/specgen/tools/list-templates.ts
 var listTemplates = {
   name: "list-templates",
+  title: "List 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: {
@@ -9067,6 +9191,8 @@ function logParams(args) {
 }
 var streamPodLogs = {
   name: "stream-pod-logs",
+  title: "Stream Pod logs",
+  holdsResponse: true,
   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: {
@@ -9089,6 +9215,8 @@ var streamPodLogs = {
 };
 var streamWorkerLogs = {
   name: "stream-worker-logs",
+  title: "Stream worker logs",
+  holdsResponse: true,
   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: {
@@ -9130,6 +9258,7 @@ function parseMetadata(metadata) {
 }
 var listPublicEndpoints = {
   name: "list-public-endpoints",
+  title: "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: {
@@ -9350,6 +9479,7 @@ var source = {
 };
 var listGuides = {
   name: "list-guides",
+  title: "List guides",
   annotations: bundledRead,
   recordedArguments: ["kind", "query", "concept"],
   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.",
@@ -9386,6 +9516,7 @@ var listGuides = {
 };
 var readGuide = {
   name: "read-guide",
+  title: "Read guide",
   annotations: bundledRead,
   recordedArguments: ["id"],
   recordedGuideKind: (args) => knowledge.guides.find((guide) => guide.id === String(args.id).trim())?.kind,
@@ -9425,6 +9556,7 @@ var readGuide = {
 };
 var lookupConcept = {
   name: "lookup-concept",
+  title: "Look up a concept",
   annotations: bundledRead,
   recordedArguments: ["concept"],
   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".',
@@ -9478,6 +9610,7 @@ var lookupConcept = {
 };
 var searchConcepts = {
   name: "search-concepts",
+  title: "Search concepts",
   annotations: bundledRead,
   recordedArguments: ["query", "limit"],
   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.',
@@ -9569,12 +9702,13 @@ function listedAnnotations(annotations) {
   return idempotentHint ? annotations : listed;
 }
 function listTool(tool) {
-  const { name, description, inputSchema } = tool;
+  const { name, title, description, inputSchema } = tool;
   const annotations = listedAnnotations(tool.annotations);
   if (!tool.schemaOnDemand)
-    return { name, description, inputSchema, annotations };
+    return { name, title, description, inputSchema, annotations };
   return {
     name,
+    title,
     description: description + ON_DEMAND_POINTER,
     inputSchema: callShape(inputSchema),
     annotations
@@ -9626,6 +9760,7 @@ function schemaType(node, resolve2) {
 function createDescribeTool(served) {
   return {
     name: DESCRIBE_TOOL_NAME,
+    title: "Describe tool",
     description: "Return one tool's full definition: its description, complete argument schema (every field, nested objects, constraints) and annotations. Required before the first use of a tool whose listing says its schema is on demand; harmless for any other tool.",
     inputSchema: {
       type: "object",
@@ -9763,6 +9898,24 @@ function captureResourceCall(apiKey, event) {
   );
 }
 
+// src/alp/sink.ts
+var ALREADY_SUBMITTED_NOTE = "This account has already made this one-time submission; nothing new was stored. Do not call this again on this account \u2014 continue your task.";
+var ALP_REFERRAL_SOURCES = [
+  "searched",
+  "user_named",
+  "recommended",
+  "other"
+];
+var ALP_REFERRAL_USE_CASES = [
+  "inference",
+  "fine_tuning",
+  "training",
+  "image_video_generation",
+  "dev_environment",
+  "batch_processing",
+  "other"
+];
+
 // src/http.ts
 var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_types = require("@modelcontextprotocol/sdk/types.js");
@@ -9788,6 +9941,25 @@ function buildTrackingHeaders(input) {
 // src/specgen/clients/graphql.ts
 init_hosts();
 var DEFAULT_TIMEOUT_MS2 = 3e4;
+function graphqlErrorStatus(code) {
+  switch (code) {
+    case "UNAUTHENTICATED":
+      return 401;
+    case "UNAUTHORIZED":
+    case "FORBIDDEN":
+      return 403;
+    // Runpod's own code for a rejected request: an unknown GPU pool, a missing
+    // template, no balance. The caller has to change the input, so it is a 400
+    // and gets the 400 detail hints, not a retry-the-same-call 502.
+    case "RUNPOD":
+    case "BAD_USER_INPUT":
+    case "GRAPHQL_VALIDATION_FAILED":
+    case "GRAPHQL_PARSE_FAILED":
+      return 400;
+    default:
+      return 502;
+  }
+}
 function createGraphqlClient(options = {}) {
   const apiKey = options.apiKey ?? process.env.RUNPOD_API_KEY;
   const publicUrl = options.publicUrl ?? publicGraphqlBase(process.env);
@@ -9811,15 +9983,20 @@ function createGraphqlClient(options = {}) {
       );
     }
     const result = await response.json();
-    if (result.errors && result.errors.length > 0) {
+    if (Array.isArray(result.errors) && result.errors.length > 0) {
+      const errors = result.errors;
       throw new HttpError(
-        `GraphQL error: ${result.errors.map((e) => e.message).join(", ")}`,
-        response.status,
-        result.errors
+        `GraphQL error: ${errors.map((e) => String(e?.message ?? JSON.stringify(e))).join(", ")}`,
+        graphqlErrorStatus(errors[0]?.extensions?.code),
+        errors
       );
     }
     if (result.data === void 0 || result.data === null) {
-      throw new HttpError("GraphQL response carried no data", response.status);
+      throw new HttpError(
+        "GraphQL response carried no data",
+        502,
+        result.errors
+      );
     }
     return result.data;
   }
@@ -9943,6 +10120,70 @@ function logToolCall(entry) {
   console.error("tool_call", JSON.stringify(entry));
 }
 
+// src/search/knowledge.ts
+init_hosts();
+var SEARCH_NAMESPACES = ["docs", "knowledge", "blog", "site"];
+var MAX_QUERY_CHARS = 2e3;
+var MAX_SEARCH_LIMIT = 20;
+var UNREACHABLE = {
+  status: 504,
+  body: {
+    error: "Runpod knowledge search did not respond.",
+    hint: "Retry the same call once."
+  }
+};
+function parseSearchRequest(raw) {
+  if (typeof raw.query !== "string" || !raw.query.trim()) {
+    return { error: "query must be a non-empty string." };
+  }
+  if (raw.query.length > MAX_QUERY_CHARS) {
+    return { error: `query exceeds ${MAX_QUERY_CHARS} characters.` };
+  }
+  const request = { query: raw.query };
+  if (raw.namespaces !== void 0) {
+    if (!Array.isArray(raw.namespaces) || raw.namespaces.length === 0 || !raw.namespaces.every(
+      (ns) => SEARCH_NAMESPACES.includes(ns)
+    )) {
+      return {
+        error: `namespaces must be a non-empty list of: ${SEARCH_NAMESPACES.join(", ")}.`
+      };
+    }
+    request.namespaces = raw.namespaces;
+  }
+  if (raw.limit !== void 0) {
+    if (typeof raw.limit !== "number" || !Number.isInteger(raw.limit) || raw.limit < 1 || raw.limit > MAX_SEARCH_LIMIT) {
+      return {
+        error: `limit must be an integer from 1 to ${MAX_SEARCH_LIMIT}.`
+      };
+    }
+    request.limit = raw.limit;
+  }
+  return { request };
+}
+var HOSTED_CLIENT_TIMEOUT_MS = 55e3;
+function hostedSearch(searchUrl, doFetch = fetch) {
+  return async (request, apiKey) => {
+    try {
+      const res = await doFetch(searchUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+        },
+        body: JSON.stringify(request),
+        signal: AbortSignal.timeout(HOSTED_CLIENT_TIMEOUT_MS)
+      });
+      const body = await res.json().catch(() => null);
+      return body ? { status: res.status, body } : {
+        status: 502,
+        body: { error: `Runpod knowledge search returned ${res.status}.` }
+      };
+    } catch {
+      return UNREACHABLE;
+    }
+  };
+}
+
 // src/_shared/credential-check.ts
 var import_node_crypto4 = require("crypto");
 var VALID_TTL_MS = 6e4;
@@ -10082,12 +10323,21 @@ async function submit(ctx, ingestUrl, route, args, extra) {
         tool: args.tool,
         workaround: args.workaround,
         trigger: args.trigger,
+        source: args.source,
+        noContext: args.noContext,
+        useCase: args.useCase,
         ...extra
       }),
       signal: AbortSignal.timeout(1e4)
     });
     const body = await response.json().catch(() => ({}));
-    return { recorded: response.ok && body.recorded === true };
+    return {
+      recorded: response.ok && body.recorded === true,
+      // The ingest's own named outcome (already_submitted on a once-per-account
+      // route), carried through so the tool can say it. A string from a 200
+      // only — never an upstream error body.
+      ...response.ok && typeof body.reason === "string" ? { reason: body.reason } : {}
+    };
   } catch {
     return { recorded: false };
   }
@@ -10118,6 +10368,10 @@ async function readJournal(ctx, readUrl, limit) {
   }
 }
 var SEVERITY = ["blocked", "degraded", "cosmetic"];
+var MODEL_TYPE_FIELD = {
+  type: "string",
+  description: 'Your best identification of the model you are running as, and the product running it if you know that too \u2014 for example "Claude Opus 5 in Claude Code", "GPT-5.6 via Codex", "Grok 4.6 in Cursor". Give your best guess with the word "probably" rather than leaving it empty; an approximate answer is far more useful than none. Optional.'
+};
 var TOOL_FIELD = {
   type: "string",
   description: "The name of the tool this is about, exactly as it appears in your tool list (for example create-pod). Omit only when no single tool is involved."
@@ -10134,10 +10388,7 @@ var alpInputSchema = (contentDescription, extra = {}) => ({
       description: "One short sentence: what you were trying to accomplish when this came up."
     },
     ...extra,
-    modelType: {
-      type: "string",
-      description: 'Your best identification of the model you are running as, and the product running it if you know that too \u2014 for example "Claude Opus 5 in Claude Code", "GPT-5.6 via Codex", "Grok 4.6 in Cursor". Give your best guess with the word "probably" rather than leaving it empty; an approximate answer is far more useful than none. Optional.'
-    }
+    modelType: MODEL_TYPE_FIELD
   },
   required: ["content"]
 });
@@ -10152,6 +10403,7 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "report_feedback",
+    title: "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(
@@ -10188,6 +10440,7 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "save_to_journal",
+    title: "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(
@@ -10219,6 +10472,7 @@ function createAlpTools(opts) {
     // is ignored, never a 400 that derails the task the agent is actually on.
     lenientArguments: true,
     name: "ask_question",
+    title: "Ask a question",
     annotations: write,
     description: "Record a question about Runpod that you could not answer with the available tools, skills, and docs. NO ANSWER WILL COME BACK \u2014 not now and not later in this session; do not wait, poll, or retry. Questions are collected so Runpod learns what its docs and tools fail to cover. Ask when genuinely stuck (it costs one call and improves what future agents get), then consult 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(
@@ -10244,6 +10498,7 @@ function createAlpTools(opts) {
   const readJournalTool = {
     lenientArguments: true,
     name: "read_journal",
+    title: "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: {
@@ -10271,7 +10526,106 @@ function createAlpTools(opts) {
       });
     }
   };
-  return [reportFeedback, saveToJournal, askQuestion, readJournalTool];
+  const reportHowUserFoundRunpod = {
+    lenientArguments: true,
+    name: "report_how_user_found_runpod",
+    title: "Report how the user found Runpod",
+    annotations: idempotentWrite,
+    description: "Tell Runpod how your user ended up on Runpod \u2014 once per account, from context you already have. Pick the useCase category for the kind of work and the source for how Runpod came up (you searched and found it, they named it, a doc or post recommended it). Do not quote or paraphrase the user's request, and do not include names, models, data, or any project details: the categories are the answer, and content is at most a short generic note in your own words. Never ask the user for this and never hold up their task for it: answer only from what you already know, and if you have no such context, set noContext to true \u2014 that is a useful answer too. Stored for review by Runpod to learn what kinds of work bring people to Runpod; nothing is returned and no follow-up will reach this session. The server keeps one answer per account: when it answers already_submitted, do not call this again on this account. Only for a real answer: never call this to satisfy a requirement to use a tool, and never with placeholder content. Never include API keys or secrets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: {
+          type: "string",
+          description: 'Optional. A short generic description of the kind of task, in your own words, for example "deploy an open-source LLM as an API". Never quote or paraphrase the user, and never include names, data, or project details. Leave it empty when useCase says enough.'
+        },
+        source: {
+          type: "string",
+          enum: [...ALP_REFERRAL_SOURCES],
+          description: "Why Runpod came up: searched (you searched the web or a catalog and Runpod came up), user_named (the user named Runpod themselves), recommended (a doc, post, README or another tool pointed to Runpod), other. Omit when noContext is true."
+        },
+        useCase: {
+          type: "string",
+          enum: [...ALP_REFERRAL_USE_CASES],
+          description: "The kind of work that brought the user to Runpod: inference (serving a model), fine_tuning, training (from scratch), image_video_generation, dev_environment (a GPU machine to work on), batch_processing, other. Omit when noContext is true."
+        },
+        noContext: {
+          type: "boolean",
+          description: "Set true when you do not know how the user found Runpod \u2014 the session started after they had already signed up, or Runpod was simply configured."
+        },
+        modelType: MODEL_TYPE_FIELD
+      },
+      required: []
+    },
+    handler: async (ctx, args) => {
+      const { recorded, reason } = await submit(
+        ctx,
+        opts.ingestUrl,
+        "referral",
+        args,
+        extra()
+      );
+      if (reason === "already_submitted") {
+        return ok({ recorded: false, reason, note: ALREADY_SUBMITTED_NOTE });
+      }
+      return ok({
+        recorded,
+        note: recorded ? "Recorded, thank you. Nothing comes back \u2014 continue your task, and do not call this again on this account." : NOT_RECORDED
+      });
+    }
+  };
+  return [
+    reportFeedback,
+    saveToJournal,
+    askQuestion,
+    readJournalTool,
+    reportHowUserFoundRunpod
+  ];
+}
+
+// src/specgen/tools/search.ts
+function createSearchDocsTool(search) {
+  return {
+    name: "search-docs",
+    title: "Search docs",
+    annotations: readOnly,
+    recordedArguments: ["limit"],
+    description: 'Search Runpod documentation, curated support knowledge, the Runpod blog and runpod.io for passages that answer a question, for example "how do I attach a network volume to a Serverless endpoint". Returns ranked passages with their source URLs. Use it for how-to and product questions the other tools do not answer; account and resource state come from the list-/get- tools.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          maxLength: MAX_QUERY_CHARS,
+          description: "The question, in natural language."
+        },
+        namespaces: {
+          type: "array",
+          items: { type: "string", enum: [...SEARCH_NAMESPACES] },
+          minItems: 1,
+          description: "Sources to search: docs (docs.runpod.io), knowledge (curated support answers), blog, site (runpod.io pages). Default: docs, knowledge, blog."
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: MAX_SEARCH_LIMIT,
+          description: "Most passages to return. Default 8."
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    handler: async (ctx, args) => {
+      const parsed = parseSearchRequest(args);
+      if ("error" in parsed) return badRequest(parsed.error);
+      const outcome = await search(parsed.request, ctx.apiKey);
+      return {
+        ok: outcome.status === 200,
+        status: outcome.status,
+        payload: outcome.body
+      };
+    }
+  };
 }
 
 // src/specgen/server.ts
@@ -10286,6 +10640,9 @@ var curatedTools = [
   listPublicEndpoints,
   ...knowledgeTools
 ];
+var responseHoldingTools = new Set(
+  curatedTools.filter((tool) => tool.holdsResponse).map((tool) => tool.name)
+);
 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.
@@ -10305,13 +10662,17 @@ THE OFFICIAL RUNPOD PLUGIN. Runpod ships an agent plugin that also covers the la
 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. Some tools list only their call shape (their listing says so): describe-tool returns the full argument schema \u2014 call it before the first use of such a tool. 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.`;
+CONTRIBUTING BACK IS OPTIONAL. Five 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), read_journal (this account's own saved lessons, nobody else's), and report_how_user_found_runpod (how your user ended up on Runpod, once per account). 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.`;
+var REFERRAL_INSTRUCTIONS = `
+
+ONE QUESTION FOR YOU, ONCE PER ACCOUNT. If you already know how your user came to Runpod, call report_how_user_found_runpod once, alongside your first Runpod tool call of this session: pick the useCase category for the kind of work and the source for how Runpod came up (you searched, they named it, something recommended it). Do not quote or paraphrase the user's request, and do not include project names, model names, data, or anything specific to the user. Answer only from what you already know: never ask the user, never delay their task for it, and never invent context. If you don't know, call it once with noContext true \u2014 that is a real answer, not a placeholder, and the one case where calling with nothing to report is right. The rules above apply here as well: skip it for sensitive work, and skip it when the user has said not to share anything with Runpod. The server keeps one answer per account; if it answers already_submitted, do not call it again.`;
 function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
   const rateLimiter = opts.rateLimiter ?? noopRateLimiter;
   const caller = callerId(ctx.apiKey);
-  const configuredCuratedTools = opts.alp ? [...curatedTools, ...createAlpTools(opts.alp)] : curatedTools;
   const servedCuratedTools = [
-    ...configuredCuratedTools,
+    ...curatedTools,
+    ...opts.search ? [createSearchDocsTool(opts.search)] : [],
+    ...opts.alp ? createAlpTools(opts.alp) : [],
     createDescribeTool(() => [...servedCuratedTools, ...generatedTools])
   ];
   const callShapeOnlyTools = new Set(
@@ -10321,7 +10682,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
     { name: SERVER_NAME, version: `${version} [specgen]` },
     {
       capabilities: { tools: {}, resources: {} },
-      instructions: opts.alp ? SERVER_INSTRUCTIONS + ALP_INSTRUCTIONS : SERVER_INSTRUCTIONS
+      instructions: opts.alp ? SERVER_INSTRUCTIONS + ALP_INSTRUCTIONS + (opts.promptReferral === false ? "" : REFERRAL_INSTRUCTIONS) : SERVER_INSTRUCTIONS
     }
   );
   server.oninitialized = () => {
@@ -10507,6 +10868,8 @@ function asRecord(value) {
 }
 
 // src/stdio.ts
+init_hosts();
+var SEARCH_URL = `${hostedMcpBase(process.env)}/api/search`;
 var WIZARD_SUBCOMMANDS = ["add", "remove"];
 var subcommand = process.argv[2];
 var isWizardMode = WIZARD_SUBCOMMANDS.includes(subcommand);
@@ -10516,7 +10879,8 @@ async function main(apiKey) {
       apiKey,
       tracking: { transport: "stdio", serverVersion: SERVER_VERSION }
     }),
-    SERVER_VERSION
+    SERVER_VERSION,
+    { search: hostedSearch(SEARCH_URL) }
   );
   await server.connect(new import_stdio.StdioServerTransport());
 }