scan_domain

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description reinforces this with 'Read-only — no domain mutation, no destructive side effects' and adds practical behavioral context: scan duration (~3-8s), no authentication required, and the scope of returned data. This goes beyond the annotations by informing the agent about speed and authentication expectations.

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 information-dense but every sentence contributes value: the first sentence states the core function, the second details the return payload, the third asserts safety, the fourth provides usage guidance and alternatives, and the fifth gives follow-up actions and auth status. It is well-structured, front-loaded with the action, and free of 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?

The description provides a comprehensive overview of what the tool returns (grade, score, issue list, recommendations, result sections, citation URLs) and its operational characteristics. Even without an output schema, the agent knows exactly what to expect. The guidance on follow-up tools and the explicit mention of no auth round out the context. For a tool with one parameter and rich annotations, this 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?

The schema covers 100% of the single parameter (domain) with a precise description including example and restrictions. The tool description does not add any additional parameter-specific semantics beyond implying the domain is the subject of the scan. With high schema coverage, a baseline score of 3 is appropriate, as the description confirms but does not augment 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 runs a DNS and email security scan with a specific verb ('Run'), identifies the resource (IntoDNS.ai), and enumerates the expected outputs (grade, score, issues, recommendations, sections, citations). It also distinguishes itself from sibling tools by calling itself 'The default tool for agent-visible scan evidence' and explicitly contrasts with get_everything_report and start_deep_scan.

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 gives explicit guidance: it names alternatives (get_everything_report for deeper reports, start_deep_scan for slower analysis) and explains when each is preferable. It also suggests follow-up actions (explain_issue, generate_dns_fix) and notes the read-only nature, which implies it's safe for initial scanning.

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