feat(capabilities): document verbs with descriptions and field docs

surfsense_backend/app/capabilities/web/scrape/definition.py

@@ -9,6 +9,12 @@ from app.capabilities.web.scrape.schemas import ScrapeInput, ScrapeOutput
 
 WEB_SCRAPE = Capability(
     name="web.scrape",
+    description=(
+        "Fetch one or more web pages and return their clean, readable content. "
+        "Give it the exact URLs to read (use web.discover first if you don't have "
+        "them). Returns one row per URL with a status (success/empty/failed), the "
+        "page content, and metadata such as title and description."
+    ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),

surfsense_backend/app/capabilities/web/scrape/schemas.py

@@ -11,8 +11,21 @@ MAX_SCRAPE_URLS = 20
 
 
 class ScrapeInput(BaseModel):
-    urls: list[str] = Field(min_length=1, max_length=MAX_SCRAPE_URLS)
-    max_length: int = 50_000
+    urls: list[str] = Field(
+        min_length=1,
+        max_length=MAX_SCRAPE_URLS,
+        description=(
+            "Full page URLs to fetch and read (1-20), each starting with "
+            "http:// or https://. Pass the exact URLs you want the content of."
+        ),
+    )
+    max_length: int = Field(
+        default=50_000,
+        description=(
+            "Maximum characters of cleaned content returned per page; "
+            "content longer than this is truncated."
+        ),
+    )
 
     @property
     def estimated_units(self) -> int:
@@ -21,15 +34,28 @@ class ScrapeInput(BaseModel):
 
 
 class ScrapeRow(BaseModel):
-    url: str
-    status: Literal["success", "empty", "failed"]
-    content: str | None = None
-    metadata: dict[str, str] | None = None
-    error: str | None = None
+    url: str = Field(description="The requested URL this result is for.")
+    status: Literal["success", "empty", "failed"] = Field(
+        description=(
+            "'success' = content returned; 'empty' = page reached but no "
+            "readable content; 'failed' = could not be fetched (see error)."
+        )
+    )
+    content: str | None = Field(
+        default=None, description="Cleaned, readable page text (present on success)."
+    )
+    metadata: dict[str, str] | None = Field(
+        default=None, description="Page metadata such as title and description."
+    )
+    error: str | None = Field(
+        default=None, description="Why the fetch failed (present on 'failed')."
+    )
 
 
 class ScrapeOutput(BaseModel):
-    rows: list[ScrapeRow]
+    rows: list[ScrapeRow] = Field(
+        description="One result per requested URL, in the same order."
+    )
 
     @property
     def billable_units(self) -> int: