karaposu · Aug 24, 2026
diff --git a/dataset_inputs.js b/dataset_inputs.js
@@ -0,0 +1,33 @@
+'use strict'; /*jslint node:true es9:true*/
+
+// Model-facing descriptions for the generated web_data_* tool inputs, keyed
+// by input name (12 names cover all 50 datasets). Values travel to the
+// trigger endpoint as STRINGS (the dataset table's own defaults are "3",
+// "10", ""), so numeric inputs say "as a numeric string" and the
+// empty-string defaults explain that empty means "no filter". A name missing
+// from this map ships undescribed (the old behaviour) and is caught by the
+// consistency check in test/dataset-inputs.test.js, not at runtime.
+export const DATASET_INPUT_DESCRIPTIONS = {
+    url: 'URL of the target page for this dataset (see the tool '
+        +'description for the expected site and page type).',
+    prompt: 'The prompt/question to submit. The tool returns the AI '
+        +'answer as markdown.',
+    package_name: 'The package name exactly as published on the registry '
+        +'(e.g., "react" for npm, "langchain-brightdata" for PyPI).',
+    keyword: 'Search keyword(s) to find products, as plain text '
+        +'(e.g., "wireless earbuds").',
+    first_name: 'First name of the person to search for.',
+    last_name: 'Last name of the person to search for.',
+    num_of_reviews: 'How many reviews to collect, as a numeric string '
+        +'(e.g., "50").',
+    days_limit: 'Only collect reviews from the last N days, as a numeric '
+        +'string (e.g., "3").',
+    start_date: 'Start of the date range (e.g., "2025-01-31"); empty '
+        +'string (the default) applies no start-date filter.',
+    end_date: 'End of the date range (e.g., "2025-01-31"); empty string '
+        +'(the default) applies no end-date filter.',
+    num_of_comments: 'How many comments to collect, as a numeric string '
+        +'(e.g., "10").',
+    days_back: 'Collect posts from the last N days, as a numeric string; '
+        +'empty string (the default) applies no time filter.',
+};
diff --git a/package.json b/package.json
@@ -44,7 +44,8 @@
         "browser_session.js",
         "aria_snapshot_filter.js",
         "tool_groups.js",
-        "prompts.js"
+        "prompts.js",
+        "dataset_inputs.js"
     ],
     "mcpName": "io.github.brightdata/brightdata-mcp"
 }
diff --git a/server.js b/server.js
@@ -6,6 +6,7 @@ import axios from 'axios';
 import {tools as browser_tools} from './browser_tools.js';
 import prompts from './prompts.js';
 import {GROUPS} from './tool_groups.js';
+import {DATASET_INPUT_DESCRIPTIONS} from './dataset_inputs.js';
 import {parse_google_search_response} from './search_utils.js';
 import {dataset_id_schema, filter_schema, metadata_to_fields, FILTER_OPERATORS}
     from './search_dataset_schema.js';
@@ -1207,6 +1208,12 @@ for (let {dataset_id, id, description, inputs, defaults = {},
     for (let input of inputs)
     {
         let param_schema = input=='url' ? z.string().url() : z.string();
+        // Descriptions are keyed by input name; a name with no entry ships
+        // undescribed (the old behaviour) and is caught by the consistency
+        // check in test/dataset-inputs.test.js, not at runtime.
+        const description = DATASET_INPUT_DESCRIPTIONS[input];
+        if (description)
+            param_schema = param_schema.describe(description);
         parameters[input] = defaults[input] !== undefined ?
             param_schema.default(defaults[input]) : param_schema;
     }

diff --git a/test/dataset-inputs.test.js b/test/dataset-inputs.test.js
@@ -0,0 +1,85 @@
+'use strict'; /*jslint node:true es9:true*/
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {dirname, resolve} from 'node:path';
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
+import {DATASET_INPUT_DESCRIPTIONS} from '../dataset_inputs.js';
+
+const test_dir = dirname(fileURLToPath(import.meta.url));
+const repo_root = resolve(test_dir, '..');
+
+// The datasets table lives inside server.js (unimportable without its
+// bootstrap), so coverage is checked against the source text: collect every
+// input name from the table's `inputs: [...]` arrays (all single-line).
+function table_input_names(){
+    const src = readFileSync(resolve(repo_root, 'server.js'), 'utf8');
+    const names = new Set();
+    for (const m of src.matchAll(/inputs:\s*\[([^\]]*)\]/g))
+        for (const q of m[1].matchAll(/'([^']+)'/g))
+            names.add(q[1]);
+    return names;
+}
+
+test('every dataset input has a description, and no orphan entries', ()=>{
+    const names = table_input_names();
+    assert.ok(names.size>0, 'found the datasets table inputs');
+    for (const name of names)
+        assert.ok(DATASET_INPUT_DESCRIPTIONS[name],
+            `input "${name}" needs an entry in DATASET_INPUT_DESCRIPTIONS`);
+    for (const key of Object.keys(DATASET_INPUT_DESCRIPTIONS))
+        assert.ok(names.has(key),
+            `map entry "${key}" matches no dataset input (stale?)`);
+});
+
+test('description texts carry their load-bearing properties', ()=>{
+    for (const [name, text] of Object.entries(DATASET_INPUT_DESCRIPTIONS))
+        assert.ok(text.length>=20, `"${name}" description is non-trivial`);
+    for (const name of ['num_of_reviews', 'days_limit', 'num_of_comments',
+        'days_back'])
+    {
+        assert.match(DATASET_INPUT_DESCRIPTIONS[name], /numeric string/,
+            `"${name}" must state the numeric-string wire format`);
+    }
+    for (const name of ['start_date', 'end_date', 'days_back'])
+    {
+        assert.match(DATASET_INPUT_DESCRIPTIONS[name], /empty string/,
+            `"${name}" must explain its empty-string default`);
+    }
+});
+
+// End-to-end: the descriptions must actually reach MCP clients. Generated
+// inputs had NO description field before this fix (verified:
+// days_back was exactly {"type":"string","default":""}), so this test fails
+// on the unfixed code and passes after the loop attaches .describe().
+test('generated tools expose input descriptions over tools/list', async()=>{
+    const client = new Client(
+        {name: 'dataset-inputs-test', version: '0.0.1'},
+        {capabilities: {tools: {}}});
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: ['server.js'],
+        cwd: repo_root,
+        env: {...process.env, API_TOKEN: 'dummy-token', PRO_MODE: 'true'},
+    });
+    try {
+        await client.connect(transport);
+        const {tools} = await client.listTools();
+        const prop = (tool_name, input)=>tools
+            .find(t=>t.name==tool_name)?.inputSchema?.properties?.[input];
+        assert.equal(prop('web_data_reddit_comments', 'days_back')?.description,
+            DATASET_INPUT_DESCRIPTIONS.days_back);
+        assert.equal(
+            prop('web_data_google_maps_reviews', 'days_limit')?.description,
+            DATASET_INPUT_DESCRIPTIONS.days_limit);
+        assert.equal(
+            prop('web_data_google_maps_reviews', 'url')?.description,
+            DATASET_INPUT_DESCRIPTIONS.url);
+        assert.equal(prop('web_data_reddit_comments', 'days_back')?.default,
+            '', 'defaults still surface alongside descriptions');
+    } finally {
+        await client.close();
+    }
+});