validate_completion_metadata
Read-onlyIdempotent
Validate required billing metadata fields and values before prompt completion to catch attribution errors and avoid paying for incorrect calls.
Instructions
Preflight billing metadata before run_prompt_completion. Validates required fields and values without making changes, so you can catch attribution errors before paying for the call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | No | Client ID for billing attribution | |
| app | No | App identifier (REQUIRED). Use your deployed app name, for example 'hourlink' or 'support-console'. | |
| env | No | Environment identifier (REQUIRED). Use your environment name, for example 'dev', 'staging', 'prod', or 'qa'. | |
| project_id | No | Project ID for granular billing | |
| feature | No | Feature name for tracking |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | Whether the tool call succeeded and returned structured data | |
| data | No | Structured success payload when ok is true | |
| error | No | Structured error payload when ok is false |
Implementation Reference
- src/tools/prompts.tools.ts:1015-1041 (handler)Registration of the 'validate_completion_metadata' MCP tool. Provides the tool description, schema reference, and handler that delegates to service.prompts.validateBillingMetadata.
// Validate completion metadata tool server.tool( "validate_completion_metadata", "Preflight billing metadata before run_prompt_completion. Validates required fields and values without making changes, so you can catch attribution errors before paying for the call.", PROMPTS_TOOL_SCHEMAS.validateCompletionMetadata, async (params) => { const result = service.prompts.validateBillingMetadata(params); return { content: [ { type: "text", text: JSON.stringify( { valid: result.valid, errors: result.errors, warnings: result.warnings, metadata: params, }, null, 2, ), }, ], }; }, ); - src/tools/prompts.tools.ts:275-287 (schema)Zod validation schema for the tool's input parameters: all fields are optional since this is a pre-flight validation check.
validateCompletionMetadata: { client_id: z .string() .optional() .describe("Client ID for billing attribution"), app: PromptAppIdentifierSchema.optional(), env: PromptEnvironmentIdentifierSchema.optional(), project_id: z .string() .optional() .describe("Project ID for granular billing"), feature: z.string().optional().describe("Feature name for tracking"), }, - Core validation logic: checks that client_id, app, and env are present (errors) and warns if project_id is missing.
validateBillingMetadata( metadata: Partial<BillingMetadata>, ): ValidateMetadataResult { const errors: string[] = []; const warnings: string[] = []; if (!metadata.client_id) { errors.push("Missing required field: client_id"); } if (!metadata.app) { errors.push("Missing required field: app"); } if (!metadata.env) { errors.push("Missing required field: env"); } if (!metadata.project_id) { warnings.push( "Missing recommended field: project_id (helps with billing attribution)", ); } return { valid: errors.length === 0, errors, warnings, }; } - src/lib/schemas.ts:70-78 (helper)Canonical BillingMetadata schema used in run_prompt_completion. The validateCompletionMetadata schema uses optional variants of the same fields.
export const BillingMetadataSchema = z.object({ client_id: z .string() .describe("Client ID for billing attribution (REQUIRED)"), app: PromptAppIdentifierSchema, env: PromptEnvironmentIdentifierSchema, project_id: z.string().optional().describe("Project ID for granular billing"), feature: z.string().optional().describe("Feature name for tracking"), }); - TypeScript interface for BillingMetadata used across the service layer.
export interface BillingMetadata { client_id: string; app: string; env: string; project_id?: string; feature?: string; prompt_slug?: string; prompt_version?: string; [key: string]: unknown; }