Save Talonic Schema
talonic_save_schemaSave a custom schema to your Talonic workspace for reuse across multiple document extractions, ensuring consistent data extraction without redefining fields each time.
Instructions
Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id.
USE WHEN:
The user asks to save a schema, store a template, or reuse the schema across docs.
You have iterated on a schema with the user and they confirmed it should be saved.
The user wants to standardise extraction across many documents of the same type.
DO NOT USE WHEN:
The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline).
The user has not confirmed the schema design (avoid creating clutter in their workspace).
DEFINITION FORMATS:
JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } }
Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema.
TIP: After saving, call talonic_extract with schema_id set to the returned id (UUID or SCH- short id) for consistent results.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the schema, e.g. 'Standard Invoice'. | |
| definition | Yes | Schema definition. Most reliable: full JSON Schema {type:'object', properties:{...}}. Also accepted: a flat key-type map {field_name:'string', amount:'number'} which the API normalises. | |
| description | No | Optional description of what this schema extracts and when to use it. |
Implementation Reference
- src/tools/save-schema.ts:39-53 (handler)The handler function `handleSaveSchema` that executes the tool logic. It calls `talonic.schemas.create` with the provided name, definition, and optional description, returning the result as JSON.
export async function handleSaveSchema( talonic: Talonic, args: { name: string; definition: Record<string, unknown>; description?: string }, ): Promise<ToolResult> { try { const result = await talonic.schemas.create({ name: args.name, definition: args.definition, ...(args.description !== undefined ? { description: args.description } : {}), }) return jsonOk(result) } catch (err) { return toolError(err) } } - src/tools/save-schema.ts:55-65 (registration)The function `registerSaveSchema` that registers the tool with name "talonic_save_schema" on the MCP server, including its input schema (zod) and description.
export function registerSaveSchema(server: McpServer, talonic: Talonic): void { server.registerTool( "talonic_save_schema", { title: "Save Talonic Schema", description: DESCRIPTION, inputSchema, }, async (args) => handleSaveSchema(talonic, args), ) } - src/tools/save-schema.ts:26-37 (schema)Input schema definition using zod: `name` (string, required), `definition` (record<string, unknown>, required), and `description` (optional string).
const inputSchema = { name: z.string().min(1).describe("Human-readable name for the schema, e.g. 'Standard Invoice'."), definition: z .record(z.string(), z.unknown()) .describe( "Schema definition. Most reliable: full JSON Schema {type:'object', properties:{...}}. Also accepted: a flat key-type map {field_name:'string', amount:'number'} which the API normalises.", ), description: z .string() .optional() .describe("Optional description of what this schema extracts and when to use it."), } - src/tools/_shared.ts:13-16 (helper)`ToolSuccessResult` type used as the return envelope for successful handler execution.
export interface ToolSuccessResult { content: Array<{ type: "text"; text: string }> [key: string]: unknown } - src/tools/_shared.ts:24-28 (helper)`ToolErrorResult` type used as the return envelope for errors (sets isError: true).
export interface ToolErrorResult { content: Array<{ type: "text"; text: string }> isError: true [key: string]: unknown }