Skip to main content
Glama

scrapewise_update_matcher_job

Destructive
        Saves the group's product-matching setup (the portal canvas's save): main list (masterData.jobId),
        ID column (masterData.targetField), match lines (masterData.matchers; per source
        masterData.matchersByScope keyed by run id) and the runs to match (scope).

        What a save does — read before calling:
          - Classic group: draft=false REPLACES the previous match result (matched rows and jobs deleted) and runs;
            draft=true only stores the setup.
          - Group on the newer matching engine: the SAME job is updated in place. The owner (Full key or
            portal) saves (draft=true) and runs (draft=false) it, like a Scrapewise admin key: text lines,
            picture lines (masterData.matchers with imageField / imageScopeField), the ID column and every
            per-source setting are the owner's. The old picture switch
            (imageMatchingEnabled) is stored off on this engine.
          - Photo checks: a group compares photos when it has a picture line. Off: remove the picture line, or
            imageMatchingEnabled=false plus clearFields ["imageMatchingEnabled"].
          - version: copy it unchanged, as a string, from your last scrapewise_get_matcher_job or save answer
            ("" when it was "", never null). Required for a newer-engine group's owner; checked whenever
            sent. 409 VERSION_CHANGED carries currentVersion: read again, redo your change, send that. Without
            version a classic save overwrites (last writer wins).
          - draft, requireIdle, afterGroupId, imageConfigManaged are request controls, never stored.
          - On a newer-engine group the main list changes through Scrapewise support only (400). The ID column
            (masterData.targetField, targetFieldByScope, targetScopeFieldByScope) is the owner's: a change is
            saved with the ID_COLUMN_CHANGED warning. Nothing is deleted then: the current results, review
            pairs and saved review decisions stay until the next run writes rows under the new ID column
            (decisions saved under the old column do not carry over to those rows).
          - warnings [{field, code, message}]: ID_COLUMN_CHANGED (above), IGNORED_BY_ENGINE (identityCol
            changed on a newer-engine group: saved, ignored by the engine), NO_RUN_ON_DRAFT (afterGroupId on
            such a draft: no effect).
            identityCol "" = keep the stored one.
          - Newer engine: a per-source column (scopeField) goes in masterData.matchersByScope[<runId>]; a
            renamed flat line no per-source list carries is 400 FLAT_SCOPE_FIELD_LOST.
          - Refused while free or AI-agent matching runs on the group.
          - Per-shop picture settings (imageMatchingEnabledByScope, imageLeft/RightColByScope) are kept for
            AI-agent keys; imageConfigManaged=false clears them.
          - schedule: PUT never clears a schedule (absent or null keeps it); change or clear it via
            scrapewise_update_matcher_schedule.
          - masterData.reviewMaxByScope / reviewFloorByScope = per-feed review band (score > max -> MATCH,
            < floor -> NO), keyed by scope job id, both or neither.
          - A held run keeps the previous matches; scrapewise_get_matcher_history says why.

        Args:
          - id (string, path, required): the group's id.
          - idempotency_key (string, query): REQUIRED for AI-agent keys. New value per save; the same
            value only to retry it (the retry gets the first answer; nothing runs twice). After a 4xx
            nothing was saved: retry with the SAME key.
          - body (MatcherJobDTO, required): masterData + scope (FINISHED run ids, one per source, from
            scrapewise_get_matcher_scope_jobs or scrapewise_get_scraper_load_history) + draft + version.
            requireIdle=true refuses while this group's matching or any of its scrapers runs;
            afterGroupId=<group id> refuses while that group is matching (not on a newer-engine draft). Both
            are checked at save time. replaceRunning=true (Run only): stop the running run, start again (work
            lost). Run only: autoMatches KEEP_ADD|REPLACE, manualMatches KEEP|FRESH (undo FRESH:
            scrapewise_update_matcher_fresh_undo).
          - customerRef (string, query, optional): admin key in Take Over only: that customer's
            customerUniqueRef.

        Returns:
          The saved MatcherJobDTO (status INITIAL/QUEUED when a run starts, PENDING for a draft; a newer-engine
          job keeps its status) with the new version for the next save.

        Examples:
          - Use when: "match group {id} on EAN against two sources if nothing runs" -> scope, matchers,
            requireIdle=true, a fresh idempotency_key.
          - Use when: "save this setup without running it" -> draft=true.
          - Don't use when: only reading the setup -> scrapewise_get_matcher_job.

        Error Handling:
          Nothing was changed in each.
          - 400 IDEMPOTENCY_KEY_REQUIRED (AI-agent key without idempotency_key); 400 VERSION_REQUIRED (owner of
            a newer-engine group sent no version); 400 FIELD_INVALID (bad identityCol, autoMatches or
            manualMatches).
          - 400 (CustomerError): a scope run of another group, a bad line, column or afterGroupId; a main-list
            change on a newer-engine group ("Contact support@scrapewise.ai with group id <id>.").
          - 402: the wallet does not cover the run (run servers); the body carries the figures.
          - 404: unknown or another customer's group.
          - 409 VERSION_CHANGED: changed since your read; read again, redo, send currentVersion.
          - 409 OWN_MATCH_RUNNING / SCRAPER_RUN_IN_PROGRESS / OTHER_GROUP_MATCHING: wait, save again with the
            SAME idempotency_key.
          - 409 IDEMPOTENCY_IN_FLIGHT: the same save is still running; retry shortly.
          - 409 ARGS_HASH_MISMATCH: the key was used for a different request; use a new key.
          - 409 TAKE_OVER_ACTIVE: end Take Over or send customerRef.
          - 429 OWNER_EDIT_RATE_LIMIT: over 10 owner saves of this group in 10 minutes; wait Retry-After
            seconds, retry with the SAME idempotency_key.
          - 401 Unauthorized; 403 for a read-only key.
          - 5xx: the save may have landed; read again before retrying.

