@blazingagents/sdk 0.33.0 → 0.35.0

package/dist/contracts/entities/chat.d.ts

@@ -78,6 +78,7 @@ export declare const blazingAgentsChatMessageMetadataSchema: z.ZodObject<{
             tenantId: z.ZodString;
             userId: z.ZodString;
         }, z.core.$strip>;
+        compactedContext: z.ZodOptional<z.ZodArray<z.ZodType<import("ai").ModelMessage, unknown, z.core.$ZodTypeInternals<import("ai").ModelMessage, unknown>>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 /**
@@ -183,10 +184,13 @@ export declare const chatRequestBodySchema: z.ZodObject<{
     messageId: z.ZodOptional<z.ZodString>;
     userId: z.ZodDefault<z.ZodString>;
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    functions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        description: z.ZodString;
-        inputSchema: z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>;
-    }, z.core.$strict>>>;
+    functions: z.ZodOptional<z.ZodCustom<Record<string, {
+        description: string;
+        inputSchema: z.core.JSONSchema.JSONSchema;
+    }>, Record<string, {
+        description: string;
+        inputSchema: z.core.JSONSchema.JSONSchema;
+    }>>>;
 }, z.core.$strict> & z.ZodType<{
     messages?: unknown[] | undefined;
     promptId?: string | undefined;

package/dist/contracts/entities/chat.js

@@ -1,3 +1,4 @@
+import { modelMessageSchema } from "ai";
 import { z } from "zod";
 import { agentIdSchema, functionCallIdSchema, promptIdSchema, sessionIdSchema, tenantIdSchema, turnIdSchema, } from "../ids.js";
 import { chatFunctionNameSchema } from "./agent-tools.js";
@@ -26,9 +27,8 @@ export const usageSummarySchema = z
     errorMessage: z.string().nullable(),
     inputTokens: z.number().int().min(0),
     /**
-     * True only when every measured inference for this Turn reported
-     * input/output totals. Provider omissions stay unknown — a zero is never
-     * substituted for a missing measurement (ADR-0048).
+     * True only when every inference reported input/output totals; a zero is
+     * never substituted for a missing measurement (ADR-0048).
      */
     measurementComplete: z.boolean(),
     modelDurationMs: z.number().int().min(0),
@@ -54,7 +54,12 @@ export const usageSummarySchema = z
     .strip();
 export const blazingAgentsChatMessageMetadataSchema = z
     .object({
-    blazingAgents: z.object({ usage: usageSummarySchema }).strip(),
+    blazingAgents: z
+        .object({
+        usage: usageSummarySchema,
+        compactedContext: z.array(modelMessageSchema).optional(),
+    })
+        .strip(),
 })
     .strip();
 /**
@@ -78,7 +83,10 @@ function hasMeaningfulSchemaRoot(value, definitions, seenReferences) {
     }
     const reference = schema.$ref;
     if (typeof reference === "string" && reference.startsWith("#/$defs/")) {
-        const name = reference.slice("#/$defs/".length);
+        const name = reference
+            .slice("#/$defs/".length)
+            .replaceAll("~1", "/")
+            .replaceAll("~0", "~");
         if (!name || seenReferences.has(name) || !(name in definitions)) {
             return false;
         }
@@ -102,7 +110,8 @@ function hasMeaningfulSchemaRoot(value, definitions, seenReferences) {
  * unions (for example, Pydantic's `int | None` TypeAdapter schema), and local
  * `$ref` roots are needed for recursive Pydantic models.
  */
