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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true and destructiveHint=false, so safety and repeatability are covered. The description still adds real value beyond them: exact fetch surface (HTML, same-site scripts, source maps), the specific credential types detected, that keys are shown masked, and that findings come back in Hebrew. It stops short of noting rate limits, scan duration, or how many scripts are followed before truncation.

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?

Dense and front-loaded: the fetch mechanism and reported findings come first, the usage trigger second, the exclusions last. The long parenthetical enumerations of secret types and hosted builders are information-bearing rather than filler, though the single unbroken paragraph makes it slightly harder to scan than a segmented layout would.

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?

With no output schema, the description must carry the return shape, and listing the exact finding categories plus 'Findings are in Hebrew' goes most of the way. It still leaves the agent guessing how results are structured (per-finding severity? counts? partial-scan failures on timeout or blocked CSP), which matters for a single-URL open-world scan.

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?

Single required parameter with 100% schema description coverage, and the schema already supplies both the 2000-char constraint and a format example ('my-app.lovable.app or https://example.com'). The description adds nothing about the url parameter beyond implying a scheme-less host is acceptable, so the schema carries the load and baseline 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?

States a concrete verb and scope: it reads one public web app the way a browser does (HTML, same-site scripts, source maps) and reports leaked secrets and missing protections. The scope (live public URL, client-visible only) inherently separates it from env-file or database-config scanning, but the description never names the siblings check_env_exposure or lint_supabase_rls, so the differentiation is implicit rather than explicit.

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?

Gives a clear trigger: 'Use when someone built an app with Lovable, Base44, Bolt, Cursor, Replit or similar and asks whether it is safe to launch or whether a key leaked.' It also draws hard boundaries with 'It does not sign in, guess paths or query the app's database,' which is genuine when-not guidance, but it never routes the agent to an alternative tool for the cases it excludes.

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