search_dataset

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: it is 'Elasticsearch-backed (fast)' with 'no snapshot', enforces a max filter nesting depth of 3, and notes pagination via search_after. It does not disclose rate limits or result/envelope shape, keeping it short of a 5.

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?

Front-loaded with purpose and usage before detail, and the bulleted operator/dataset lists are scannable. The operator list duplicates the schema's enum and could arguably be trimmed, but every part remains actionable.

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 complex filter-tree plus pagination tool with no output schema, the definition covers prerequisites, dataset IDs, filter grammar, depth limits, and the search_after flow. It stops short of describing the record shape returned, which is the main residual gap.

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 80%, so most fields are documented structurally, but the description adds value the schema cannot: it maps the three opaque dataset_id UUIDs to human-meaningful resources (LinkedIn profiles, contact-enriched profiles, company info) and explains the filter tree grammar and full leaf-operator list in prose. This goes beyond baseline 3.

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 specific verb and resource ('Search a Bright Data dataset by a filter and get matching records back directly') and explicitly distinguishes itself from the sibling run_scraper by scope (find many by criteria vs. collect fresh by URL). An agent can differentiate without opening either schema.

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?

Explicitly states when to use it ('to FIND MANY records by criteria, as opposed to run_scraper which collects fresh records by URL') and gives a prerequisite ('First call list_dataset_fields to get valid field names'). Names the alternative and the condition that selects it.

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