fix(api): document search domain limits and clarify scrape parameter errors (#1388)

Stainless-Generated-From: f9386f8

Author: stlc-bot

src/context/dev/resources/web.py

@@ -373,18 +373,18 @@ def scrape(
 
           url: Public HTTP or HTTPS URL to scrape.
 
-          highlights_params: Required when `formats.highlights` is `true`.
+          highlights_params: Requires `formats.highlights: true`; required when it is set.
 
           image_params: Image options. Requires formats.images: true.
 
-          json_params: Required when formats.json is true.
+          json_params: Requires `formats.json: true`; required when it is set.
 
           markdown_params: Markdown options. Requires `formats.markdown`.
 
           max_age_ms: Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to
               3 days (259200000 ms). Maximum: 1 year (31536000000 ms).
 
-          parse_params: Required when formats.parse is true.
+          parse_params: Requires `formats.parse: true`; required when it is set.
 
           product_params: Product options. Requires formats.product: true.
 
@@ -1051,16 +1051,18 @@ def search(
           country: Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific
               country (maps to Google's `gl` parameter). Example: "us", "gb", "de".
 
-          exclude_domains: Blocklist — drop results from these domains. Example: ["pinterest.com",
-              "reddit.com"].
+          exclude_domains:
+              Blocklist — drop results from these domains. Up to 100 domains. Example:
+              ["pinterest.com", "reddit.com"].
 
           freshness: Restrict results to content published within this window.
 
           highlights_options: Passages from each result page that are relevant to the query. Pages are read
               with the `markdownOptions` settings.
 
-          include_domains: Allowlist — only return results from these domains. Example: ["arxiv.org",
-              "github.com"].
+          include_domains:
+              Allowlist — only return results from these domains. Up to 100 domains. Example:
+              ["arxiv.org", "github.com"].
 
           markdown_options: Inline Markdown scraping for each result. Set `enabled: true` to activate.
 
@@ -1779,18 +1781,18 @@ async def scrape(
 
           url: Public HTTP or HTTPS URL to scrape.
 
-          highlights_params: Required when `formats.highlights` is `true`.
+          highlights_params: Requires `formats.highlights: true`; required when it is set.
 
           image_params: Image options. Requires formats.images: true.
 
-          json_params: Required when formats.json is true.
+          json_params: Requires `formats.json: true`; required when it is set.
 
           markdown_params: Markdown options. Requires `formats.markdown`.
 
           max_age_ms: Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to
               3 days (259200000 ms). Maximum: 1 year (31536000000 ms).
 
-          parse_params: Required when formats.parse is true.
+          parse_params: Requires `formats.parse: true`; required when it is set.
 
           product_params: Product options. Requires formats.product: true.
 
@@ -2457,16 +2459,18 @@ async def search(
           country: Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific
               country (maps to Google's `gl` parameter). Example: "us", "gb", "de".
 
-          exclude_domains: Blocklist — drop results from these domains. Example: ["pinterest.com",
-              "reddit.com"].
+          exclude_domains:
+              Blocklist — drop results from these domains. Up to 100 domains. Example:
+              ["pinterest.com", "reddit.com"].
 
           freshness: Restrict results to content published within this window.
 
           highlights_options: Passages from each result page that are relevant to the query. Pages are read
               with the `markdownOptions` settings.
 
-          include_domains: Allowlist — only return results from these domains. Example: ["arxiv.org",
-              "github.com"].
+          include_domains:
+              Allowlist — only return results from these domains. Up to 100 domains. Example:
+              ["arxiv.org", "github.com"].
 
           markdown_options: Inline Markdown scraping for each result. Set `enabled: true` to activate.
 

src/context/dev/types/web_scrape_params.py

@@ -44,13 +44,13 @@ class WebScrapeParams(TypedDict, total=False):
     """Public HTTP or HTTPS URL to scrape."""
 
     highlights_params: Annotated[HighlightsParams, PropertyInfo(alias="highlightsParams")]
-    """Required when `formats.highlights` is `true`."""
+    """Requires `formats.highlights: true`; required when it is set."""
 
     image_params: Annotated[ImageParams, PropertyInfo(alias="imageParams")]
     """Image options. Requires formats.images: true."""
 
     json_params: Annotated[JsonParams, PropertyInfo(alias="jsonParams")]
-    """Required when formats.json is true."""
+    """Requires `formats.json: true`; required when it is set."""
 
     markdown_params: Annotated[MarkdownParams, PropertyInfo(alias="markdownParams")]
     """Markdown options. Requires `formats.markdown`."""
@@ -63,7 +63,7 @@ class WebScrapeParams(TypedDict, total=False):
     """
 
     parse_params: Annotated[ParseParams, PropertyInfo(alias="parseParams")]
-    """Required when formats.parse is true."""
+    """Requires `formats.parse: true`; required when it is set."""
 
     product_params: Annotated[ProductParams, PropertyInfo(alias="productParams")]
     """Product options. Requires formats.product: true."""
@@ -122,7 +122,7 @@ class Formats(TypedDict, total=False):
 
 
 class HighlightsParams(TypedDict, total=False):
-    """Required when `formats.highlights` is `true`."""
+    """Requires `formats.highlights: true`; required when it is set."""
 
     query: Required[str]
     """The question or topic to find passages for."""
@@ -142,10 +142,10 @@ class ImageParams(TypedDict, total=False):
 
 
 class JsonParams(TypedDict, total=False):
-    """Required when formats.json is true."""
+    """Requires `formats.json: true`; required when it is set."""
 
     schema: Required[Dict[str, object]]
-    """JSON Schema for a top-level object, up to 50 KB.
+    """JSON Schema (not an example object) for a top-level object, up to 50 KB.
 
     Use optional or nullable fields for missing facts.
     """
@@ -188,7 +188,7 @@ class ParseParamsRulesUnionMember1(TypedDict, total=False):
 
 
 class ParseParams(TypedDict, total=False):
-    """Required when formats.parse is true."""
+    """Requires `formats.parse: true`; required when it is set."""
 
     rules: Required[Dict[str, ParseParamsRules]]
     """Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects.

src/context/dev/types/web_search_params.py

@@ -274,7 +274,7 @@ class WebSearchParams(TypedDict, total=False):
     exclude_domains: Annotated[SequenceNotStr[str], PropertyInfo(alias="excludeDomains")]
     """Blocklist — drop results from these domains.
 
-    Example: ["pinterest.com", "reddit.com"].
+    Up to 100 domains. Example: ["pinterest.com", "reddit.com"].
     """
 
     freshness: Literal["last_24_hours", "last_week", "last_month", "last_year"]
@@ -289,7 +289,7 @@ class WebSearchParams(TypedDict, total=False):
     include_domains: Annotated[SequenceNotStr[str], PropertyInfo(alias="includeDomains")]
     """Allowlist — only return results from these domains.
 
-    Example: ["arxiv.org", "github.com"].
+    Up to 100 domains. Example: ["arxiv.org", "github.com"].
     """
 
     markdown_options: Annotated[MarkdownOptions, PropertyInfo(alias="markdownOptions")]