Skip to main content
Glama
Sign In

Scrapewise

by ai.scrapewise
OverviewDiscussionsAdmin

scrapewise_preview_scraper_from_url

Read-onlyIdempotent
        Take a target URL, run every applicable detection strategy in parallel
        (SINGLE_PRODUCT, MULTIPLE_PRODUCTS, APPLICATION_LD_JSON, plus the Amazon and
        Google specialisations), and return the candidate scraper configurations that
        successfully produced data along with their sample rows. Each candidate is
        feature-gated against the customer's plan — only configs the plan can actually
        run are returned. This is a preview / discovery endpoint: nothing persists.
        Pick a candidate from the response, then call scrapewise_create_scraper to
        save it.

        INPUT CONTRACT — paste the link, never a keyword or an ID:
          `url` is the full web address of the page you want, exactly as it appears in a
          browser address bar. Every value a dedicated endpoint needs (search term, ASIN,
          seller id, place id, product id, country, language, page) is read OUT of that
          address — never asked for separately. The one exception is plain Google Search,
          which also accepts typed words.

          The address decides the endpoint:
            - `google.<tld>/search?q=…`                  → Google Search
            - `google.<tld>/search?q=…&udm=28` (or `tbm=shop`) → Google Shopping search
            - `google.<tld>/search?q=…&tbm=nws`, `news.google.com/search?q=…` → Google News
            - `google.<tld>/shopping/product/<id>?q=…`   → Google Shopping product
              (the search phrase is required: the catalog lookup is refused without it)
            - `google.<tld>/maps/search|place|reviews…`  → Google Maps
            - `google.<tld>/travel/flights|search…`      → Google Flights / Hotels
            - `amazon.<tld>/s?k=…`, `/gp/offer-listing/<asin>`, `/deals`,
              `/gp/bestsellers/<category>`, `/sp?seller=…` → the matching Amazon endpoint
            - `walmart.com/search?q=…`, `walmart.com/ip/<name>/<item>` → Walmart
            - `play.google.com/store/search|apps/details` → Google Play
            - `youtube.com/results?search_query=…`       → YouTube
            - `trends.google.com/trends/explore?q=…`     → Google Trends
          Any OTHER address is not an error: it runs the normal detection flow above.

        Args:
          - body (SimpleModeWithUrlDTO, required): the target page descriptor.
              - id (string, optional): existing scraper id if previewing changes
              - name (string, required): display name for the future scraper
              - groupId (string, required): owning group's MongoDB ObjectId
              - url (string, required): the page address to analyse (see INPUT CONTRACT)
              - endpointTag (string, optional): the answer to a closed choice question when
                one address fits several variants of the same family. It never overrides the
                address: the address's own host must belong to that endpoint, and it can
                never turn typed words into a dedicated call.
              - itemsConfig (list, optional): pre-existing field selectors to bias detection
          - tryWithHiddenData (boolean, query param, optional, default false): enable
            a more aggressive JSON-LD pass that reads scripts hidden by the renderer.
          - useCache (boolean, query param, optional, default false): reuse a recent
            fetch instead of hitting the network. Faster but may serve stale HTML.

        Returns:
          `Set<ScraperSampleDataDTO>` — one entry per detection strategy that produced
          data. Each entry carries the candidate `scraperDTO` (full ScraperDTO ready
          to persist via scrapewise_create_scraper) plus a `sampleData` map of the
          first scraped rows and `executionTimeSec` for that detection pass. Empty
          set means no strategy succeeded for this URL on this plan.

        Examples:
          - Use when: "find a scraper config for https://example.com/widget" → returns
            every detection strategy that worked, customer picks one
          - Use when: building a new scraper interactively in chat — preview, evaluate
            candidates, then create
          - Don't use when: you already have a ScraperDTO ready to persist → call
            scrapewise_create_scraper directly
          - Don't use when: the target needs custom request shape (cookies, headers) →
            use scrapewise_preview_scraper_from_curl instead

        Error Handling:
          - 200 with empty Set if no strategy produced data on the customer's plan
            (not an error — the URL is just unsupported by available detectors).
          - 400 INPUT_MUST_BE_URL if `endpointTag` names a dedicated endpoint but `url` is
            typed words rather than an address. Only Google Search accepts typed words.
          - 400 AMBIGUOUS_URL if the address fits several variants of one family and no
            choice was sent. The message lists the closed option set; pick one and retry.
          - An address that matches NO endpoint is never an error — it takes the normal
            detection flow.
          - 401 Unauthorized if no Firebase JWT or API key on the request.
          - 500 INTERNAL with `correlationId` if a detector or downstream proxy
            crashes mid-pass.

[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_preview_scraper_from_url"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes
useCacheNo
forceTopTierNo
tryWithHiddenDataNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (which already declare read-only, idempotent, non-destructive), the description discloses that candidates are feature-gated against the customer's plan, that only runnable configs are returned, that nothing persists, that an empty set is a non-error outcome, that useCache may serve stale HTML, and it enumerates status codes (400 INPUT_MUST_BE_URL, 400 AMBIGUOUS_URL, 401, 500 with correlationId). That is substantial context an agent could not obtain from the annotations or schema.

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?

The purpose is front-loaded in the first sentence and the text is cleanly sectioned into INPUT CONTRACT, Args, Returns, Examples, and Error Handling. It is long, though: the full URL-pattern routing table and the repeated restatement of error conditions occupy a lot of space for information the agent may not need before its 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 tool with a dynamic response and no output schema, the description fully specifies the return contract (Set of entries with scraperDTO, sampleData, executionTimeSec) and the empty-set semantics, and the runtime hint covers defensive parsing. Combined with the documented error paths and the create/preview workflow, an agent has everything needed to call and interpret it.

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 description coverage is 0%, so the description must carry the load, and it documents all six nested body fields plus useCache and tryWithHiddenData with real semantics (e.g. endpointTag 'never overrides the address', itemsConfig biases detection). However, the top-level `forceTopTier` parameter appears in the schema and is never mentioned anywhere, leaving one parameter with zero meaning attached.

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 names the specific verb and resource: run every applicable detection strategy on a target URL and return candidate scraper configurations with sample rows. It also explicitly distinguishes the tool from its siblings by stating 'nothing persists' and routing persistence to scrapewise_create_scraper.

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?

Provides explicit 'Use when' cases (interactive scraper building, unknown URL) and explicit 'Don't use when' cases that name the alternatives by name: scrapewise_create_scraper for an already-built ScraperDTO and scrapewise_preview_scraper_from_curl for custom cookies/headers. The INPUT CONTRACT further states when the URL form must be used versus typed words.

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

All Scrapewise toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources