search_dorks_live

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

With no annotations, the description carries the full load and does so well: it flags billable API calls, names the required env vars (BRIGHTDATA_API_KEY, BRIGHTDATA_SERP_ZONE), and discloses that the target leaves the boundary to Google/Bright Data via the [passive] tag. It stops short of rate limits, failure modes, or what happens when the default dork set is insufficient.

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?

Three dense sentences with no filler: action and return shape first, cost/credential constraints second, data-flow disclosure last. Every clause earns its place.

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 annotations and no output schema, the description does the heavy lifting — cost model, credentials, external data flow, and return fields are all covered. The remaining hole is the meaning/format of the required 'target' parameter, which leaves an agent slightly under-informed before calling.

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 only 50%, and the undocumented parameter is the single required one — 'target' — whose expected format (domain, IP, email, query string) is never stated, only mentioned obliquely as 'for a target.' The description adds nothing to 'json_output' beyond the schema, so it fails to compensate for the coverage gap.

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 names a specific verb and resource (execute Google dork queries) plus the data source (Bright Data SERP API) and return shape (title, URL, snippet), so the agent knows exactly what happens. It implicitly separates itself from the sibling generate_dorks by emphasizing 'live,' but never names or contrasts that sibling explicitly, which keeps it short of a 5.

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?

It discloses that up to 5 dorks run by default and that each is billable, which implies a cost-sensitive use context, but there is no explicit when-to-use versus generate_dorks (does the agent generate dorks first, or not?) and no prerequisite or exclusion guidance. Usage must be inferred.

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