-export const jsonSchemaShapeSchema = z.custom((value) => {
+export const jsonSchemaShapeSchema = z
+    .custom((value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return false;
     }
@@ -123,7 +132,12 @@ export const jsonSchemaShapeSchema = z.custom((value) => {
     catch {
         return false;
     }
-}, { message: "schema contains an unsupported or invalid JSON Schema feature" });
+}, { message: "schema contains an unsupported or invalid JSON Schema feature" })
+    /**
+     * `z.custom` is opaque to the OpenAPI generator; declare the honest wire
+     * shape (any JSON object) for the generated document.
+     */
+    .meta({ type: "object" });
 export const MAX_CHAT_FUNCTIONS = 32;
 export const MAX_CHAT_FUNCTION_DEFINITIONS_BYTES = 64 * 1024;
 export const MAX_CHAT_FUNCTION_PAYLOAD_BYTES = 256 * 1024;
@@ -202,23 +216,68 @@ export const resolveChatFunctionResponseSchema = z
 export const chatRequestBodySchema = z
     .object({
     /**
-     * AI SDK owns the runtime UIMessage schema. Core keeps this wire field
-     * unknown; the HTTP boundary validates it with `safeValidateUIMessages`
-     * before treating it as a UIMessage.
+     * AI SDK owns the UIMessage schema; the HTTP boundary validates this with
+     * `safeValidateUIMessages`.
      */
-    messages: z.array(z.unknown()).min(1).optional(),
-    promptId: promptIdSchema.optional(),
-    variables: promptVariablesSchema.optional(),
-    trigger: chatTriggerSchema.default("submit-message"),
-    messageId: z.string().min(1).optional(),
+    messages: z
+        .array(z.unknown())
+        .min(1)
+        .optional()
+        .describe('Ordered messages for one Turn, each an AI SDK `UIMessage` with `role: "user"`, an `id`, and non-empty `parts`. Parts can be text, or `file` parts with an `image/*` media type and a base64 `data:` URL. Send either `messages` or `promptId`.'),
+    promptId: promptIdSchema
+        .optional()
+        .describe("ID of a saved prompt to send instead of `messages`."),
+    variables: promptVariablesSchema
+        .optional()
+        .describe("Values for the saved prompt's variables. Allowed only with `promptId`, and must name exactly the prompt's variables."),
+    trigger: chatTriggerSchema
+        .default("submit-message")
+        .describe("`submit-message` (the default) sends a new message. `regenerate-message` generates the answer again and is allowed only when continuing a session."),
+    messageId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("With `regenerate-message`, the message to cut the conversation back to before the answer is generated again."),
     /**
-     * End-user attribution (ADR-0001), stamped on the Session at lazy
-     * materialization and on every usage row this Turn records.
+     * Stamps the session row at lazy materialization and every
+     * `token_usage_*` row this turn records (ADR-0001).
      */
-    userId: userIdSchema.default(""),
-    metadata: metadataSchema.default({}),
-    /** Caller-local functions for this invocation; handlers stay in the caller's backend. */
-    functions: chatFunctionDefinitionsSchema.optional(),
+    userId: userIdSchema
+        .default("")
+        .describe("Your end user's ID. Starting a session records it on the session, and every turn in that session keeps the session's end user."),
+    metadata: metadataSchema
+        .default({})
+        .describe("Your own key-value data. Recorded on a new session and on the turn's usage."),
+    /**
+     * `chatFunctionDefinitionsSchema` validates the value; `z.custom` is opaque
+     * to the OpenAPI generator, so `meta` declares the wire shape.
+     */
+    functions: z
+        .custom((value) => typeof value === "object" && value !== null)
+        .check((context) => {
+        const result = chatFunctionDefinitionsSchema.safeParse(context.value);
+        if (!result.success) {
+            context.issues.push({
+                code: "custom",
+                input: context.value,
+                message: z.prettifyError(result.error),
+            });
+        }
+    })
+        .optional()
+        .meta({
+        additionalProperties: {
+            additionalProperties: false,
+            properties: {
+                description: { type: "string" },
+                inputSchema: { type: "object" },
+            },
+            required: ["description", "inputSchema"],
+            type: "object",
+        },
+        type: "object",
+    })
+        .describe("Caller-local functions the model may call during this turn, keyed by name; each entry has a `description` and a JSON Schema `inputSchema`. Your backend claims and answers each call through the function-call endpoints."),
 })
     .strict()
     .refine((body) => body.messages === undefined
@@ -234,17 +293,32 @@ export const chatRequestBodySchema = z
  */
 export const generationRequestBodySchema = z
     .object({
-    prompt: z.string().trim().min(1).optional(),
-    promptId: promptIdSchema.optional(),
-    variables: promptVariablesSchema.optional(),
-    output: z.discriminatedUnion("type", [
+    prompt: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("The prompt to answer. Send either `prompt` or `promptId`."),
+    promptId: promptIdSchema
+        .optional()
+        .describe("ID of a saved prompt to use instead of `prompt`."),
+    variables: promptVariablesSchema
+        .optional()
+        .describe("Values for the saved prompt's variables. Allowed only with `promptId`, and must name exactly the prompt's variables."),
+    output: z
+        .discriminatedUnion("type", [
         z.object({ type: z.literal("text") }).strict(),
         z
             .object({ type: z.literal("object"), schema: jsonSchemaShapeSchema })
             .strict(),
-    ]),
-    userId: userIdSchema.default(""),
-    metadata: metadataSchema.default({}),
+    ])
+        .describe('What to stream back: `{"type":"text"}` for text, or `{"type":"object","schema":{…}}` for JSON that matches a JSON Schema.'),
+    userId: userIdSchema
+        .default("")
+        .describe("Your end user's ID, used for usage attribution."),
+    metadata: metadataSchema
+        .default({})
+        .describe("Your own key-value data, recorded with the usage."),
 })
     .strict()
     .refine((body) => body.prompt === undefined

package/dist/contracts/entities/mcp-connections.d.ts

@@ -239,6 +239,8 @@ export declare const mcpConnectionReconnectResultSchema: z.ZodDiscriminatedUnion
 }, z.core.$strip>], "status">;
 export type McpConnectionAuthType = z.infer<typeof mcpConnectionAuthTypeSchema>;
 export type McpConnectionStatus = z.infer<typeof mcpConnectionStatusSchema>;
+export type McpConnectionTestErrorCode = z.infer<typeof mcpConnectionTestErrorCodeSchema>;
+export type McpConnectionLiveDetails = z.infer<typeof mcpConnectionLiveDetailsSchema>;
 export type McpConnectionResponse = z.infer<typeof mcpConnectionResponseSchema>;
 export type McpConnectionsResponse = z.infer<typeof mcpConnectionsResponseSchema>;
 export type CreateMcpConnectionBody = z.infer<typeof createMcpConnectionBodySchema>;

package/dist/contracts/entities/mcp-connections.js

@@ -25,27 +25,33 @@ const mcpConnectionNameSchema = z
     .trim()
     .min(1)
     .max(MAX_MCP_CONNECTION_NAME_LENGTH);
+/** Request bodies describe the field; responses carry the bare value. */
+const mcpConnectionNameInputSchema = mcpConnectionNameSchema.describe("Display name of the connection, unique within your tenant.");
 const bearerTokenSchema = z
     .string()
     .min(1)
     .max(MAX_MCP_BEARER_TOKEN_LENGTH)
-    .regex(/^[!-~]+$/, "Bearer token must contain visible ASCII characters only");
+    .regex(/^[!-~]+$/, "Bearer token must contain visible ASCII characters only")
+    .describe("Token sent as `Authorization: Bearer <token>` to the MCP server. Required when `authType` is `bearer`. Never returned.");
 const oauthClientIdSchema = z
     .string()
     .min(1)
     .max(MAX_MCP_OAUTH_CLIENT_ID_LENGTH)
-    .regex(/^[!-~]+$/, "Client ID must contain visible ASCII characters only");
+    .regex(/^[!-~]+$/, "Client ID must contain visible ASCII characters only")
+    .describe("OAuth client ID. Required with `clientSecret` for `oauth_client_credentials`. Optional for `oauth_authorization_code`, but send it together with `clientSecret`.");
 const oauthClientSecretSchema = z
     .string()
     .min(1)
     .max(MAX_MCP_OAUTH_CLIENT_SECRET_LENGTH)
-    .regex(/^[!-~]+$/, "Client secret must contain visible ASCII characters only");
+    .regex(/^[!-~]+$/, "Client secret must contain visible ASCII characters only")
+    .describe("OAuth client secret. Required with `clientId` for `oauth_client_credentials`. Optional for `oauth_authorization_code`, but send it together with `clientId`. Never returned.");
 const oauthScopeSchema = z
     .string()
     .trim()
     .min(1)
     .max(MAX_MCP_OAUTH_SCOPE_LENGTH)
-    .regex(/^[\x20-\x7e]+$/, "Scope must contain printable ASCII characters only");
+    .regex(/^[\x20-\x7e]+$/, "Scope must contain printable ASCII characters only")
+    .describe("OAuth scope to request. Optional for either OAuth type.");
 const credentialFragmentSchema = z.string().min(1).max(4).nullable();
 const mcpConnectionUrlSchema = z
     .string()
@@ -68,6 +74,8 @@ const mcpConnectionUrlSchema = z
     message: "URL must use http(s) without credentials, query, or fragment",
 })
     .transform((value) => new URL(value).toString());
