get_scan_result

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

With no annotations, the description fully carries behavioral disclosure. It explains API key requirement and 403 behavior, output size difference between summary and full, and the 404 polling behavior. All these add real behavioral context beyond the schema.

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 front-loaded with the core purpose, then proceeds logically through prerequisites, return content, the optional full-detail behavior, and polling edge case. Every sentence adds value; no wasted phrases or repetition of schema fields.

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 there is an output schema and no annotations, the description covers the important contextual aspects: auth, result content, size trade-offs, and error handling. It does not need to spell out the return structure since an output schema exists, so the description is complete.

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 description coverage is 0%, so the description must compensate. It explicitly explains the 'detail' parameter with its enum values and impact on context window. The 'uuid' parameter is implicitly clear from the context of fetching a specific scan, and the description notes the relationship to recently submitted scans.

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 opens with a clear verb+resource+scope: 'Fetch a completed urlscan.io scan as a summarised verdict.' It distinguishes itself from siblings by focusing on retrieving an existing scan's summary verdict rather than submitting, searching, or providing visual/DOM outputs.

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?

Provides clear usage context: use when a scan is completed, poll again on 404 for fresh scans, and use detail='full' sparingly because it consumes context. However, it doesn't explicitly name sibling tools as alternatives for other scenarios (e.g., use search_scans to find scans).

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