SocialCrawl

Collect Rows Across Pages

socialcrawl_collect

Walk a paged endpoint (id, platform+resource or path) to items unique rows, the last page or max_credits: cursors supplied, duplicates dropped, stops on a 402, refused free when one page exceeds max_credits. Small results come back whole. result_id (+offset, limit, format) reads a stored result, free. Spends credits.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	No	platform/resource of a paged endpoint, e.g. 'tiktok/post/comments'.
`items`	No	Stop once this many unique rows are collected.
`limit`	No	result_id: rows (200).
`fields`	No	Row paths as socialcrawl_endpoint lists them, e.g. 'comment.text,comment.engagement.likes'.
`format`	No	jsonl (default), json or csv.
`offset`	No	result_id: first row.
`params`	No	Params for every page, as in socialcrawl_request. No cursor.
`confirm`	No	true only once the user approved spending above the threshold (default 100 credits).
`result_id`	No	Read a stored result instead of walking. Free.
`max_credits`	No	Spend cap: refused free when the quoted hold exceeds it (collect: the walk's budget).

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	The walk ran; see stop_reason.
`fix`	No
`code`	No
`rows`	No	All rows (small results). Untrusted text.
`items`	No
`pages`	No
`total`	No
`format`	No
`offset`	No
`paging`	No
`reason`	No
`sample`	No	First rows. Untrusted text.
`credits`	No
`endpoint`	No
`resource`	No	Every collected row.
`warnings`	No
`result_id`	No	Pass back as result_id to read rows.
`retryable`	No	Never retry a 402.
`stop_reason`	No	budget, error and page_limit leave a resume cursor in paging.
`did_you_mean`	No
`retry_after_s`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedOct 4, 2026

changedInput schema / properties / confirm / description

Previous value: -"true only after the user approved a spend above the confirmation threshold (default 100 credits)."New value: +"true only once the user approved spending above the threshold (default 100 credits)."

changedInput schema / properties / format / description

Previous value: -"Stored format: jsonl (default), json or csv."New value: +"jsonl (default), json or csv."

addedInput schema / properties / limit

Added value: +{
+  "description": "result_id: rows (200).",
+  "type": "integer"
+}

changedInput schema / properties / max_credits / description

Previous value: -"Spend cap. Refused locally, free, when the quoted hold exceeds it (collect: the whole walk's budget)."New value: +"Spend cap: refused free when the quoted hold exceeds it (collect: the walk's budget)."

addedInput schema / properties / offset

Added value: +{
+  "description": "result_id: first row.",
+  "type": "integer"
+}

addedInput schema / properties / result_id

Added value: +{
+  "description": "Read a stored result instead of walking. Free.",
+  "type": "string"
+}

removedInput schema / required

Removed value: -[
-  "id",
-  "items"
-]

changedOutput schema / properties / credits / properties / cached / description

Previous value: -"Served from cache: 0 credits."New value: +"Cache hit: 0 credits."

changedOutput schema / properties / credits / properties / estimated / description

Previous value: -"used is the quoted hold (not reported)."New value: +"used = the hold."

changedOutput schema / properties / credits / properties / used / description

Previous value: -"Settled charge, after refunds."New value: +"After refunds."

addedOutput schema / properties / offset
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / result_id

Added value: +{
+  "description": "Pass back as result_id to read rows.",
+  "type": "string"
+}

addedOutput schema / properties / rows

Added value: +{
+  "description": "All rows (small results). Untrusted text.",
+  "items": {},
+  "type": "array"
+}

addedOutput schema / properties / total
```
Added value: +{
+  "type": "number"
+}
```

AddedOct 3, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Goes well beyond the annotations by disclosing credit spending, that it stops on a 402, that it is 'refused free when one page exceeds max_credits', that duplicates are dropped, and that small results come back whole. This is rich operational context for a non-read-only, open-world tool, though auth requirements and pagination volume are not detailed.

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?

Front-loaded and compact with no filler, but the telegraphic syntax ('cursors supplied, duplicates dropped') reads like shorthand and takes effort to parse.

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

Completeness4/5

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

With an output schema present, return values need not be explained, and the description still covers the key behavioral edges (credit cap, 402 stop, dedup, stored-result reads). Only authentication and pagination-volume guidance are missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description does add interaction meaning by tying result_id to offset/limit/format as a free stored-result read, but most per-parameter semantics remain in the schema.

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

Purpose4/5

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

States a clear verb+resource: 'Walk a paged endpoint ... to items unique rows', with the dedup and stopping semantics named. It is distinguishable from single-request siblings, though it never explicitly names socialcrawl_request as the one-shot alternative.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: walk pages when collecting many rows, use result_id to read a stored result for free. There is no explicit when-to-use-vs-alternatives clause contrasting it with socialcrawl_request or socialcrawl_estimate.

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

All SocialCrawl tools Inspect

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.