Skip to main content
Glama

scrapewise_create_customer_schema

        Upsert a JSON-Schema document owned by the authenticated customer. Customer
        schemas constrain LLM output for AI-driven scrapers (`AI_CONF` mode): the
        scraper feeds the schema to the LLM and the LLM is required to return data
        matching that shape. Customer schemas exist alongside the global ones but are
        only visible to their owning customer (`customerRef` is set automatically
        from the auth principal — the caller cannot forge another customer's schema).
        Upsert semantics differ by type. Non-CUSTOM: if `body.id` is set and matches an
        existing customer-owned schema, it's updated in place; otherwise a new schema is
        created. **CUSTOM is different: there is no update-in-place.** Every PUT for a
        CUSTOM schema creates a brand-new immutable version — `body.id` is ignored for
        CUSTOM (only `body.groupId` matters); `body.version` is always ignored for CUSTOM
        too (the server atomically reserves the next version number). A scraper attached to
        a CUSTOM schema's group always tracks that group's current latest version
        automatically (live-latest binding) — you never need to re-attach a scraper after
        adding a version. CUSTOM versions are immutable and cannot be deleted
        (scrapewise_delete_customer_schema throws for them); version forward here instead.

        The response always carries the persisted id (use it to attach to a scraper).

        Args:
          - body (SchemaDTO, required): the schema definition.
              - id (string, optional): existing schema id; absent = create new. Ignored
                for CUSTOM — use `groupId` instead to add a version to an existing group.
              - version (int, required by the DTO shape, but ignored for CUSTOM): schema
                version number for change tracking. For CUSTOM the server always computes
                the next version itself; send any value.
              - type (SchemaType, required): one of the SchemaType enum values
                (PRODUCT, REVIEW, ARTICLE, CUSTOM, etc.)
              - content (SchemaContent, required): the JSON-Schema document itself —
                `properties` map, `required` array, etc. For CUSTOM, validated server-side
                before anything is persisted: non-blank description, at least one field, no
                blank/duplicate/reserved-keyword field names, ≤200 fields, ≤50 KB content —
                violations return 400 with every failing field named in one message.
              - description (string, optional for other types, REQUIRED non-blank for
                CUSTOM): human-readable purpose, surfaced to the agent when a scraper
                references this schema

              - templateId / templateName (string, optional): if forked from a
                BEBO-1406 template, the template provenance
              - domainPatterns (list of strings, optional): domains this schema
                is intended for (used by the auto-suggest UI; agent can ignore)
              - groupId (string, optional, CUSTOM-only): omit to start a brand-new
                CUSTOM schema group; supply an existing group's id (from a prior response,
                or from scrapewise_list_custom_schema_groups) to add a new version to that
                group instead. Ignored for non-CUSTOM types.

        CUSTOM content: fields are `{"type":["string","null"],"description":"..."}` in
        `items.properties`; order matters. `items.required`: Tells the AI this field should
        always be filled in. Rows are kept even if it is empty. None marked ⇒ all fields asked
        for (null when missing); unknown/duplicate names ignored. The fields decide what is
        extracted: every matching item on the page, one or many. Omit `products.description`
        to use the default "Extract every item on the page that matches these fields, as a
        flat array. If only one item matches, return one. Use null for any missing fields.";
        any other text is "custom instructions", kept as written. Same content as a built-in
        schema ⇒ same result.

        Returns:
          `SchemaDTO` — the persisted schema (this specific new version, for CUSTOM) with
          its assigned `id`. Use the `id` in subsequent scraper-create calls to attach this
          schema to an AI_CONF scraper. For CUSTOM, also carries `groupId` — save it if you
          plan to add further versions to this same group later. Note the response's
          `version` is the server-assigned version for CUSTOM, not necessarily what you sent.

        Examples:
          - Use when: "create a product schema with fields title, price, sku" → build
            content + call this op
          - Use when: "update my 'reviews' schema to add author field" (non-CUSTOM) →
            fetch via scrapewise_list_customer_schema, edit content, re-PUT with the same id
          - Use when: "add a version to my existing custom schema" → call
            scrapewise_list_custom_schema_groups to find the `groupId`, then PUT with that
            `groupId` set (omit `id`) — this always creates a new version, never edits one
          - Don't use when: a global (admin-managed) schema would cover the case →
            global schemas are not exposed via the MCP surface; ask the operator to
            surface or fork one rather than duplicating it as a customer schema
          - Don't use when: you only want to read existing schemas →
            scrapewise_list_customer_schema is read-only and cheaper

        Error Handling:
          - 400 if `content` violates JSON-Schema syntax or required fields missing, or
            (CUSTOM) fails the field-level content validation described above.
          - 401 Unauthorized if no Firebase JWT or API key.
          - 500 INTERNAL with `correlationId` if persistence fails.

[runtime hint] This tool returns JSON-as-text — its response shape is dynamic (per-scraper itemsConfig, file binary, etc.) so the MCP outputSchema is omitted. Do not rely on the presence of any specific field in the response; treat the result as a string-or-object blob and parse defensively.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "body": "<body>"
    },
    "name": "scrapewise_create_customer_schema"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesthe schema definition.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / body / description
      Added value: +"the schema definition."
  2. Added

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only give readOnly=false, idempotent=false, destructive=false; the description goes far beyond them, explaining why it is not idempotent for CUSTOM (every PUT creates a new immutable version, id and version ignored, server reserves the number), that versions cannot be deleted, that scrapers live-bind to the latest group version, and that customerRef is derived from the auth principal so forgery is impossible. Concrete failure modes (400 with all failing fields named, 401 on missing JWT/API key, 500 with correlationId) are also disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Structure is excellent — front-loaded CUSTOM caveat, then Args, Returns, Examples, Error Handling — but the document is long and repeats the CUSTOM rules: "no update-in-place" appears in the preamble, again under id and version, and a third time in the examples. The paragraph on items.required/products.description explains schema authoring rather than invocation, though it is arguably needed to build a valid body.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with a deeply nested body, no output schema, and a dynamic JSON-as-text response, the description is complete: it states exactly what is returned (persisted SchemaDTO with assigned id and, for CUSTOM, groupId and server-assigned version) and how to use the id downstream in scraper creation. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema documents the shape, it carries almost no per-field meaning; the description supplies it — id is ignored for CUSTOM, version must be sent but is ignored for CUSTOM, groupId is CUSTOM-only and selects new-group vs add-version, description is required non-blank for CUSTOM, content has hard limits (≤200 fields, ≤50 KB, no duplicate/reserved names), and domainPatterns is explicitly irrelevant to the agent. This is meaning well beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a precise verb+resource+scope: "Upsert a JSON-Schema document owned by the authenticated customer." It immediately distinguishes customer schemas from global ones and from the read-only siblings (scrapewise_list_customer_schema, scrapewise_list_custom_schema_groups), so an agent can select it without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit "Use when" cases cover create, update (non-CUSTOM), and add-a-version (CUSTOM), each naming the predicate and the sibling to consult first (list_custom_schema_groups for groupId, list_customer_schema for the id). "Don't use when" bullets exclude the global-schema and read-only cases, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.