[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": {
      "id": "<id>",
      "idempotency_key": "<idempotency_key>",
      "body": "<body>"
    },
    "name": "scrapewise_update_matcher_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesthe group's id.
bodyYesmasterData + scope (FINISHED run ids, one per source, from scrapewise_get_matcher_scope_jobs or scrapewise_get_scraper_load_history) + draft + version. requireIdle=true refuses while this group's matching or any of its scrapers runs; afterGroupId=<group id> refuses while that group is matching (not on a newer-engine draft). Both are checked at save time.
customerRefNoAdmin keys in Take Over only: the customerUniqueRef of the customer the admin works for. Required then; leave it out otherwise.
idempotency_keyYesRequired for AI-agent keys: a new value per new save, the same value only to retry it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / body / description
      Added value: +"masterData + scope (FINISHED run ids, one per source, from scrapewise_get_matcher_scope_jobs or scrapewise_get_scraper_load_history) + draft + version. requireIdle=true refuses while this group's matching or any of its scrapers runs; afterGroupId=<group id> refuses while that group is matching (not on a newer-engine draft). Both are checked at save time."
    • addedInput schema / properties / id / description
      Added value: +"the group's id."
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

Far exceeds the annotations: it discloses that a classic draft=false save deletes matched rows and jobs, that newer-engine jobs are updated in place via support only for the main list, that version is checked and 409 VERSION_CHANGED must be redone, the 10-saves-per-10-minutes owner rate limit, and that saves are refused while matching runs. This is consistent with destructiveHint=true and idempotentHint=false rather than contradicting them.

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

Conciseness3/5

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

Well structured with front-loaded purpose, bulleted semantics, Args/Returns/Errors/Examples sections, but it runs roughly 800 words and the Args section duplicates text already present in the schema (body, idempotency_key, customerRef descriptions). The requireIdle/afterGroupId refusal rule is stated twice, and the content is dense enough to dilute the one paragraph that matters most before the first call.

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 destructive, multi-mode, nested-schema tool with no output schema, it covers what is returned (saved MatcherJobDTO with new version and status INITIAL/QUEUED vs PENDING), the warning codes on the response, and per-status error handling including idempotency and version conflicts. Nothing an agent needs to call it safely is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real operational meaning the schema lacks: version must be copied unchanged as a string and re-read on 409, idempotency_key is new-per-save but reused for retries after 4xx/409, requireIdle/afterGroupId are checked at save time and never stored, and scope must be FINISHED run ids from sibling tools. Points are lost because the Args section largely restates the schema's own body description verbatim.

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?

Opens with a specific verb and resource: "Saves the group's product-matching setup (the portal canvas's save)", then enumerates exactly what is persisted (main list, ID column, match lines, runs). An agent can distinguish this from scrapewise_get_matcher_job, scrapewise_update_matcher_schedule and scrapewise_update_matcher_fresh_undo 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 when-to-use examples ("match group {id} on EAN against two sources if nothing runs", "save this setup without running it" -> draft=true) and an explicit when-not ("Don't use when: only reading the setup -> scrapewise_get_matcher_job"). It also names the correct channel for adjacent concerns (schedule -> scrapewise_update_matcher_schedule, undo -> scrapewise_update_matcher_fresh_undo).

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.