Skip to main content

talonic_save_schema

Save a schema definition to the workspace for reuse. Returns a schema_id that can be passed to talonic_extract.

`talonic_save_schema` persists an extraction template so it can be referenced by ID in future talonic_extract calls. This is useful when the same schema will be applied to many documents — for example, a standard invoice schema used across all vendor invoices, or a contract schema applied to every new agreement.

The recommended workflow is to iterate on the schema inline first (passing it directly to talonic_extract), verify the extraction results with the user, and only call talonic_save_schema once the schema design is confirmed. This avoids cluttering the workspace with draft schemas that never get used.

The response returns both a UUID (id) and a short ID (short_id in SCH-XXXXXXXX format). Either can be used as schema_id in subsequent talonic_extract calls. The version field starts at 1 and increments if the schema is updated through the Talonic dashboard.

ParameterTypeDescription
name *stringHuman-readable schema name.
definition *objectSchema definition. Full JSON Schema `{type: "object", properties: {...}}` recommended.
descriptionstringWhat this schema extracts and when to use it.
Prefer full JSON Schema format with type: "object" and properties. The flat key-type map format is not fully supported server-side yet.

Example

Tool input
{
  "name": "Standard Invoice",
  "description": "Extracts vendor, line items, totals, and payment terms from invoices.",
  "definition": {
    "type": "object",
    "properties": {
      "vendor_name": { "type": "string" },
      "invoice_number": { "type": "string" },
      "total_amount": { "type": "number" },
      "due_date": { "type": "string", "format": "date" },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "amount": { "type": "number" }
          }
        }
      }
    },
    "required": ["vendor_name", "total_amount"]
  }
}
Tool response
{
  "id": "sch_7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "short_id": "SCH-A1B2C3D4",
  "name": "Standard Invoice",
  "description": "Extracts vendor, line items, totals, and payment terms from invoices.",
  "version": 1,
  "field_count": 5
}

Example: iterate inline then save

Step 1: test the schema inline with talonic_extract
// Agent extracts with inline schema first:
{
  "file_url": "https://example.com/sample-po.pdf",
  "schema": {
    "type": "object",
    "properties": {
      "po_number": { "type": "string" },
      "vendor": { "type": "string" },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "integer" },
            "unit_price": { "type": "number" }
          }
        }
      },
      "total": { "type": "number" },
      "delivery_date": { "type": "string", "format": "date" }
    },
    "required": ["po_number", "vendor", "total"]
  }
}
// → User reviews results, confirms the schema looks right
Step 2: save the confirmed schema for reuse
// Agent calls talonic_save_schema:
{
  "name": "Purchase Order",
  "description": "Extracts PO number, vendor, line items, total, and delivery date.",
  "definition": {
    "type": "object",
    "properties": {
      "po_number": { "type": "string" },
      "vendor": { "type": "string" },
      "items": { "type": "array" },
      "total": { "type": "number" },
      "delivery_date": { "type": "string", "format": "date" }
    },
    "required": ["po_number", "vendor", "total"]
  }
}

// Response:
{
  "id": "sch_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "short_id": "SCH-D4E5F6A7",
  "name": "Purchase Order",
  "version": 1,
  "field_count": 5
}
// → Future extractions use: { "schema_id": "SCH-D4E5F6A7" }

The description field is optional but strongly recommended. A clear description helps agents (and users) understand when to use a particular schema. Agents can read schema descriptions from talonic_list_schemas to auto-select the right schema based on the document type. For example, if the user drops a purchase order, the agent can scan saved schema descriptions for keywords like 'purchase order' or 'PO' and suggest the matching schema automatically.

Schema naming conventions matter for discoverability. Use descriptive, consistent names like 'Standard Invoice', 'Certificate of Insurance', or 'Employment Contract' rather than abbreviations or internal codes. These names appear in talonic_list_schemas results and the talonic://schemas resource, where users and agents browse them to find the right template. A well-named schema library reduces friction across the entire team.

Frequently asked questions

How do I save a schema via MCP?+
Call talonic_save_schema with a name and JSON Schema definition. It returns a schema_id for reuse in talonic_extract calls.
When should I save a schema vs use an inline schema?+
Save a schema when you will reuse it across many documents (e.g., a standard invoice template). Use inline schemas for one-off extractions or when iterating on schema design with the user.
Can I update a saved schema?+
Schema updates are managed through the Talonic dashboard. The version field in the response tracks changes. Via MCP, you can save a new schema with a different name if the design changes significantly.
What is the recommended workflow for schema design?+
Iterate inline first: pass the schema directly to talonic_extract, review results with the user, adjust fields as needed. Once the user confirms the schema produces good results, call talonic_save_schema to persist it. This prevents cluttering the workspace with draft schemas that never get used.
Should I include a description when saving a schema?+
Yes. The description helps agents auto-select the right schema based on document type, and helps team members understand what each schema extracts. Use clear language like 'Extracts vendor, line items, totals, and payment terms from invoices' so both humans and AI agents can match schemas to documents.

Related

talonic_list_schemas
talonic_extract