Skip to main content
Glama
Sign In
Bright Data MCP

Bright Data MCP

Official
by brightdata
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

search_dataset

Read-only

Find matching records in Bright Data datasets by applying field filters and returning up to 10 results. Use it to query LinkedIn profile or company datasets by criteria.

Instructions

Search a Bright Data dataset by a filter and get matching records back directly (fast Elasticsearch-backed search; no snapshot). Use this to FIND MANY records by criteria, as opposed to run_scraper which collects fresh records by URL. First call list_dataset_fields to get valid field names. A filter is a tree: a group {operator:"and"|"or", filters:[...]} or a leaf {name, value, operator}. Max nesting depth 3. Leaf operators: =, !=, <, <=, >, >=, in, not_in, includes, not_includes, array_includes, not_array_includes, is_null, is_not_null. Supported dataset_id values:

  • gd_l1viktl72bvl7bjuj0: LinkedIn people profiles

  • gd_me5ppxjr2ge6icjuh0: LinkedIn people profiles (contact-enriched)

  • gd_l1vikfnt1wgvvqz95w: LinkedIn company information

Input Schema

NameRequiredDescriptionDefault
sizeNoNumber of records to return (max 10, default 10)
sortNoSorting: "default", "random", or a custom array like [{"timestamp":"asc"}]. Use "default" or custom sort to paginate with search_after.
filterYesFilter tree describing which records to match. Required, cannot be empty.
dataset_idYes
search_afterNoPagination cursor from a previous response's search_after value.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv4.1.0
    • changedInput schema / properties / filter / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "filters": {
-        "items": {
-          "anyOf": [
-            {
-              "additionalProperties": false,
-              "properties": {
-                "filters": {
-                  "items": {
-                    "anyOf": [
-                      {
-                        "additionalProperties": false,
-                        "properties": {
-                          "filters": {
-                            "items": {
-                              "additionalProperties": false,
-                              "properties": {
-                                "name": {
-                                  "description": "Field name to filter on. Get valid field names from the list_dataset_fields tool.",
-                                  "type": "string"
-                                },
-                                "operator": {
-                                  "description": "Filter operator, one of: =, !=, <, <=, >, >=, in, not_in, includes, not_includes, array_includes, not_array_includes, is_null, is_not_null",
-                                  "type": "string"
-                                },
-                                "value": {
-                                  "anyOf": [
-                                    {
-                                      "type": "string"
-                                    },
-                                    {
-                                      "type": "number"
-                                    },
-                                    {
-                                      "type": "boolean"
-                                    },
-                                    {
-                                      "items": {
-                                        "type": [
-                                          "string",
-                                          "number",
-                                          "boolean"
-                                        ]
-                                      },
-                                      "type": "array"
-                                    }
-                                  ]
-                                }
-                              },
-                              "required": [
-                                "name",
-                                "operator",
-                                "value"
-                              ],
-                              "type": "object"
-                            },
-                            "minItems": 1,
-                            "type": "array"
-                          },
-                          "operator": {
-                            "enum": [
-                              "and",
-                              "or"
-                            ],
-                            "type": "string"
-                          }
-                        },
-                        "required": [
-                          "operator",
-                          "filters"
-                        ],
-                        "type": "object"
-                      },
-                      {
-                        "$ref": "#/properties/filter/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items"
-                      }
-                    ]
-                  },
-                  "minItems": 1,
-                  "type": "array"
-                },
-                "operator": {
-                  "enum": [
-                    "and",
-                    "or"
-                  ],
-                  "type": "string"
-                }
-              },
-              "required": [
-                "operator",
-                "filters"
-              ],
-              "type": "object"
-            },
-            {
-              "$ref": "#/properties/filter/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items"
-            }
-          ]
-        },
-        "minItems": 1,
-        "type": "array"
-      },
-      "operator": {
-        "enum": [
-          "and",
-          "or"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "operator",
-      "filters"
-    ],
-    "type": "object"
-  },
-  {
-    "$ref": "#/properties/filter/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "filters": {
+        "items": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "filters": {
+                  "items": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": false,
+                        "properties": {
+                          "filters": {
+                            "items": {
+                              "additionalProperties": false,
+                              "properties": {
+                                "name": {
+                                  "description": "Field name to filter on. Get valid field names from the list_dataset_fields tool.",
+                                  "type": "string"
+                                },
+                                "operator": {
+                                  "description": "Filter operator, one of: =, !=, <, <=, >, >=, in, not_in, includes, not_includes, array_includes, not_array_includes, is_null, is_not_null",
+                                  "type": "string"
+                                },
+                                "value": {
+                                  "anyOf": [
+                                    {
+                                      "type": "string"
+                                    },
+                                    {
+                                      "type": "number"
+                                    },
+                                    {
+                                      "type": "boolean"
+                                    },
+                                    {
+                                      "items": {
+                                        "type": [
+                                          "string",
+                                          "number",
+                                          "boolean"
+                                        ]
+                                      },
+                                      "type": "array"
+                                    }
+                                  ],
+                                  "description": "Value to compare against. Omit for is_null / is_not_null."
+                                }
+                              },
+                              "required": [
+                                "name",
+                                "operator"
+                              ],
+                              "type": "object"
+                            },
+                            "minItems": 1,
+                            "type": "array"
+                          },
+                          "operator": {
+                            "enum": [
+                              "and",
+                              "or"
+                            ],
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "operator",
+                          "filters"
+                        ],
+                        "type": "object"
+                      },
+                      {
+                        "$ref": "#/properties/filter/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items"
+                      }
+                    ]
+                  },
+                  "minItems": 1,
+                  "type": "array"
+                },
+                "operator": {
+                  "enum": [
+                    "and",
+                    "or"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "operator",
+                "filters"
+              ],
+              "type": "object"
+            },
+            {
+              "$ref": "#/properties/filter/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items"
+            }
+          ]
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "operator": {
+        "enum": [
+          "and",
+          "or"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "operator",
+      "filters"
+    ],
+    "type": "object"
+  },
+  {
+    "$ref": "#/properties/filter/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items/anyOf/0/properties/filters/items"
+  }
+]
  2. Addedv3.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description only needs to add mechanism. It does: "fast Elasticsearch-backed search; no snapshot" tells the agent results are existing indexed data, not a fresh capture, which is the key behavioral distinction. It omits the hard 10-record cap and pagination flow beyond the schema's own text, so not fully complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling contrast, then prerequisite, then filter grammar, then the dataset catalog — a logical build. Dense but each block earns its place; the bulleted dataset list is the one mild expansion, though it supplies information absent from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description only says "get matching records back directly" without indicating the response shape or that search_after comes from a previous response (that detail lives in the schema). For a 5-parameter read tool with annotations carrying safety, however, what is present is enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the baseline is 3, but the description substantially compensates: it explains the filter is a tree of group vs. leaf nodes, states max nesting depth 3 (which the deeply $ref'd schema never says plainly), enumerates all 14 leaf operators, and gives human-readable meanings for each of the three dataset_id enum values that the schema leaves unlabeled. That is real meaning beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 ... get matching records back directly") plus the retrieval mechanism (Elasticsearch-backed, no snapshot). It explicitly distinguishes itself from the sibling run_scraper, so an agent can route between the two 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the positive case ("FIND MANY records by criteria"), the contrast case ("as opposed to run_scraper which collects fresh records by URL"), and a prerequisite step ("First call list_dataset_fields to get valid field names"). Nothing is left to inference about when to pick this tool.

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

Deploy Server

Other Tools