Retrieve the result of an asynchronous scan task. If completed, returns the full scan result (risk_score, confidence, agent_access_directive, etc.). If still running, returns status with retry_after_ms — call again after that interval. Non-blocking.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task ID to retrieve the result for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it distinguishes between completed and running states, provides the retry mechanism, and states non-blocking behavior. No contradiction with annotations.
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, each adding value: defines the action, describes the two possible outcomes, and gives a retry instruction. 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?
For a simple async polling tool with one parameter and no output schema, the description covers the key scenarios (completed vs running), retry timing, and example result fields. It is sufficient for an agent to use the tool correctly, though it does not address error cases or invalid task IDs.
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 the single parameter task_id fully described. The description does not add parameter-specific details, but the schema already carries the meaning. 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 uses a specific verb 'Retrieve' and names the resource 'result of an asynchronous scan task'. It clearly distinguishes from sibling tools by stating it returns the full scan result when complete, unlike url_scanner_async_task_status which likely only provides status.
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 explains the polling pattern: if still running, it returns retry_after_ms and tells the agent to call again after that interval. It also notes 'non-blocking'. However, it does not explicitly name alternatives like task_status for status-only use, but the guidance is clear and actionable.
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.
