Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@aparser-mcp find Google rankings for example.com for 'buy shoes' in US"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English · Русский
An MCP server that exposes the A-Parser HTTP API as tools, so an AI agent can drive parsing tasks directly — run a SERP or suggest query, queue bulk jobs, poll them, and fetch results.
Transport: stdio. Built on the official TypeScript MCP SDK.
A running A-Parser instance with the API enabled (Settings → API) and its
password. The API listens on http://<host>:9091/API.
Node.js ≥ 18 (for npx, or to build from source).
Related MCP server: ScrapeOps MCP Server
Published on npm — no install needed, npx fetches and runs it:
AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npx -y aparser-mcpgit clone <this-repo> aparser-mcp && cd aparser-mcp
npm install # builds dist/ via the prepare script
AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npm startThe server reads three environment variables:
Variable | Required | Description |
| yes | API base URL, e.g. |
| yes | API password from the A-Parser web UI. |
| no | Per-request HTTP timeout in seconds (default |
claude mcp add aparser \
--env AP_URL=http://<host>:9091/API \
--env AP_PASSWORD=<password> \
-- npx -y aparser-mcpOr add it to .mcp.json / your MCP client config:
{
"mcpServers": {
"aparser": {
"command": "npx",
"args": ["-y", "aparser-mcp"],
"env": {
"AP_URL": "http://<host>:9091/API",
"AP_PASSWORD": "<password>"
}
}
}
}Once the server and the aparser skill are installed, ask in plain language and
the skill picks the parser, geo, and output format for you:
“aparser, find positions of domain.com for: query one, query two in Serbia”
→ SE::Google::Position on google.rs (gl=rs, hl=sr) → rank per query.
“aparser, Google autocomplete for buy iphone” → suggestions.
“aparser, top-20 Google results for best running shoes in Spain” → SERP links.
More concrete tool-call examples: skills/aparser/examples.md.
Tool | What it does |
| Health check. Returns |
| Server status: tasks in queue, pid, list of available parsers. |
| Just the parser names (e.g. |
| A parser's result-field schema ( |
| Live proxies from the checkers as |
| Run one parse synchronously and return the result. Best for single lookups. |
| Queue a bulk task saved to a file. Returns the task id. |
| A task's status and live stats. |
| Poll a task until it completes; returns the final state. |
| Single-use download URL for a completed task's results file. |
one_request vs add_taskone_request — synchronous, one query, result returned inline. Use it for a
suggest lookup, a single SERP, checking one page.
add_task — asynchronous queue, many queries, output written to a file on the
server. Use wait_task then task_results to retrieve it.
add_task takes a parsers stack — a list of [name, preset, ...overrides] entries:
[["SE::Google", "default"]]In results_format, $p1 refers to the first entry, $p2 the second, etc. Call
parser_info("SE::Google") to see the fields you can reference:
$p1.serp.format('$link; $anchor\n')Per-request overrides (in one_request.options or a parsers entry) use the shape
{"type": "override", "id": "<param_id>", "value": <value>}.
Copy-adaptable request examples — suggests, SERP, position checks with geo,
captcha solving, desktop/mobile, bulk tasks — are in
skills/aparser/examples.md.
aparser)The skills/aparser/ directory holds a Claude Code skill that teaches an agent
when and how to call these tools — parser naming, presets, geo, resultsFormat,
and the position-checking query format. Install it so Claude picks it up:
# easiest — via skills.sh (installs into every supported agent):
npx skills add izzipizzy/aparser-mcp
# or manually as a personal Claude Code skill:
cp -r skills/aparser ~/.claude/skills/aparserIt then loads automatically when you ask about A-Parser positions/SERPs/suggests.
(Inside the izzy plugin it is the izzy:aparser skill.) See
skills/aparser/SKILL.md and skills/aparser/api-reference.md.
Parsers that hit search engines need working proxies. If one_request hangs or
errors, check get_proxies and the parser's proxy settings in A-Parser.
Secrets are never stored in this repo. Keep AP_PASSWORD in your MCP client
config or the environment.
npm install # install deps + build
npm run build # compile src/ -> dist/
npm start # run the built server (needs AP_URL / AP_PASSWORD)Source is a single file: src/index.ts.
Queue a bulk parsing task. Returns the task id (taskUid). Poll it with task_state / wait_task, then fetch the output with task_results.
parsers: stack as a list of [parser_name, preset_name, ...overrideObjects], e.g. [["SE::Google","default"]]. $p1 in a resultsFormat refers to the first entry.
results_format: output template, e.g. "$p1.serp.format('$link\n')"; omit to use the preset's own format. results_file_name supports macros like $datefile.format() ($taskId is NOT a valid macro).
| Name | Required | Description | Default |
|---|---|---|---|
| do_log | No | Write per-query logs to the A-Parser DB (view in UI). On by default. | |
| parsers | Yes | Parser stack, e.g. [["SE::Google","default"]]. | |
| queries | No | Inline queries (when queries_file is not given). | |
| priority | No | ||
| queries_file | No | Server-side path to a queries file. | |
| query_format | No | How each input line becomes a query (default "$query"). | $query |
| config_preset | No | Thread/config preset; defaults to AP_CONFIG_PRESET or th17. | default |
| results_append | No | ||
| results_format | No | Output template; omit to use the preset format. | |
| unique_queries | No | ||
| results_prepend | No | ||
| results_file_name | No | $datefile.format().txt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the operation is asynchronous (returns a taskUid for later polling) and notes specific format constraints. However, it does not address side effects, required permissions, or failure modes, so transparency is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the core purpose and then providing necessary details. Every sentence adds value, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description covers the essential workflow: return value, polling steps, and result retrieval. It explains key parameters and caveats. Some minor gaps remain (e.g., other parameters), but the overall context is sufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 58% parameter coverage, and the description significantly compensates by explaining the parsers stack structure with a concrete example, the meaning of $p1 in results_format, and the macro behavior of results_file_name. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues a bulk parsing task and returns the taskUid. It explicitly distinguishes the workflow from sibling tools by mentioning polling with task_state/wait_task and fetching output with task_results, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: queue a task, then poll with task_state/wait_task, then fetch with task_results. It does not explicitly mention alternatives like one_request, but the 'bulk parsing task' phrasing conveys when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get live proxies from the proxy checkers as {"ip:port": ["type", ...]}.
| Name | Required | Description | Default |
|---|---|---|---|
| checkers | No | Optional list of checker names to filter by. Omit for all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains the output format but does not disclose whether the operation is read-only, resource consumption, or any side effects. The description is adequate but lacks explicit behavioral clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential information without any superfluous content. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description is largely complete. It covers the purpose, resource, and output format. However, it could mention potential error conditions or limits for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for the 'checkers' parameter. The description does not add semantic value beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'live proxies from the proxy checkers', and specifies the output format. It distinguishes from sibling tools which focus on tasks, parsers, or system info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving proxy data but does not explicitly state when to use this tool vs alternatives, nor provides context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get A-Parser status: tasks in queue, pid, and the list of available parsers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it 'gets' status, implying a read-only operation, but does not disclose any behavioral traits such as authentication requirements, rate limits, or side effects. The description is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the purpose and lists the key output fields succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description adequately specifies what the tool returns (tasks in queue, pid, list of parsers). However, it could be slightly improved by noting that the output is a snapshot of current status. Still, it is reasonably complete for a simple status retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description naturally adds no parameter-level information. Baseline 4 is appropriate as the schema provides 100% coverage by being empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves A-Parser status including tasks in queue, pid, and list of available parsers. This is a specific verb+resource pairing that distinguishes it from siblings like 'task_state' or 'ping'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The usage context is implied by the name and description (general status check), but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the names of all installed parsers (e.g. "SE::Google", "SE::Google::Suggest").
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description correctly implies a read-only operation. However, it could explicitly state that it does not modify any state. The simplicity of the tool makes this a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys purpose and provides an example. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description is complete. It fully explains what the tool returns and gives representative examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema description coverage is 100%. The description does not need to add parameter meaning, earning a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'names of all installed parsers', with concrete examples. It distinguishes itself from sibling tools like 'parser_info' which likely provides details on specific parsers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it could mention that this tool is useful for getting a list to use with parser_info, but it does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a single parse synchronously and return the result immediately. Best for one-off lookups (a suggest query, one SERP, one page). For many queries or saved output files, use add_task instead.
raw_results=true -> structured results array (recommended); false -> a single formatted resultString from the preset.
options: per-request overrides, each {type:'override', id:'', value:}.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The query to parse (keyword, URL, etc.). | |
| parser | Yes | Parser name, e.g. "SE::Google::Suggest". | |
| preset | No | Saved parser preset name. | default |
| options | No | Per-request parameter overrides. | |
| raw_results | No | Structured results array vs one formatted string. | |
| config_preset | No | Thread/config preset name; defaults to AP_CONFIG_PRESET or th17. | default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses synchronous execution, immediate return, and the difference between raw_results and a formatted resultString. It also explains the structure of the options array. It does not mention error handling or side effects, but for a parse tool this is reasonable coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. The first sentence states the action and result. The following sentences and bullet-like lines are well-structured and each adds necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of a fully described schema, the description adequately covers the core use case, output format, and relationship to add_task. It does not mention error handling or edge cases, but the synchronous single-parse scope makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly describing the result of raw_results=true/false (naming 'results' and 'resultString') and by giving the exact shape of each options override ({type:'override', id, value}). This goes beyond the schema's generic 'Per-request parameter overrides.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Run a single parse synchronously and return the result immediately.' It uses a specific verb and resource, and distinguishes itself from add_task by contrasting one-off lookups with batch processing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Best for one-off lookups... For many queries or saved output files, use add_task instead.' This names the alternative tool and specifies when not to use it, giving clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe a parser's result fields. Returns the results schema: arrays (nested lists like serp/ads) and flat (scalar fields like $query, $totalcount) that you can reference in a resultsFormat template. Call this before writing a resultsFormat for add_task.
| Name | Required | Description | Default |
|---|---|---|---|
| parser | Yes | Parser name, e.g. "SE::Google". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It explains the return structure but does not explicitly state that the tool is read-only or has no side effects. For a simple info tool, this is acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, return details, and usage guidance. It is front-loaded, concise, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
In the absence of an output schema, the description explains the return value well by categorizing fields as arrays and flat with examples. It ties the tool to add_task, providing context. Minor omission: it doesn't specify the format of the returned schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter described as 'Parser name, e.g. "SE::Google".' The description does not add additional meaning to the parameter, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Describe a parser's result fields.' It also specifies what it returns (arrays and flat fields) and how it relates to add_task, distinguishing it from sibling tools like info or list_parsers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this before writing a resultsFormat for add_task,' providing clear context. However, it does not mention when not to use it or alternatives, leaving room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health-check the A-Parser server. Returns "pong" when reachable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the return value upon success but does not describe failure behavior (e.g., timeout, error handling). This is adequate for a simple tool but lacks completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the purpose and return value concisely. Every word is necessary, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is fully complete. It tells what the tool does and what to expect as output, which is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema description coverage is 100% (vacuously). Baseline is 3, and the description does not need to add parameter info. No additional semantic value needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'health-check' and the resource 'A-Parser server', with a specific return value 'pong' when reachable. This distinguishes it from sibling tools like task_state or info, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a preliminary connectivity check, but does not explicitly state when to use it versus alternatives. For a simple health-check, the context is clear, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single-use download URL for a completed task's results file.
| Name | Required | Description | Default |
|---|---|---|---|
| task_uid | Yes | The task id returned by add_task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the key behavioral trait that the URL is 'single-use'. Since no annotations exist, the description carries the full burden and does so well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no wasted words. Efficiently communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with one param and no output schema. Could explicitly state failure behavior if task not completed, but implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for task_uid with basic description. The tool description adds value by explaining the URL's single-use nature and the requirement for a completed task.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'download URL for a completed task's results file', and the condition 'completed task'. It distinguishes from siblings like task_state and wait_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied that it should be used after task completion, but no explicit guidance on when not to use or alternatives like task_state or wait_task for incomplete tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a task's status and live stats (status, queriesDone, resultsCount, ...).
| Name | Required | Description | Default |
|---|---|---|---|
| task_uid | Yes | The task id returned by add_task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavior. It implies a read operation but does not disclose error handling, validity of task_uid, or whether stats are real-time. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous words, effectively conveying the purpose. Very concise, though a bit more structure could list returned fields explicitly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple state retrieval with one parameter and no output schema. Could mention that it is lightweight and intended for periodic polling, but not strictly required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for task_uid. The tool description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'task's status and live stats', listing specific fields (status, queriesDone, resultsCount). It distinguishes from siblings like add_task (creation) and task_results (results).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as wait_task or task_results. The description does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a task until it completes (or the timeout elapses). Returns the final state.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | Max seconds to wait before giving up. | |
| interval | No | Seconds between polls. | |
| task_uid | Yes | The task id returned by add_task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds key behavior not in the schema: polling until completion or timeout, and returning final state. However, with no annotations, more detail on side effects (none expected) or concurrency would help, but it's adequate for a simple poll.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero redundancy. Every word adds value: action (poll), condition (until complete or timeout), result (returns final state). Optimally front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description tells what is returned (final state) but not its structure. For a 3-parameter tool with simple behavior, this is minimally adequate but could be more informative about the return value format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the input schema (100% coverage). The description adds no additional semantic value beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls a task until completion or timeout, with a specific verb (poll) and resource (task). It implies waiting behavior, but doesn't explicitly contrast with sibling tools like task_state, so it's clear but not differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool instead of alternatives (e.g., task_state for a single check, or add_task to create a task). No conditions or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_task3 fields changedInput schema / properties / config_preset / descriptionAdded value: +"Thread/config preset; defaults to AP_CONFIG_PRESET or th17."Input schema / properties / do_log / defaultPrevious value: -falseNew value: +trueInput schema / properties / do_log / descriptionAdded value: +"Write per-query logs to the A-Parser DB (view in UI). On by default."one_request1 field changedInput schema / properties / config_preset / descriptionPrevious value: -"Thread/config preset name."New value: +"Thread/config preset name; defaults to AP_CONFIG_PRESET or th17."v0.1.3add_taskget_proxiesinfolist_parsersone_requestparser_infopingtask_resultstask_statewait_taskScored across 10 tools
Each tool targets a distinct concern: health (ping), server status (info), parser discovery (list_parsers), schema introspection (parser_info), proxy access (get_proxies), synchronous execution (one_request), and async task lifecycle (add_task, task_state, wait_task, task_results). Even task_state and wait_task differ clearly: one returns a snapshot, the other blocks until completion.
Task operations mostly use a task_ prefix (add_task, task_state, wait_task, task_results) and parser operations pair list_parsers with parser_info. However, the mix of verb-first names (add_task, get_proxies) and resource-first names (task_state, parser_info), plus the outlier one_request, prevents a perfect score.
With 10 tools, the set is well-scoped for a parsing automation server. Every tool serves a clear role in the workflow—health, info, discovery, schema, proxies, single request, task submission, monitoring, and retrieval—with no redundancy or bloat.
The surface covers the full lifecycle: health check, server status, parser listing and schema introspection, proxy management, synchronous one-off parsing, bulk task submission, monitoring (both snapshot and blocking), and result retrieval. No critical operation is missing for typical usage.
Web scraping runtime for agents: parsers, scrapes, batches, crons, and SQL databases.
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
SEO research, audits, backlinks, GSC, and content workflow tools for AI agents.
Live web access for agents: scrape, SERP search, crawl/map, 74 collectors, datasets, proxies.
