mcp-coreclaw

run_worker

Run a CoreClaw worker with an ad-hoc JSON input payload.

WHEN TO USE: Use when the user wants to start, execute, scrape, crawl, or run a worker with specific input. 中文触发: 当用户要在 CoreClaw 中查询、运行、重跑、停止、导出或查看对应 worker/run/task 数据时使用。

WHEN NOT TO USE: Do not use public web search or code search for private CoreClaw platform data. Do not call excluded internal worker-version or internal-detail APIs.

RETURNS: JSON with run_slug for async runs or synchronous result fields for sync runs.

WORKFLOW: Call get_worker_input_schema first, then run_worker, then get_worker_run or get_last_worker_run, then results/export/log tools.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Result limit. Example: 20. Must be 1-100. (default: 20)
`offset`	No	Page number, 1-based. offset=1 is page 1; offset=0 is accepted as page 1. (default: 1)
`version`	No	Worker script version. Example: "latest" or "1.0.1". Obtain from get_worker; default is backend latest. (optional)
`is_async`	No	Whether CoreClaw should run asynchronously. Example: true. Use false only for small synchronous runs. (default: true)
`worker_id`	Yes	Worker slug or owner path. Example: "demo-worker" or "owner~demo-worker". Obtain from list_store_workers or list_workers.
`input_json`	No	Worker business input payload as a JSON object string. Example: {"keyword":"coffee","limit":10}. The MCP server sends it as input.parameters.custom, matching CoreClaw saved task payloads. Schema comes from get_worker_input_schema. Marked optional because the schema does not force it, but almost every worker requires input fields to run — omit only when the worker has no business fields. (optional)
`callback_url`	No	Callback URL for asynchronous status updates. Example: "https://client.example.com/openapi/callback". (optional)
`raw_input_json`	No	Advanced escape hatch: full CoreClaw input object to send as input without wrapping. Example: {"parameters":{"system":{"proxy_region":"US"},"custom":{"keyword":"coffee"}}}. Do not combine with input_json. (optional)

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already mark this as non-read-only, non-idempotent, and non-destructive. The description adds valuable behavioral detail: async runs return a run_slug, sync runs return result fields, and input_json is wrapped as input.parameters.custom. It does not mention side effects or error cases, but given annotation coverage, this is adequate.

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 well-organized into headed sections (purpose, when, when not, returns, workflow), making it scannable and front-loaded. The Chinese trigger line is somewhat redundant for English users, but it serves bilingual audiences and only slightly lengthens the text. Every section contributes operational value.

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?

For a complex tool with 8 parameters, no output schema, and many sibling tools, the description covers the essential context: return shape, async/sync behavior, required sequencing, and clear boundaries against other tools. It lacks error handling and edge cases, but the rich schema and workflow guidance make it sufficiently complete for an agent to invoke correctly.

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 baseline is 3. The description adds meaningful context beyond the schema by explaining the relationship between input_json and raw_input_json, the escaping mechanism, and the workflow dependency on get_worker_input_schema. This extra clarification justifies a 4.

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+resource: 'Run a CoreClaw worker with an ad-hoc JSON input payload.' This clearly distinguishes run_worker from siblings like run_worker_task (saved task) and queue_worker_run (queued execution) by emphasizing ad-hoc payloads. The WHEN TO USE section further reinforces the scope with concrete actions (start, execute, scrape, crawl).

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

Usage Guidelines4/5

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

Explicit WHEN TO USE and WHEN NOT TO USE sections provide clear context, including a Chinese trigger phrase and exclusions for public search/internal APIs. The WORKFLOW section prescribes ordering with get_worker_input_schema first, then run_worker, then result/export tools. However, it does not name alternative sibling tools explicitly, so it stops short of a 5.

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

All mcp-coreclaw tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.7/5.0

Disambiguation3/5

Most tools follow a systematic scope pattern (user's last run, worker's last run, specific run), so intent is discernible, but the reversed word order (e.g., get_last_worker_run vs get_worker_last_run) makes many tools easy to conflate. Descriptions are thorough, yet the sheer number of near-identical names creates real misselection risk.

Naming Consistency3/5

Verbs and nouns are consistently snake_case, but the modifier order alternates unpredictably—some tools say last_worker_run, others worker_last_run—across abort/export/get/list/rerun groups. This inconsistency makes the set feel less coherent than a strict verb_noun pattern would.

Tool Count2/5

At 42 tools, the surface is heavily inflated by triplicating every run-related action across user-last, worker-last, and specific-run scopes. Many of these could be consolidated into a single tool with optional worker_id/run_id parameters, making the count feel excessive for the domain.

Completeness4/5

The surface covers the full lifecycle of workers, runs, tasks, queue, and account, including poll/verify/batch operations that go beyond basic CRUD. Minor gaps exist (e.g., no explicit run-input retrieval, no worker editing), but agents can achieve all common workflows without dead ends.

Resources

Need Help?