Check the status of an asynchronous scan task. Returns the current task status using native MCP task semantics (working, completed, failed, cancelled) without blocking. Use url_scanner_async_task_result to retrieve the result once completed.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task ID to check status for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it uses native MCP task semantics with specific statuses and that it is non-blocking—valuable behavioral context for an agent deciding how to poll. No contradictions.
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 short sentences that front-load the purpose and add only necessary behavioral and usage details. Every sentence contributes, with no filler.
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?
For a simple one-parameter status-check tool with no output schema, the description sufficiently covers purpose, return semantics, and next steps. It even provides the possible status values, making it self-contained.
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 single parameter task_id is fully described in the schema ('The task ID to check status for.'), giving 100% schema description coverage. The tool description does not add additional parameter details, but the baseline of 3 applies because the schema handles it.
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 uses a specific verb ('Check') and resource ('status of an asynchronous scan task'), clearly distinguishing it from starting scans or retrieving results. It even lists the status values, reinforcing its distinct role.
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 directs the agent to use url_scanner_async_task_result for result retrieval after completion, providing a clear alternative and implying this tool is not for retrieving results. This matches the 'explicit alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose: sync vs async scan, with/without intent, and task status vs result retrieval. The descriptions explicitly clarify when to use each, leaving no ambiguity about which tool to select.
Names follow a predictable url_scanner_ prefix pattern with consistent suffixes for intent ('_with_intent') and sync/async distinction. The minor inconsistency is mixing 'async_scan' for submission with 'async_task_status'/'async_task_result' for polling, but the pattern remains readable and understandable.
Six tools is well-scoped for a URL scanning service: it covers the sync/async dimension, intent context, and the full task lifecycle (submit, check status, get result). No redundant or missing categories for the core purpose.
The core scan lifecycle is fully covered (sync and async, with intent, status polling, result retrieval). The only notable gap is the lack of a cancel operation for async tasks, which could be useful for long-running scans, but this is a minor omission not likely to cause agent failures.
