brightdata-mcp-plus

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

Adds genuine context beyond the annotations: extraction runs through MCP sampling on the caller's model, and there is no extra Bright Data cost beyond the page fetch. It also implicitly signals caching via the fresh parameter's cost note. It doesn't disclose failure behavior when the model returns schema-invalid JSON, which is the main remaining gap.

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?

Two sentences, no waste; the mechanism and cost note come first and the parameter call-to-action second. Every clause carries information an agent needs.

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 convey the return shape and does (JSON, optionally constrained by a provided schema), and the cost model is covered. Missing only edge-case behavior such as what happens on extraction or schema-validation failure.

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 parameters are already documented in-schema (fresh, country, schema, extraction_prompt). The description reinforces that extraction_prompt is the core input and schema is optional shaping, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 ('Fetch a page') and transformation ('turn it into JSON') plus the non-obvious mechanism (MCP sampling with the caller's own model). This distinguishes it functionally from scrape_as_markdown/scrape_as_html, though it never names those siblings, so an agent must infer the boundary.

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?

The description implies when to use it (when you want structured JSON shaped by a prompt/schema) and notes the cost profile, but gives no explicit when-to-use/when-not guidance relative to scrape_as_markdown or scrape_as_html. The choice must be inferred from the output format implied by each tool name.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantive behavior beyond them: a three-tier fetch strategy (free direct, free headless render, billed Bright Data unlocker) and the fact that the result includes a note stating which path was taken. This billing/cost disclosure is exactly the kind of context annotations cannot convey.

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 tight sentences, each front-loaded with the most actionable information: what it returns first, the alternative second, the cost model third. No filler.

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 still covers return format (raw HTML, character offsets), the cost/billing implications, and the fallback ladder. Nothing an agent needs to select or call this tool correctly is missing.

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 the schema already documents most params. The description adds workflow meaning by framing offset/max_chars as a pagination pair and implying the truncated-result flow, though it doesn't explain the interaction with next_offset beyond what the schema says.

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 ('Fetch one page and return its raw HTML') plus its pagination model, and explicitly contrasts with the scrape_as_markdown sibling so an agent can choose 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 names the preferred alternative and the exact condition to deviate: 'Prefer scrape_as_markdown unless you need markup, attributes or embedded JSON.' That is a clear when-to-use and when-not-to-use rule.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the three-tier fetch strategy (direct free, headless browser free, Bright Data billed only on block) and that a note after the result identifies which path was used. The truncation/pagination behavior is also spelled out, which is exactly the kind of cost and output behavior annotations cannot convey.

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 tight sentences, front-loaded with the core action, then cost behavior, then pagination and format tips. Every sentence carries distinct information with no repetitive restatement of the title.

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 carries return-value burden and does explain the post-result note and pagination offsets. Minor gap: it says 'returned offset' while the schema field is next_offset, and it doesn't describe the shape of the Markdown payload beyond 'compact'.

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 83%, so the schema already documents nearly every parameter, including format, offset, fresh, and max_chars. The description adds only the format=raw recommendation and the offset-retry loop, which is marginal value over structured data. The 3 baseline 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?

The description opens with a specific verb and resource — 'Fetch one web page and return it as compact Markdown' — and the 'one web page' scope implicitly separates it from scrape_batch. It doesn't explicitly name siblings like scrape_as_html or extract, so the differentiation is inferred rather than stated.

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 gives clear operational guidance: use format=raw for unprocessed Markdown, and call again with the returned offset when a page is truncated. It also explains the fetch cost ladder, which tells an agent what to expect. It stops short of saying when to prefer scrape_as_html or extract over this tool.

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

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

Annotations only say readOnly/idempotent/openWorld; the description adds the critical non-obvious behavior: a three-tier fetch strategy (free direct, free local headless browser, billed Bright Data Web Unlocker only when blocked) and the fact that `source` reports which tier was used. That cost/permission disclosure is exactly the context annotations cannot carry.

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 sentences, no waste: return shape first, then the cap plus escape hatch, then the fetch/cost model. Each sentence carries distinct information the agent needs.

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?

No output schema exists, and the description compensates by specifying the exact response shape and the meaning of `ok`, `source`, `content`/`error`. Combined with the disclosed billing model for the Bright Data tier, an agent has everything needed to call it correctly and predict cost.

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 60%; the description supplies meaning for the undocumented max_chars_per_url (each page is capped) and explains the `source` field in the response, which the schema does not cover. It does not add anything about `country`, `fresh`, or `format` beyond what the schema already documents.

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 (fetch), resource (up to 10 pages in parallel) and the exact return shape [{url, ok, source, content | error}], plus names the sibling scrape_as_markdown as the single-page alternative. An agent can distinguish it from scrape_as_markdown, scrape_as_html and extract without opening any 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 routes the agent to scrape_as_markdown when it needs to read past the per-page cap, which is a real selection criterion. It does not spell out when to prefer batch vs. the other siblings (scrape_as_html, extract), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is clear. The description adds the list of reported metrics, which is useful but overlaps with the output schema and does not disclose other behavioral traits (e.g., refresh cadence or whether the stats are real-time). With annotations covering safety, a 3 is appropriate.

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?

The description is a single, front-loaded sentence that enumerates the metrics efficiently. It is dense but not wasteful, though a brief introductory verb (e.g., 'Returns') would make it slightly more scannable.

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?

Given a zero-parameter read-only tool with an output schema and clear annotations, the description is sufficiently complete: it tells the agent what categories of data are available. It could be improved by specifying when to call it, but that is covered under usage guidelines.

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?

There are zero parameters, so the baseline is 4. The description adds no parameter semantics because none exist, but the schema is empty and needs no further explanation.

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 clearly indicates this tool returns session usage statistics, enumerating the specific metrics (calls, errors, latency, cost, budget, zone status, browser sessions). The resource and scope are identifiable, and the sibling tools (scraping/extraction) are unrelated, so no differentiation is needed.

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?

Usage is only implied: an agent would infer this is for checking session health and cost. There is no explicit when-to-use guidance, no mention of alternatives, and no exclusions. It is adequate but minimal.

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