Skip to main content
Glama
Gi0tto

sluicer

by Gi0tto
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Learn an extractor

compile_extractor
Read-onlyIdempotent

Learn a reusable extractor from a few pages of one template, then replay it on similar pages to extract structured fields and rows automatically.

Instructions

Learn an extractor from pages of one template, to replay later for free.

pages: http(s) URLs, or the HTML itself, of pages built from one template -- two or three pages of one listing, or of one kind of product page. listing: learn the rows the pages repeat; by default only where they declare nothing about a thing. want: example values one row of the listing holds, by the name each column is to have, as {"price": "41.90", "title": "Brake pad set"}: they choose the listing and the columns, and only those columns are kept. A value that no row holds is an error that names it. select: instead of want, each field by a CSS or XPath selector you write, as {"title": "h1", "price": "span.price::text"}; pages may then be empty. Where the fields are is not learnt; what the pages show of them is, and a run fails when a selector finds nothing. Try a selector first with select_values. rows: with select, the selector of a listing's rows ("li.product"), each field then read inside each row.

Returns {"ok", "extractor"}: keep that object and hand it to run_extractor. It holds what the pages declared, the listing's place, its fields, and what every field looked like. An extractor heavier than one answer may be, 75,000 bytes, is too_large: sluicer compile writes it to a file.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
rowsNowith select, the selector of a listing's rows ("li.product"), each field then read inside each row.
wantNoexample values one row of the listing holds, by the name each column is to have, as {"price": "41.90", "title": "Brake pad set"}: they choose the listing and the columns, and only those columns are kept. A value that no row holds is an error that names it.
pagesYeshttp(s) URLs, or the HTML itself, of pages built from one template -- two or three pages of one listing, or of one kind of product page.
selectNoinstead of want, each field by a CSS or XPath selector you write, as {"title": "h1", "price": "span.price::text"}; pages may then be empty. Where the fields are is not learnt; what the pages show of them is, and a run fails when a selector finds nothing. Try a selector first with select_values.
listingNolearn the rows the pages repeat; by default only where they declare nothing about a thing.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYes
errorNo
extractorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.9.0
    • addedInput schema / properties / rows
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "with select, the selector of a listing's rows (\"li.product\"), each field then read inside each row.",
+  "title": "Rows"
+}
    • addedInput schema / properties / select
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "instead of want, each field by a CSS or XPath selector you write, as {\"title\": \"h1\", \"price\": \"span.price::text\"}; pages may then be empty. Where the fields are is not learnt; what the pages show of them is, and a run fails when a selector finds nothing. Try a selector first with select_values.",
+  "title": "Select"
+}
    • changedOutput schema / $defs / ErrorDetail / description
      Previous value: -"Why a tool could not answer.\n\n``retryable`` is true only for ``fetch_failed``, and on a crawled page for\n``rate_limited``: the same call may work later. The others need something\nto change first -- an install, an input, or the caller's mind about a site\nthat said no."New value: +"Why a tool could not answer.\n\n``retryable`` is true only for ``fetch_failed``, and on a crawled page for\n``rate_limited``: the same call may work later. Not every ``fetch_failed``\nis: a redirect loop, or an encoding this install cannot read, would be\nmet again. The others need something to change first -- an install, an\ninput, or the caller's mind about a site that said no."
    • changedOutput schema / $defs / ErrorDetail / properties / code / enum
      Previous value: -[
-  "missing_extra",
-  "refused_by_robots",
-  "refused_address",
-  "fetch_failed",
-  "too_large",
-  "bad_input",
-  "tdm_reserved"
-]New value: +[
+  "missing_extra",
+  "refused_by_robots",
+  "refused_by_site",
+  "payment_required",
+  "refused_address",
+  "fetch_failed",
+  "too_large",
+  "bad_input",
+  "tdm_reserved"
+]
  2. Changed3 schema fields changedv0.7.0
    • addedInput schema / properties / listing / description
      Added value: +"learn the rows the pages repeat; by default only where they declare nothing about a thing."
    • addedInput schema / properties / pages / description
      Added value: +"http(s) URLs, or the HTML itself, of pages built from one template -- two or three pages of one listing, or of one kind of product page."
    • addedInput schema / properties / want / description
      Added value: +"example values one row of the listing holds, by the name each column is to have, as {\"price\": \"41.90\", \"title\": \"Brake pad set\"}: they choose the listing and the columns, and only those columns are kept. A value that no row holds is an error that names it."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explains that a value no row holds is an error that names it, that a run fails when a selector finds nothing, that pages may be empty with select, and that an extractor heavier than 75,000 bytes is too_large and sluicer compile writes it to a file. It also discloses what the returned extractor contains. This goes beyond the annotations without 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.

Conciseness4/5

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

The description is dense but well-structured, with each parameter name bolded and followed by a concise explanation. It front-loads the core purpose in the first sentence and then systematically covers each parameter. Some sentences are long and packed with multiple clauses, which slightly reduces scannability, but every sentence earns its place and there is no fluff.

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?

The description is complete for a tool with 5 parameters, 100% schema coverage, and an output schema. It explains the input requirements (two or three pages of one template), the two modes (want vs select), the error conditions, the output format, and the next step (hand to run_extractor). The output schema exists, so the description needn't detail return values, but it still summarizes what the extractor holds. The only minor gap is not explaining what 'declared' means in the listing context, but the schema and examples make it understandable.

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 100%, so the schema already documents all five parameters. The description adds meaning by explaining the relationship between parameters: want and select are alternatives ('instead of want'), rows is used 'with select', and listing's default behavior is clarified ('by default only where they declare nothing about a thing'). It also gives concrete examples of want and select values. This is more than the schema alone provides, though the schema already carries the parameter names and basic descriptions.

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 description opens with a specific verb and resource: 'Learn an extractor from pages of one template, to replay later for free.' It clearly distinguishes this from siblings like run_extractor (replay) and select_values (try a selector first). The title 'Learn an extractor' is expanded with concrete detail about what learning means and what the output is for.

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?

The description gives explicit when-to-use guidance: use it to learn an extractor from pages of one template, and explicitly says 'Try a selector first with select_values' when using select. It also names run_extractor as the tool to hand the returned extractor to. The distinction between want (example values) and select (CSS/XPath selectors) is clearly explained, and the 'listing' parameter's default behavior is stated.

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

Deploy Server

Other Tools