+const mcpConnectionUrlInputSchema = mcpConnectionUrlSchema.describe("Streamable HTTP URL of the MCP server. Use `http` or `https`, with no credentials, query, or fragment.");
+const authTypeDescription = "How Blazing Agents authenticates to the MCP server: `none`, `bearer`, `oauth_client_credentials`, or `oauth_authorization_code`. The other fields you send depend on it.";
 export const mcpConnectionResponseSchema = z
     .object({
     id: mcpConnectionIdSchema,
@@ -111,8 +119,13 @@ export const mcpAttachmentsResponseSchema = z
     .strip();
 export const updateMcpAttachmentBodySchema = z
     .object({
-    forwardUserId: z.boolean().optional(),
-    forwardedMetadataKeys: forwardedMetadataKeysSchema.optional(),
+    forwardUserId: z
+        .boolean()
+        .optional()
+        .describe("Send the session's `userId` to the MCP server with every tool call."),
+    forwardedMetadataKeys: forwardedMetadataKeysSchema
+        .optional()
+        .describe("Session metadata keys whose values are sent to the MCP server with every tool call. Replaces the current list."),
 })
     .strict()
     .refine(hasObjectKeys, {
@@ -120,43 +133,43 @@ export const updateMcpAttachmentBodySchema = z
 });
 const createNoneMcpConnectionBodySchema = z
     .object({
-    name: mcpConnectionNameSchema,
-    url: mcpConnectionUrlSchema,
-    authType: z.literal("none"),
+    name: mcpConnectionNameInputSchema,
+    url: mcpConnectionUrlInputSchema,
+    authType: z.literal("none").describe(authTypeDescription),
 })
     .strict();
 const createBearerMcpConnectionBodySchema = z
     .object({
-    name: mcpConnectionNameSchema,
-    url: mcpConnectionUrlSchema,
-    authType: z.literal("bearer"),
+    name: mcpConnectionNameInputSchema,
+    url: mcpConnectionUrlInputSchema,
+    authType: z.literal("bearer").describe(authTypeDescription),
     bearerToken: bearerTokenSchema,
 })
     .strict();
 const oauthClientCredentialsFields = {
-    authType: z.literal("oauth_client_credentials"),
+    authType: z.literal("oauth_client_credentials").describe(authTypeDescription),
     clientId: oauthClientIdSchema,
     clientSecret: oauthClientSecretSchema,
     scope: oauthScopeSchema.optional(),
-    url: mcpConnectionUrlSchema,
+    url: mcpConnectionUrlInputSchema,
 };
 const oauthAuthorizationCodeFields = {
-    authType: z.literal("oauth_authorization_code"),
+    authType: z.literal("oauth_authorization_code").describe(authTypeDescription),
     clientId: oauthClientIdSchema.optional(),
     clientSecret: oauthClientSecretSchema.optional(),
     scope: oauthScopeSchema.optional(),
-    url: mcpConnectionUrlSchema,
+    url: mcpConnectionUrlInputSchema,
 };
 const createOauthAuthorizationCodeMcpConnectionBodySchema = z
     .object({
     ...oauthAuthorizationCodeFields,
-    name: mcpConnectionNameSchema,
+    name: mcpConnectionNameInputSchema,
 })
     .strict();
 const createOauthClientCredentialsMcpConnectionBodySchema = z
     .object({
     ...oauthClientCredentialsFields,
-    name: mcpConnectionNameSchema,
+    name: mcpConnectionNameInputSchema,
 })
     .strict();
 export const createMcpConnectionBodySchema = z
@@ -178,7 +191,7 @@ export const createMcpConnectionBodySchema = z
 });
 export const updateMcpConnectionBodySchema = z
     .object({
-    name: mcpConnectionNameSchema.optional(),
+    name: mcpConnectionNameInputSchema.optional(),
 })
     .strict()
     .refine(hasObjectKeys, {
@@ -188,15 +201,15 @@ export const reconnectMcpConnectionBodySchema = z
     .discriminatedUnion("authType", [
     z
         .object({
-        authType: z.literal("none"),
-        url: mcpConnectionUrlSchema,
+        authType: z.literal("none").describe(authTypeDescription),
+        url: mcpConnectionUrlInputSchema,
     })
         .strict(),
     z
         .object({
-        authType: z.literal("bearer"),
+        authType: z.literal("bearer").describe(authTypeDescription),
         bearerToken: bearerTokenSchema,
-        url: mcpConnectionUrlSchema,
+        url: mcpConnectionUrlInputSchema,
     })
         .strict(),
     z.object(oauthAuthorizationCodeFields).strict(),

package/dist/contracts/entities/memories.d.ts

@@ -42,6 +42,7 @@ export declare const createMemoryBodySchema: z.ZodObject<{
 export declare const updateMemoryBodySchema: z.ZodObject<{
     text: z.ZodString;
 }, z.core.$strict>;
+export type Memory = z.infer<typeof memorySchema>;
 export type MemoryResponse = z.infer<typeof memoryResponseSchema>;
 export type MemoriesListResponse = z.infer<typeof memoriesListResponseSchema>;
 export type CreateMemoryBody = z.input<typeof createMemoryBodySchema>;

package/dist/contracts/entities/memories.js

@@ -38,12 +38,14 @@ export const memoryResponseSchema = z
 export const memoriesListResponseSchema = paginatedResponseSchema(memorySchema);
 export const createMemoryBodySchema = z
     .object({
-    text: memoryTextSchema,
-    userId: userIdSchema.default(""),
+    text: memoryTextSchema.describe("The note to remember, up to 10 KiB."),
+    userId: userIdSchema
+        .default("")
+        .describe("The end user this memory belongs to. Only turns that pass the same `userId` see it. Leave it out or send an empty string for a general memory that every turn of the agent sees. It cannot change after creation."),
 })
     .strict();
 export const updateMemoryBodySchema = z
     .object({
-    text: memoryTextSchema,
+    text: memoryTextSchema.describe("Replacement text for the memory, up to 10 KiB."),
 })
     .strict();

package/dist/contracts/entities/merchant.js

@@ -48,17 +48,30 @@ export const merchantConnectionResponseSchema = z
     .strip();
 export const createMerchantConnectionBodySchema = z
     .object({
-    provider: merchantProviderSchema,
-    environment: merchantEnvironmentSchema,
-    credential: z.string().min(1),
-    guard: merchantGuardSchema.optional(),
+    provider: merchantProviderSchema.describe("Your billing provider: `polar` or `dodo`."),
+    environment: merchantEnvironmentSchema.describe("The provider environment to send usage to: `sandbox` or `live`."),
+    credential: z
+        .string()
+        .min(1)
+        .describe("A credential for your provider account: a Polar Organization Access Token, or a Dodo API key in the mode that matches `environment`. It is never returned."),
+    guard: merchantGuardSchema
+        .optional()
+        .describe("Check each end user's plan or balance with your provider before every turn starts. Off when left out."),
 })
     .strict();
 export const updateMerchantConnectionBodySchema = z
     .object({
-    credential: z.string().min(1).optional(),
-    status: merchantConnectionStatusSchema.optional(),
-    guard: merchantGuardSchema.optional(),
+    credential: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A replacement credential. It must belong to the same merchant account as the current one."),
+    status: merchantConnectionStatusSchema
+        .optional()
+        .describe("`active` sends usage events to your provider. While `disconnected`, deliveries fail and can be retried after you set it back to `active`, and turns are refused if the guard is on."),
+    guard: merchantGuardSchema
+        .optional()
+        .describe("The complete guard configuration, replacing the current one."),
 })
     .strict();
 export const merchantCustomerBindingSchema = z
@@ -76,7 +89,12 @@ export const merchantBindingsResponseSchema = z
 })
     .strip();
 export const upsertMerchantBindingBodySchema = z
-    .object({ customerId: z.string().min(1) })
+    .object({
+    customerId: z
+        .string()
+        .min(1)
+        .describe("The ID of the customer in your billing provider."),
+})
     .strict();
 export const merchantBindingResponseSchema = z
     .object({ binding: merchantCustomerBindingSchema })
@@ -182,7 +200,8 @@ export const merchantUsageSummaryQuerySchema = z
         .int()
         .min(1)
         .max(MAX_MERCHANT_USAGE_SUMMARY_DAYS)
-        .default(DEFAULT_MERCHANT_USAGE_SUMMARY_DAYS),
+        .default(DEFAULT_MERCHANT_USAGE_SUMMARY_DAYS)
+        .describe(`UTC days in the \`daily\` series, ending today, from 1 to ${MAX_MERCHANT_USAGE_SUMMARY_DAYS}.`),
 })
     .strict();
 export const merchantUsageSummaryResponseSchema = z

package/dist/contracts/entities/prompts.d.ts

@@ -40,10 +40,10 @@ export declare const promptsResponseSchema: z.ZodObject<{
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const promptsListQuerySchema: z.ZodObject<{
-    cursor: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userId: z.ZodOptional<z.ZodString>;
     agentId: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
 export declare const createPromptBodySchema: z.ZodObject<{
     name: z.ZodString;

package/dist/contracts/entities/prompts.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { cursorSchema, paginatedResponseSchema } from "../api.js";
 import { agentIdSchema, promptIdSchema, tenantIdSchema } from "../ids.js";
-import { DEFAULT_PROMPTS_LIST_LIMIT, MAX_PROMPT_NAME_LENGTH, MAX_PROMPT_TEMPLATE_BYTES, MAX_PROMPT_VARIABLES, MAX_PROMPTS_LIST_LIMIT, } from "../limitations.js";
+import { DEFAULT_RESOURCES_LIST_LIMIT, MAX_PROMPT_NAME_LENGTH, MAX_PROMPT_TEMPLATE_BYTES, MAX_PROMPT_VARIABLES, MAX_RESOURCES_LIST_LIMIT, } from "../limitations.js";
 import { atLeastOneFieldMessage, hasObjectKeys } from "../utils.js";
 import { metadataSchema, userIdSchema } from "./attribution.js";
 export const promptVariableTokenPattern = /{{([\s\S]*?)}}/g;
@@ -66,34 +66,61 @@ export const promptResponseSchema = z
 })
     .strip();
 export const promptsResponseSchema = paginatedResponseSchema(promptResponseSchema);
+const promptFieldDescriptions = {
+    name: "Display name, 1 to 80 characters.",
+    template: "Message template, up to 10,240 characters. Mark each variable as `{{name}}`; names match `[A-Za-z_][A-Za-z0-9_]*`, and a template can use up to 10 of them.",
+    agentId: "ID of an agent in your tenant to link the prompt to, or `null` for no link. Deleting the agent also deletes its linked prompts.",
+    metadata: "Your own key-value data, returned unchanged.",
+};
 export const promptsListQuerySchema = z
     .object({
-    cursor: cursorSchema.optional(),
+    userId: userIdSchema
+        .optional()
+        .describe("Return only prompts for this end user. Send an empty string for tenant-level prompts, or leave it out for all prompts."),
+    agentId: agentIdSchema
+        .optional()
+        .describe("Return only prompts linked to this agent."),
+    cursor: cursorSchema
+        .optional()
+        .describe("`nextCursor` from the previous page."),
     limit: z.coerce
         .number()
         .int()
         .min(1)
-        .max(MAX_PROMPTS_LIST_LIMIT)
-        .default(DEFAULT_PROMPTS_LIST_LIMIT),
-    userId: userIdSchema.optional(),
-    agentId: agentIdSchema.optional(),
+        .max(MAX_RESOURCES_LIST_LIMIT)
+        .default(DEFAULT_RESOURCES_LIST_LIMIT)
+        .describe("Maximum number of prompts to return."),
 })
     .strict();
 export const createPromptBodySchema = z
     .object({
-    name: promptNameSchema,
-    template: promptTemplateSchema,
-    agentId: agentIdSchema.nullable().optional(),
-    userId: userIdSchema.default(""),
-    metadata: metadataSchema.default({}),
+    name: promptNameSchema.describe(promptFieldDescriptions.name),
+    template: promptTemplateSchema.describe(promptFieldDescriptions.template),
+    agentId: agentIdSchema
+        .nullable()
+        .optional()
+        .describe(promptFieldDescriptions.agentId),
+    userId: userIdSchema
+        .default("")
+        .describe("Your end user's ID, used for attribution. An empty string means a tenant-level prompt. It cannot change after creation."),
+    metadata: metadataSchema
+        .default({})
+        .describe(promptFieldDescriptions.metadata),
 })
     .strict();
 export const updatePromptBodySchema = z
     .object({
-    agentId: agentIdSchema.nullable().optional(),
-    name: promptNameSchema.optional(),
-    template: promptTemplateSchema.optional(),
-    metadata: metadataSchema.optional(),
+    agentId: agentIdSchema
+        .nullable()
+        .optional()
+        .describe(promptFieldDescriptions.agentId),
+    name: promptNameSchema.optional().describe(promptFieldDescriptions.name),
+    template: promptTemplateSchema
+        .optional()
+        .describe(promptFieldDescriptions.template),
+    metadata: metadataSchema
+        .optional()
+        .describe(`${promptFieldDescriptions.metadata} Replaces the current value.`),
 })
     .strict()
     .refine(hasObjectKeys, {

package/dist/contracts/entities/providers.js

@@ -52,7 +52,8 @@ export const providerModelsResponseSchema = z
     })
         .strip()),
 })
-    .strip();
+    .strip()
+    .meta({ id: "ProviderModelList" });
 /**
  * `POST /v1/providers` — name, type, optional base URL, and the API key
  * (plaintext, never stored — goes to Vault). `custom` providers require a
@@ -61,10 +62,17 @@ export const providerModelsResponseSchema = z
  */
 export const createProviderBodySchema = z
     .object({
-    name: providerNameSchema,
-    providerType: providerTypeSchema,
-    baseUrl: providerBaseUrlSchema.nullable().default(null),
-    apiKey: z.string().trim().min(1),
+    name: providerNameSchema.describe("Display name, unique within your tenant."),
+    providerType: providerTypeSchema.describe("The model vendor. Cannot be changed later."),
+    baseUrl: providerBaseUrlSchema
+        .nullable()
+        .default(null)
+        .describe("Endpoint override. Required for `custom`, not accepted for `vercel_ai_gateway`, and optional otherwise. Cannot be changed later."),
+    apiKey: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("The vendor API key. It is stored encrypted, never returned, and cannot be changed later."),
 })
     .strict()
     .refine((body) => body.providerType !== "custom" ||
@@ -79,7 +87,7 @@ export const createProviderBodySchema = z
 /** `PATCH /v1/providers/{id}` — only the display name is mutable. */
 export const updateProviderBodySchema = z
     .object({
-    name: providerNameSchema,
+    name: providerNameSchema.describe("New display name, unique within your tenant."),
 })
     .strict();
 export const thinkingLevelsResponseSchema = z