mcp-scraper 0.2.19 → 0.2.21

package/docs/specs/mcp-tool-definition-quality-audit-spec.md

@@ -0,0 +1,1602 @@
+# MCP Tool Definition Quality Audit Spec
+
+Audit date: 2026-06-17
+
+Repo reviewed: `/Users/vilovieta/Desktop/mcp-scraper`
+
+Quality bar: the user's gold-standard MCP definition example, especially:
+
+- names must make tool choice obvious
+- descriptions must include what to use it for, the symptom/user phrasing that should trigger it, when not to use it, sibling tools, defaults, caps, cost, and recovery paths
+- parameters must act as micro-runbooks, not labels
+- parameter examples must silently teach exact accepted format, casing, units, and granularity
+- outputs must be structured, high-signal, bounded, and aligned with descriptions
+- responses must close the loop with resolved inputs, counts, cursors, truncation, diagnostics, and URLs
+- write-like tools must state side effects and use suitable annotations
+- every tool must stand alone because models often read one tool in isolation
+
+Additional context reviewed:
+
+- `/tmp/codex-remote-attachments/019ed213-92c4-7410-85f0-c616946ea57f/01E59EB1-700F-4535-9328-43B05F2A82AF/1-mcp-craft-vercel-linear-2026-06-17.pdf`
+- The PDF adds emphasis on symptom-language descriptions, examples as format specifications, token economics, task-shaped tools, and the one-tool-isolation litmus test.
+
+## Executive Verdict
+
+This MCP is operationally useful and has several strong tool definitions, especially `harvest_paa`, `maps_search`, `maps_place_intel`, `directory_workflow`, `credits_info`, and parts of the workflow layer.
+
+It is not yet gold-standard. The biggest issue is not one weak description. It is that the full MCP surface is hard to identify and inconsistent across local combined stdio, main stdio, Browser Agent stdio, and hosted HTTP. After manual review, I found 41 unique public tool names across all local and hosted surfaces, while repo docs and tests still refer to 13, 23, 24, and 39 in different places.
+
+There is also a systematic Browser Agent gap: Browser Agent returns JSON as text and registers no output schemas. That violates the "data as data" requirement across all 17 Browser Agent tools.
+
+## Surfaces Reviewed
+
+### Local MCP Scraper stdio
+
+Entrypoint:
+
+- `package.json` bin `mcp-scraper` -> `dist/bin/mcp-stdio-server.js`
+- source server: `src/mcp/paa-mcp-server.ts`
+- tool schemas: `src/mcp/mcp-tool-schemas.ts`
+- response formatting: `src/mcp/mcp-response-formatter.ts`
+
+Tool count found in source: 22.
+
+### Browser Agent stdio
+
+Entrypoint:
+
+- `package.json` bin `browser-agent` -> `dist/bin/browser-agent-stdio-server.js`
+- source server: `src/mcp/browser-agent-mcp-server.ts`
+- tool schemas: `src/mcp/browser-agent-tool-schemas.ts`
+
+Tool count found in source: 17.
+
+### Combined stdio
+
+Entrypoint:
+
+- `package.json` bin `mcp-scraper-combined` -> `dist/bin/mcp-scraper-combined-stdio-server.js`
+
+Tool count found in source: 39.
+
+### Hosted HTTP MCP
+
+Source executor:
+
+- `src/mcp/http-mcp-tool-executor.ts`
+
+Tool count found in source path: 24.
+
+The hosted surface appears to expose the main 22 tools plus 2 hosted-only SERP Intelligence capture tools.
+
+### Unique public tool names found
+
+I found 41 unique public tool names when including the local main tools, Browser Agent tools, and hosted-only capture tools.
+
+## Inventory Drift Finding
+
+Severity: P0
+
+The repo does not have one canonical MCP manifest that answers "what is the full MCP?" without reverse-engineering multiple files.
+
+Observed drift:
+
+- `README.md` says the hosted MCP exposes 21 web-intelligence/workflow tools plus 2 SERP Intelligence capture tools, for 23 total.
+- `tests/live/mcp/mcp-http-protocol.live.test.ts` expects 23 hosted tools.
+- `tests/live/mcp/mcp-stdio-protocol.live.test.ts` still refers to `ALL_13_TOOLS`.
+- `tests/unit/install-terminal.test.ts` references "39 MCP tools", which matches the local combined stdio surface.
+- Source review found 22 main stdio tools, 17 Browser Agent tools, 39 combined stdio tools, 24 hosted HTTP tools, and 41 unique local plus hosted names.
+
+What is wrong:
+
+- A developer, user, or LLM cannot easily identify the complete MCP surface.
+- Tests are not a reliable source of truth.
+- Docs are not a reliable source of truth.
+- Hosted and local surfaces are different, but the difference is not explicitly documented as a first-class contract.
+
+What is needed:
+
+- Add a canonical generated manifest, for example `docs/mcp-tool-manifest.generated.json`, produced from the same registration code used by the servers.
+- Split the manifest by surface:
+  - `main_stdio`
+  - `browser_agent_stdio`
+  - `combined_stdio`
+  - `hosted_http`
+  - `hosted_only`
+- Include name, description, input schema, output schema presence, annotations, formatter name, side effects, and sample prompts.
+- Include `symptomTriggers`, `formatExamples`, `negativeSpace`, `tokenBudgetClass`, and `producesHandlesFor` metadata.
+- Make tests assert against this generated manifest instead of hard-coded old counts.
+- Add a short human doc page that says exactly:
+  - local main MCP exposes 22 tools
+  - Browser Agent exposes 17 tools
+  - combined local MCP exposes 39 tools
+  - hosted HTTP exposes 24 tools
+  - 41 unique names exist across all public surfaces
+
+Why:
+
+For an MCP, tool discoverability is part of the product. If the operator cannot easily tell whether there are 13, 23, 24, 39, or 41 tools, model-side tool selection and human-side support will both degrade.
+
+## Global Findings
+
+### G1. Browser Agent returns JSON as text
+
+Severity: P0
+
+Evidence:
+
+- `src/mcp/browser-agent-mcp-server.ts` uses `textResult(value)` to return `JSON.stringify(value)` inside a text block.
+- No Browser Agent tool registration includes `outputSchema`.
+
+What is wrong:
+
+- The model receives escaped JSON as text instead of structured data.
+- Every Browser Agent tool requires ad hoc parsing by the model.
+- Tool outputs cannot be validated or reasoned about by schema-aware clients.
+
+What is needed:
+
+- Add output schemas for all Browser Agent tools.
+- Return `structuredContent` for every Browser Agent tool.
+- Keep human-readable text only as a compact summary, not the primary data surface.
+- For screenshot tools, return image content plus structured metadata.
+
+Why:
+
+The gold-standard requirement is explicit: do not return stringified JSON inside a text blob. Browser automation is perception-heavy; ambiguous string outputs create unnecessary failure modes.
+
+### G2. Several transcript and capture tools lack structured outputs
+
+Severity: P1
+
+Affected tools:
+
+- `youtube_transcribe`
+- `facebook_ad_transcribe`
+- `capture_serp_snapshot`
+- `capture_serp_page_snapshots`
+
+What is wrong:
+
+- These tools are high-value read tools, but their schema contracts are incomplete or absent.
+- Transcript output is one of the most reusable MCP results, but the structured content path is missing.
+- Capture tools intentionally skipped output schemas while payloads were evolving, but that leaves the model without a stable contract.
+
+What is needed:
+
+- Add stable envelopes even if nested payloads remain flexible:
+  - `source`
+  - `resolvedInput`
+  - `status`
+  - `transcript` or `captures`
+  - `summary`
+  - `artifact`
+  - `diagnostics`
+  - `errors`
+  - `schemaVersion`
+- Keep volatile provider payloads under a namespaced `raw` or `providerPayload` field.
+
+Why:
+
+A stable envelope lets the model perform reliable next steps even while internal payloads evolve.
+
+### G3. Some descriptions promise fields that structured outputs omit
+
+Severity: P1
+
+Examples:
+
+- `youtube_harvest` description promises dates and thumbnails, but the structured output omits them.
+- `facebook_page_intel` description promises ad copy and landing URLs, but the structured output omits primary ad text and landing URL/domain fields.
+- `extract_url` description promises markdown, metadata, Schema.org, media, visual styling, and downloads, but the structured output contains only a small summary.
+- `maps_place_intel` description promises reviews, hours, menus, attributes, categories, posts, photos, and historical snapshots, but the structured output only exposes a subset.
+
+What is wrong:
+
+- The model cannot trust the description as an output contract.
+- The user-facing text report may contain information that is invisible to schema-aware clients.
+
+What is needed:
+
+- For every promised output category, either add a compact structured field or remove the promise from the description.
+- Add `truncated` flags and counts where returning the full category would be too large.
+- Include artifact URLs or file paths when the full report contains more than the structured summary.
+
+Why:
+
+Gold-standard tool definitions align name, description, parameters, and return shape. Mismatches force the model to infer, parse prose, or make false assumptions.
+
+### G4. Too many generic workflow schemas
+
+Severity: P1
+
+Affected tools:
+
+- `workflow_run`
+- `workflow_step`
+- `workflow_status`
+- `workflow_artifact_read`
+
+What is wrong:
+
+- `workflow_run.input` is a broad `record(unknown)`.
+- Workflow outputs use broad records for artifacts, summaries, diagnostics, and status details.
+- The model gets good prose but weak schema boundaries.
+
+What is needed:
+
+- Add workflow-specific input contracts or a discriminated union keyed by workflow ID.
+- Add `resolvedWorkflow`, `expectedNextTool`, `requiredInputFields`, `missingFields`, and `artifactManifest` to outputs.
+- Add do-not-invent guards for run IDs, artifact IDs, and cursors.
+
+Why:
+
+Workflow orchestration is exactly where agents need the most guardrails. Prose alone is not enough.
+
+### G5. Proxy default documentation is stale
+
+Severity: P1
+
+What is wrong:
+
+- README guidance still describes US local SERP defaults as location-based, while current schema defaults for `harvest_paa` and `search_serp` are `configured`.
+- The user explicitly asked for API and MCP defaults to avoid setting proxy location except where needed, with Maps as the default-location exception. The tool schemas now mostly reflect that, but docs do not.
+
+What is needed:
+
+- Update README and any install/help text to say:
+  - default proxy mode is `configured` for general search/extract/social/video tools
+  - use explicit location only when the user asks for geographic SERP behavior
+  - Maps defaults to location-based proxying because Maps locality is intrinsic to the task
+- Add regression tests that inspect schema defaults.
+
+Why:
+
+Proxy behavior is part of the semantic contract. Stale docs cause wrong calls, wrong location assumptions, and worse search success.
+
+### G6. Missing sample prompts as first-class schema/docs content
+
+Severity: P2
+
+What is wrong:
+
+- Some descriptions include example request shapes inline.
+- There is no consistent `samplePrompts` catalog per tool.
+
+What is needed:
+
+- Add 2 to 3 sample prompts for every tool in the generated manifest.
+- Use realistic user phrasing, not internal API phrasing.
+- Keep examples short and tied to the tool's highest-value use cases.
+
+Why:
+
+Sample prompts are cheap few-shot routing hints. They improve model tool selection before parameters are even considered.
+
+### G7. Missing negative space in many tool descriptions
+
+Severity: P2
+
+What is wrong:
+
+Strong tools name sibling tools. Weak tools do not tell the model when not to use them.
+
+What is needed:
+
+Every description should include one or two sentences of negative space:
+
+- use `extract_url` for one page, `map_site_urls` before crawling a site, `extract_site` after selecting URLs
+- use `youtube_harvest` to discover videos, `youtube_transcribe` once you have one video ID or URL
+- use `facebook_ad_search` to find advertisers, `facebook_page_intel` to inspect one advertiser, `facebook_ad_transcribe` or `facebook_video_transcribe` when video/audio text is needed
+- use `browser_screenshot` or `browser_read` before clicking if the target is not known
+
+Why:
+
+Most model tool mistakes are tool-selection mistakes, not syntax mistakes.
+
+### G8. File-writing side effects are under-annotated
+
+Severity: P2
+
+Affected examples:
+
+- `browser_replay_download`
+- `browser_replay_annotate`
+- `extract_url` when screenshots or media downloads are enabled
+- possibly report-saving formatter behavior
+
+What is wrong:
+
+- Several tools can write local files while still being marked read-only or described mainly as read tools.
+
+What is needed:
+
+- Descriptions should state local file side effects.
+- Annotations should distinguish external service mutations from local filesystem writes.
+- Output schemas should return `artifactPath`, `artifactUrl`, `mimeType`, and `bytes` where applicable.
+
+Why:
+
+The user should not be surprised by files written to disk, and the model needs handles for follow-up work.
+
+### G9. Descriptions often name functions, not user symptoms
+
+Severity: P2
+
+What is wrong:
+
+- Stronger descriptions explain the user problem that should trigger the tool, not only the API function.
+- Several tools still read like implementation labels:
+  - `browser_goto`: navigate to a URL
+  - `browser_click`: click something
+  - `youtube_transcribe`: transcribe a video
+  - `workflow_status`: get status
+- The model rarely thinks in those labels. It thinks "the page changed", "I need the transcript", "the workflow may still be running", or "I need to inspect the current screen."
+
+What is needed:
+
+- Add `symptomTriggers` to each manifest entry.
+- Rewrite thin descriptions to include user-language triggers:
+  - "Use this when the user says the page failed to load, asks you to go to another URL, or you need to continue in an existing browser session."
+  - "Use this when the user asks what was said in a YouTube video or asks for claims, offers, or lessons from a video."
+  - "Use this when you started a workflow and need to know whether to poll, read an artifact, or report a failure."
+
+Why:
+
+The Vercel teardown point is direct: models route from the user's symptom, not the internal function name. Symptom phrasing raises first-call selection accuracy.
+
+### G10. Parameter examples do not consistently teach exact format
+
+Severity: P2
+
+What is wrong:
+
+- Some parameters have examples, but the style is inconsistent.
+- Format examples are missing for many fields where exact shape matters:
+  - YouTube video URL versus video ID
+  - Facebook page ID, ad archive ID, and video URL
+  - browser key combinations
+  - workflow IDs and artifact IDs
+  - country and language codes
+  - proxy modes and location strings
+
+What is needed:
+
+- Every parameter where the model could format incorrectly should include one concrete example in the accepted shape.
+- Examples should encode exact casing, separators, ID prefixes, URL shape, units, and granularity.
+- If aliases are accepted, examples should show both strict and human-friendly forms.
+
+Why:
+
+Models mimic examples. A parameter description without a concrete example leaves casing, units, and granularity to chance.
+
+### G11. The tool surface needs token-economics governance
+
+Severity: P2
+
+What is wrong:
+
+- The MCP has grown to 39 combined local tools and 41 unique public names across all surfaces.
+- The repo lacks a declared policy for when to add a new tool versus extend an existing task-shaped tool.
+- Tool definitions are paid as context rent before any work begins.
+
+What is needed:
+
+- Add `tokenBudgetClass` to the manifest:
+  - `core`: high-frequency tools worth detailed descriptions
+  - `specialized`: lower-frequency tools that still need complete runbooks
+  - `hosted_only`: tools exposed only on hosted HTTP
+  - `internal_or_legacy`: tools that should not be prominent in docs
+- Add a tool-addition rule:
+  - add a tool only when it represents a recurring user task that existing tools cannot serve cleanly
+  - otherwise improve the existing tool's parameters, negative space, or output schema
+- Add an audit command that totals tool-description token cost by surface.
+
+Why:
+
+The PDF's token-economics point matters here because the surface is already large and hard to identify. A bigger MCP is only better if each added tool improves task routing more than it costs in always-loaded context.
+
+### G12. The one-tool-isolation litmus test is not enforced
+
+Severity: P2
+
+What is wrong:
+
+- Some shared concepts are explained well in one tool but not repeated in related tools.
+- Examples:
+  - Browser session ID guidance is repeated in schemas, but the action tools still lack full recovery and do-not-guess guidance.
+  - Proxy default behavior is clearer in schemas than in docs.
+  - Facebook discovery paths are implicit across several tools rather than repeated in each tool that needs them.
+
+What is needed:
+
+- Add a testable lint rule for tool descriptions:
+  - if a parameter accepts an opaque handle, the description must say where to get it
+  - if a tool overlaps with a sibling, the description must name that sibling
+  - if a parameter has an enum, the description must include the enum values
+  - if a parameter has a default, the description must state the default
+- Treat repetition as correct, not redundant.
+
+Why:
+
+Models often evaluate one tool at a time. A tool description that depends on remembering another tool's docs is not self-contained enough.
+
+## Tool-by-Tool Spec
+
+Priority scale:
+
+- P0: Blocks reliable discovery or structured use.
+- P1: Major model failure risk or contract mismatch.
+- P2: Important improvement for routing, recovery, or boundedness.
+- P3: Polish, consistency, or docs quality.
+
+### 1. `harvest_paa`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong.
+
+What is wrong:
+
+- Description is one of the best in the MCP, but structured output does not fully close the loop.
+- PAA questions omit source URL/citation-level fields.
+- Description mentions local pack data when present, but the output schema does not expose a dedicated local pack object.
+- No explicit `resolvedInputs` object with proxy mode, requested location, resolved location, query, and cap.
+- No consistent `truncated` or `hitLimit` signal when `maxQuestions` is reached.
+
+Needed spec:
+
+- Add `resolvedInputs`.
+- Add `questions[].sourceUrl`, `questions[].sourceTitle`, `questions[].sourceSite`, and optional `questions[].answerExcerpt`.
+- Add `localPack` or remove local-pack language from the description.
+- Add `count`, `requestedMaxQuestions`, `truncated`, and `artifact`.
+- Keep `proxyMode` default documented as `configured`.
+
+Why:
+
+This is a high-traffic search tool. It should be the reference implementation for structured search output.
+
+### 2. `search_serp`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong input schema, useful output.
+
+What is wrong:
+
+- Local pack structured entries are too thin for follow-up actions.
+- Missing consistent `resolvedInputs`.
+- Missing `truncated` or page/cap completion signal.
+- Search diagnostics are not consistently structured unless debug paths are used.
+
+Needed spec:
+
+- Add `resolvedInputs` with query, search type, language, country, location, proxy mode, requested pages, and result caps.
+- Expand local pack entries with address, phone, place URL, website URL, CID/place ID where available.
+- Add `resultCounts` by block type: organic, local, ads, aiOverview, peopleAlsoAsk.
+- Add `truncated`, `pagesFetched`, `nextRecommendedTool`, and `diagnostics`.
+
+Why:
+
+SERP outputs are branching points. The model needs enough structured detail to choose between extraction, Maps lookup, or another SERP pass.
+
+### 3. `extract_url`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: useful, but output contract is underbuilt.
+
+What is wrong:
+
+- Description promises markdown, metadata, Schema.org blocks, media, visual styling, screenshots, and downloads.
+- Structured output exposes only a compact summary and omits most promised categories.
+- `allowLocal` is documented, but the tool can also write screenshots/media locally and that side effect is not prominent enough.
+- No structured `truncated` or `artifact` handle for the full extraction.
+
+Needed spec:
+
+- Add structured fields:
+  - `url`, `finalUrl`, `statusCode`, `title`, `description`, `canonicalUrl`
+  - `bodyMarkdown`, `bodyTextExcerpt`, `wordCount`, `headings`
+  - `schemaOrg`
+  - `links`
+  - `images`, `video`, `mediaAssets`
+  - `styles`, `colors`, `fonts`
+  - `screenshot`
+  - `downloads`
+  - `artifact`
+  - `truncated`
+- State clearly when to use `map_site_urls` and `extract_site` instead.
+- Add sample prompts for page extraction, competitor page capture, and visual asset extraction.
+
+Why:
+
+This is a core research primitive. If the report has the data but structured output hides it, downstream agents cannot reliably use it.
+
+### 4. `map_site_urls`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: good.
+
+What is wrong:
+
+- It is named as a mapping tool, but the description could better distinguish discovery from extraction.
+- `maxUrls` lacks a strong default/cap explanation in the schema.
+- Output has `truncated`, but not enough explanation of excluded URLs or crawl boundaries.
+
+Needed spec:
+
+- Add description sentence: "Use this before `extract_site` when you need to choose pages; use `extract_url` for a single known URL."
+- Add `resolvedInputs` with start URL, final URL, same-domain policy, limit, depth, and exclusions.
+- Add `excludedCounts` by reason, such as off-domain, duplicate, unsupported scheme, blocked, too deep.
+- Add sample prompts for sitemap discovery, competitor page inventory, and choosing pages for extraction.
+
+Why:
+
+URL mapping is a planning tool. The output should explain what it did not include as much as what it did include.
+
+### 5. `extract_site`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: useful but underspecified.
+
+What is wrong:
+
+- The structured output is too small for site-level extraction.
+- Description does not fully explain how it relates to `map_site_urls`.
+- Output lacks per-page status, word counts, canonical URLs, extraction errors, and truncation detail.
+
+Needed spec:
+
+- Add `resolvedInputs` and `crawlPlan`.
+- Return `pages[]` with URL, final URL, title, status, word count, schema types, headings, canonical URL, and artifact references.
+- Add `failedPages[]` with errors.
+- Add `truncated`, `pagesRequested`, `pagesExtracted`, and `nextRecommendedTool`.
+- Add examples for "extract these selected URLs" and "crawl a small site".
+
+Why:
+
+Site extraction should create a reliable corpus manifest, not just a prose report.
+
+### 6. `youtube_harvest`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium.
+
+What is wrong:
+
+- Description promises titles, views, dates, durations, URLs, thumbnails, and video IDs.
+- Structured output omits publish dates and thumbnails.
+- `maxVideos` allows up to 500 without a clear cost/size warning.
+- Description should more clearly point to `youtube_transcribe` for one selected video.
+
+Needed spec:
+
+- Add `videos[].publishedAt`, `videos[].thumbnailUrl`, `videos[].channelUrl`, and `videos[].descriptionExcerpt`.
+- Add `requestedMaxVideos`, `returnedCount`, `truncated`, and `resolvedInputs`.
+- State that broad channel/search harvests can be large and should use narrower queries or smaller limits.
+- Add negative space: use `youtube_transcribe` for transcript extraction after selecting a video.
+
+Why:
+
+Harvest is a discovery tool. Missing dates and thumbnails reduce ranking and selection quality.
+
+### 7. `youtube_transcribe`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: weak relative to importance.
+
+What is wrong:
+
+- No output schema.
+- No `structuredContent`.
+- Formatter returns one text block.
+- Input schema only accepts `videoId`, while the description says the model can infer from a URL if the user provided one.
+- No structured transcript metadata such as language, duration, source URL, word count, or chunk count.
+
+Needed spec:
+
+- Accept `videoId` or `url` explicitly.
+- Add recovery text: "If the user gave a YouTube URL, pass it as `url`; do not manually strip parameters unless needed."
+- Add output schema:
+  - `videoId`
+  - `url`
+  - `title`
+  - `channelName`
+  - `duration`
+  - `language`
+  - `transcript`
+  - `segments`
+  - `wordCount`
+  - `artifact`
+  - `resolvedInputs`
+  - `errors`
+- Add `truncated` if transcript text is capped in content.
+
+Why:
+
+Transcripts are often reused for summaries, quotes, outlines, and extraction. Text-only JSON/report output is not enough.
+
+### 8. `facebook_page_intel`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium-low.
+
+What is wrong:
+
+- Several parameter descriptions are labels rather than runbooks.
+- `pageId`, `libraryId`, `country`, and `maxAds` need clearer accepted formats and recovery paths.
+- Description promises page metadata, ad copy, landing URLs, media, and Page Transparency.
+- Structured output omits important ad copy and landing URL fields.
+
+Needed spec:
+
+- Add parameter runbooks:
+  - `pageId`: explain numeric page ID and how to get it from `facebook_ad_search`
+  - `libraryId`: explain ad library ID and when to use it
+  - `country`: include ISO examples and default
+  - `maxAds`: default, max, and filtering advice
+- Add output fields:
+  - `page`
+  - `transparency`
+  - `ads[].libraryId`
+  - `ads[].primaryText`
+  - `ads[].headline`
+  - `ads[].cta`
+  - `ads[].landingUrl`
+  - `ads[].domain`
+  - `ads[].media`
+  - `ads[].startedAt`
+  - `ads[].isActive`
+  - `resolvedInputs`
+  - `truncated`
+- Add negative space: use `facebook_ad_search` when you do not know the page; use transcript tools for video text.
+
+Why:
+
+Facebook workflows are ID-heavy. The tool must teach discovery and provide enough structured ad data for competitive research.
+
+### 9. `facebook_ad_search`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium.
+
+What is wrong:
+
+- `country` and `maxResults` descriptions are too thin.
+- Output does not fully close the loop for the next tool call.
+- Description should name `facebook_page_intel` as the next step more explicitly.
+
+Needed spec:
+
+- Add parameter descriptions with defaults, examples, cap, and country behavior.
+- Return `pages[]` with page ID, page name, page URL, matched ad library IDs, active ad count, country, and confidence.
+- Add `nextRecommendedTool` with ready-to-pass args for `facebook_page_intel`.
+- Add `resolvedInputs`, `count`, and `truncated`.
+
+Why:
+
+This is a discovery tool. Its main job is to produce correct handles for page-level inspection.
+
+### 10. `facebook_ad_transcribe`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: weak.
+
+What is wrong:
+
+- No output schema.
+- No `structuredContent`.
+- Formatter returns only text.
+- The input schema is decent, but it should clarify accepted URL forms and what to do if the user only has a library ID.
+
+Needed spec:
+
+- Add output schema:
+  - `adArchiveId`
+  - `adUrl`
+  - `videoUrl`
+  - `transcript`
+  - `segments`
+  - `language`
+  - `duration`
+  - `wordCount`
+  - `artifact`
+  - `resolvedInputs`
+  - `errors`
+- Add negative space: use `facebook_page_intel` first if the user has only an advertiser or page.
+- Add sample prompts for transcribing one Facebook ad, extracting claims, and comparing ad angles.
+
+Why:
+
+Ad transcription is a high-value competitive-intelligence output. It should be directly machine-readable.
+
+### 11. `facebook_video_transcribe`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong relative to neighboring Facebook tools.
+
+What is wrong:
+
+- Output schema is present, but it could expose more download and media-selection detail.
+- Quality fallback behavior should be reflected in `resolvedInputs`.
+- The description should make clearer when to choose this over `facebook_ad_transcribe`.
+
+Needed spec:
+
+- Add `resolvedInputs` with requested quality, selected quality, and whether fallback occurred.
+- Add `media` with source URL, downloaded bytes, mime type, and extraction method.
+- Add negative space: use this for organic Facebook videos; use `facebook_ad_transcribe` for Ads Library creatives.
+- Add `truncated` and `artifact`.
+
+Why:
+
+Video transcription depends on media resolution and fallback behavior. The model should know which asset was actually transcribed.
+
+### 12. `maps_place_intel`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong.
+
+What is wrong:
+
+- Description promises reviews, hours, menus, attributes, categories, posts, photos, and historical snapshots.
+- Structured output exposes some but not all of those categories.
+- Review output is too summary-oriented for tasks that need exact review evidence.
+- No explicit `resolvedInputs` object.
+
+Needed spec:
+
+- Add `resolvedInputs` with place ID, Maps URL, query, location, and selected place.
+- Add compact structured fields for:
+  - reviews
+  - reviewHistogram
+  - hours
+  - attributes
+  - serviceOptions
+  - categories
+  - posts
+  - photos
+  - menu
+  - historicalSnapshots
+- Include counts and `truncated` per section.
+- Add `artifact` for the full report.
+
+Why:
+
+Maps intelligence is one of the highest-value tools. It should preserve evidence, not only conclusions.
+
+### 13. `maps_search`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong.
+
+What is wrong:
+
+- This is correctly treated as a default-location tool, but that exception should be documented consistently.
+- Output could better indicate cap hits and next steps.
+- The tool does not use pagination, so limit handling must be explicit.
+
+Needed spec:
+
+- Add `resolvedInputs` with query, requested location, proxy mode, resolved proxy, and limit.
+- Add `truncated` when result count reaches the requested max.
+- Add `nextRecommendedTool` with ready-to-pass `maps_place_intel` args for top candidates.
+- Add sample prompts for local competitor lookup, category search, and place discovery.
+
+Why:
+
+Maps search is inherently location-sensitive. It is the right exception to the no-default-location proxy policy, but it needs to say so everywhere.
+
+### 14. `directory_workflow`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong but dense.
+
+What is wrong:
+
+- Description is useful but long.
+- Output is strong, but per-city partial failures and cap hits should be more explicit.
+- Credit/cost expectations are not as explicit as they are in `harvest_paa`.
+
+Needed spec:
+
+- Add `estimatedCredits` or a cost note in the description.
+- Add `cities[]` fields for requested ZIP/city, resolved city, attempt count, status, result count, and errors.
+- Add `failedCityCount`, `partial`, and `truncated`.
+- Add negative space: use `maps_search` for one city/category; use this for scaled directory builds.
+
+Why:
+
+Directory workflows can be expensive and multi-step. The model needs clear partial-success handling.
+
+### 15. `workflow_list`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: good.
+
+What is wrong:
+
+- It is a list tool, but this is acceptable because it lists available workflows rather than user data.
+- Description could better name the follow-up path.
+- Sample prompts are missing.
+
+Needed spec:
+
+- Add sample prompts for "what workflows are available" and "show workflows for local SEO."
+- Return `workflows[]` with ID, title, goal, required inputs, estimated cost, expected duration, and next tool.
+- Add `nextRecommendedTool: workflow_suggest` or `workflow_run` depending on context.
+
+Why:
+
+Workflow discovery should quickly transition into either suggestion or execution.
+
+### 16. `workflow_suggest`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: good.
+
+What is wrong:
+
+- Suggestions need stronger confidence/rationale fields.
+- Input goal is free-text without examples or supported workflow categories.
+
+Needed spec:
+
+- Add input examples for local SEO, competitor research, PAA harvesting, SERP capture, and directory building.
+- Return `suggestions[]` with workflow ID, confidence, why, required inputs, missing inputs, estimated cost, and ready-to-run args.
+- Add negative space: use `workflow_list` if the user simply asks what exists.
+
+Why:
+
+Suggestion tools must make the next call easy and must expose why a workflow was selected.
+
+### 17. `workflow_run`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium.
+
+What is wrong:
+
+- `input` is an unrestricted record.
+- The description has examples, but the schema does not enforce workflow-specific required fields.
+- There is no `idempotencyKey`, even though workflow starts can be retried.
+- Cost and duration expectations are not consistently explicit.
+
+Needed spec:
+
+- Add workflow-specific schemas or a discriminated union keyed by `workflowId`.
+- Add `idempotencyKey` to prevent duplicate workflow runs on retry.
+- Add `dryRun` or `validateOnly` if feasible.
+- Return `runId`, `status`, `createdAt`, `estimatedCost`, `estimatedDuration`, `artifactManifest`, and `nextRecommendedTool`.
+- Include do-not-invent guidance for workflow IDs.
+
+Why:
+
+This is the main write-like orchestration tool. It needs write-side guardrails even if it only writes internal job state.
+
+### 18. `workflow_step`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium.
+
+What is wrong:
+
+- Requires a valid run ID, but the parameter description should explicitly say not to invent it.
+- Output should better distinguish completed, waiting, failed, and still-running states.
+
+Needed spec:
+
+- Add parameter text: "Use only a `runId` returned by `workflow_run`, `workflow_status`, or a prior workflow tool response."
+- Add output fields:
+  - `runId`
+  - `currentStep`
+  - `status`
+  - `completedSteps`
+  - `remainingSteps`
+  - `nextPollAfterMs`
+  - `nextRecommendedTool`
+  - `errors`
+
+Why:
+
+Step tools are recovery tools. They should tell the model exactly whether to poll, read an artifact, or ask the user.
+
+### 19. `workflow_status`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium.
+
+What is wrong:
+
+- Similar run-ID hallucination risk as `workflow_step`.
+- Output status needs a closed enum and next action.
+
+Needed spec:
+
+- Add do-not-invent run-ID guard.
+- Add status enum: `queued`, `running`, `waiting`, `completed`, `failed`, `canceled`.
+- Add `terminal`, `nextPollAfterMs`, `artifactManifest`, and `nextRecommendedTool`.
+
+Why:
+
+Status tools should prevent model-side uncertainty about whether work is done.
+
+### 20. `workflow_artifact_read`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: medium-good.
+
+What is wrong:
+
+- Artifact IDs need a do-not-invent guard.
+- Large artifact reading needs clearer continuation semantics.
+- Output should expose artifact metadata more explicitly.
+
+Needed spec:
+
+- Add parameter text: "Use only artifact IDs returned by workflow status/run/step responses."
+- Add `cursor` or `offset` continuation if artifacts can be large.
+- Return `artifactId`, `runId`, `name`, `mimeType`, `bytes`, `downloadUrl` or local path, `content`, `truncated`, and `nextCursor`.
+
+Why:
+
+Artifacts are the durable output of workflows. They need stable handles and pagination.
+
+### 21. `rank_tracker_blueprint`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: good.
+
+What is wrong:
+
+- The output is planning-heavy and may include large prompt-like content.
+- Description should make explicit that this is a planning/blueprint tool, not a live rank tracker.
+- Sample prompts are missing.
+
+Needed spec:
+
+- Add `blueprintVersion`.
+- Add `implementationSteps[]`, `schema`, `schedule`, `metrics`, `dataSources`, and `limitations`.
+- Add negative space: use `search_serp` or capture tools for live SERP data.
+- Add sample prompts for building a tracker, designing a local SEO tracker, and estimating data needs.
+
+Why:
+
+The tool name is clear, but the return should be easier to consume as a structured build plan.
+
+### 22. `credits_info`
+
+Surface: main stdio, combined stdio, hosted HTTP.
+
+Current quality: strong.
+
+What is wrong:
+
+- This is close to gold-standard, but could expose upgrade/top-up paths more explicitly.
+- The description should mention when to call it before expensive workflows.
+
+Needed spec:
+
+- Add `billingUrl` or `topUpUrl` if available.
+- Add `concurrency`, `plan`, `remainingCredits`, `resetAt`, and `recommendedAction`.
+- Add description sentence: "Use this before large harvests or workflows when credit availability matters."
+
+Why:
+
+This is a safety and planning tool. It should help the model avoid starting work that cannot complete.
+
+### 23. `browser_open`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: good description, weak output contract.
+
+What is wrong:
+
+- No output schema.
+- Returns JSON text.
+- Parameter descriptions do not explain default proxy behavior.
+- It can create a billable session but does not return a typed session envelope.
+
+Needed spec:
+
+- Add output schema with:
+  - `sessionId`
+  - `watchUrl`
+  - `url`
+  - `proxy`
+  - `profile`
+  - `status`
+  - `screenshot`
+  - `createdAt`
+  - `expiresAt`
+  - `billing`
+- Return structuredContent.
+- Add parameter guidance for proxy/location defaults and when to use a persistent profile.
+
+Why:
+
+This tool creates the browser session used by every other Browser Agent tool. Its output must be a reliable handle.
+
+### 24. `browser_screenshot`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: good concept, weak contract.
+
+What is wrong:
+
+- No output schema.
+- Output mixes image content with JSON text.
+- Element metadata is not contractually described.
+
+Needed spec:
+
+- Add output schema with:
+  - `sessionId`
+  - `url`
+  - `title`
+  - `screenshot`
+  - `viewport`
+  - `elements[]`
+  - `timestamp`
+- Return image content plus structuredContent.
+- Add guidance to use this before click/type when target location is uncertain.
+
+Why:
+
+This is the primary visual perception tool. It must give the model stable references for interaction.
+
+### 25. `browser_read`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: useful, weak contract.
+
+What is wrong:
+
+- No output schema.
+- Description does not explain how it differs from screenshot.
+- Returns JSON text.
+
+Needed spec:
+
+- Add output schema with `sessionId`, `url`, `title`, `text`, `links`, `forms`, `buttons`, `headings`, `truncated`.
+- Add description: use this for DOM text; use `browser_screenshot` for visual layout or CAPTCHA.
+
+Why:
+
+DOM reading and visual perception are different. The model should choose the right one.
+
+### 26. `browser_locate`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium.
+
+What is wrong:
+
+- No output schema.
+- Needs clearer recovery guidance when the target is not found.
+- Returns JSON text.
+
+Needed spec:
+
+- Add output schema with matches, confidence, bounding boxes, selectors, labels, and suggested next action.
+- Add parameter examples for natural language targets.
+- Add description: use this before `browser_click` when a user describes an element but coordinates are unknown.
+
+Why:
+
+Locate is a bridge from language to UI action. It should return click-ready references.
+
+### 27. `browser_goto`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: thin.
+
+What is wrong:
+
+- No output schema.
+- Description is too short for a navigation tool.
+- Missing guidance for redirects, login walls, and follow-up screenshot/read.
+
+Needed spec:
+
+- Add output schema with `sessionId`, `requestedUrl`, `finalUrl`, `status`, `title`, `redirects`, `blocked`, `captchaDetected`, and `nextRecommendedTool`.
+- Add description: use an existing session ID from `browser_open`; call `browser_screenshot` after navigation if visual state matters.
+
+Why:
+
+Navigation often changes state in ways the model must inspect before acting.
+
+### 28. `browser_click`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: thin.
+
+What is wrong:
+
+- No output schema.
+- Needs stronger "do not guess coordinates" guidance.
+- Description does not explain preferred selector/element-reference path.
+
+Needed spec:
+
+- Add parameter guidance: prefer a selector or located element reference; use coordinates only from a recent screenshot/locate result.
+- Add output schema with clicked target, navigation/change detection, URL before/after, and suggested next tool.
+- Add errors with recovery suggestions.
+
+Why:
+
+Click mistakes are costly in browser automation. The tool should bias toward grounded actions.
+
+### 29. `browser_type`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: thin.
+
+What is wrong:
+
+- No output schema.
+- Needs clearer guidance on target selection and sensitive text.
+- Description does not say whether it clears existing content or appends.
+
+Needed spec:
+
+- Add parameter `clearFirst` if supported, or describe current behavior.
+- Add output schema with target, text length, URL, focused element, and errors.
+- Add guidance to locate or click the field first if target is ambiguous.
+
+Why:
+
+Typing into the wrong field is a common browser-agent failure.
+
+### 30. `browser_scroll`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: thin.
+
+What is wrong:
+
+- No output schema.
+- Direction/amount semantics need examples.
+- Output should state resulting scroll position.
+
+Needed spec:
+
+- Add output schema with direction, amount, page position, reachedTop, reachedBottom, and nextRecommendedTool.
+- Add parameter examples such as `down 800` or `to bottom` if supported.
+
+Why:
+
+Scrolling is perception setup. The model needs to know whether it reached the desired region.
+
+### 31. `browser_press`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: thin.
+
+What is wrong:
+
+- No output schema.
+- Key names and combinations need examples.
+- Output should indicate focus and page changes.
+
+Needed spec:
+
+- Add parameter examples: `Enter`, `Escape`, `Tab`, `Meta+L`, `ArrowDown`.
+- Add output schema with key, focused element, URL before/after, navigation detected, and errors.
+
+Why:
+
+Keyboard automation is brittle unless accepted key syntax is explicit.
+
+### 32. `browser_replay_start`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium.
+
+What is wrong:
+
+- No output schema.
+- Description should explain the relationship between session ID and replay ID.
+
+Needed spec:
+
+- Add output schema with `sessionId`, `replayId`, `startedAt`, `status`, and `artifact`.
+- Add do-not-invent guard for session IDs.
+
+Why:
+
+Replay tools create handles used by later tools. Those handles must be structured.
+
+### 33. `browser_replay_stop`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium.
+
+What is wrong:
+
+- No output schema.
+- Needs clearer next-step guidance for downloading or annotating replay.
+
+Needed spec:
+
+- Add output schema with `sessionId`, `replayId`, `stoppedAt`, `durationMs`, `status`, and `nextRecommendedTool`.
+
+Why:
+
+Stopping a replay should naturally hand off to list/download/annotate.
+
+### 34. `browser_list_replays`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium.
+
+What is wrong:
+
+- No output schema.
+- It is a list tool, but acceptable because it lists session artifacts.
+- Output should be paginated or capped.
+
+Needed spec:
+
+- Add output schema with `replays[]`, `count`, `nextCursor`, and `resolvedInputs`.
+- Add parameter cursor if replay history can grow.
+
+Why:
+
+Replay lists can grow over time and should not flood context.
+
+### 35. `browser_replay_download`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium-low.
+
+What is wrong:
+
+- No output schema.
+- This writes a local file but is annotated like a read tool.
+- Description should state destination behavior and file type.
+
+Needed spec:
+
+- Add output schema with `replayId`, `filePath`, `mimeType`, `bytes`, `downloadedAt`, and `sourceUrl`.
+- State local filesystem side effect in the description.
+- Revisit annotations to indicate local write behavior.
+
+Why:
+
+Downloaded replay artifacts need stable paths for follow-up analysis.
+
+### 36. `browser_replay_mark`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium-good.
+
+What is wrong:
+
+- No output schema.
+- Annotation semantics need to say whether the mark mutates remote replay metadata, local metadata, or only the current session.
+
+Needed spec:
+
+- Add output schema with `replayId`, `markId`, `timestampMs`, `label`, `createdAt`, and `scope`.
+- Add side-effect description.
+
+Why:
+
+Marks are workflow state. The model needs to know where that state lives.
+
+### 37. `browser_replay_annotate`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium-good parameters, weak side-effect contract.
+
+What is wrong:
+
+- No output schema.
+- This may write annotated artifacts locally, but side effects are not strongly annotated.
+- Description should clarify expected input file/path and output artifact.
+
+Needed spec:
+
+- Add output schema with `replayId`, `inputPath`, `outputPath`, `annotations`, `bytes`, `mimeType`, and `createdAt`.
+- State local file write behavior.
+- Revisit read-only annotations.
+
+Why:
+
+Annotated replay artifacts are files the user will want to open or attach elsewhere.
+
+### 38. `browser_close`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: decent.
+
+What is wrong:
+
+- No output schema.
+- It is correctly destructive, but output should prove the session is closed.
+
+Needed spec:
+
+- Add output schema with `sessionId`, `closed`, `closedAt`, `durationMs`, and `billingStopped`.
+
+Why:
+
+Closing sessions is part of cost control. The model should get an unambiguous success signal.
+
+### 39. `browser_list_sessions`
+
+Surface: Browser Agent stdio, combined stdio.
+
+Current quality: medium.
+
+What is wrong:
+
+- No output schema.
+- Needs cap/pagination if many sessions exist.
+- Could better distinguish active, idle, closing, and closed sessions.
+
+Needed spec:
+
+- Add output schema with `sessions[]`, `count`, `nextCursor`, and status enum.
+- Include `sessionId`, `url`, `createdAt`, `lastActivityAt`, `status`, `watchUrl`, and billing state.
+
+Why:
+
+Session listing is a recovery tool. It should help the model reuse or close the right session.
+
+### 40. `capture_serp_snapshot`
+
+Surface: hosted HTTP only.
+
+Current quality: strong input schema, weak output contract.
+
+What is wrong:
+
+- Output schema was deliberately deferred while payloads evolved.
+- Current contract does not expose a stable, gold-standard return surface.
+- No formatter-specific high-signal summary.
+
+Needed spec:
+
+- Add a stable output envelope:
+  - `schemaVersion`
+  - `snapshotId`
+  - `query`
+  - `resolvedInputs`
+  - `status`
+  - `capturedAt`
+  - `blocks`
+  - `organic`
+  - `localPack`
+  - `aiOverview`
+  - `citations`
+  - `artifacts`
+  - `diagnostics`
+  - `providerPayload`
+- Keep volatile provider fields inside `providerPayload`.
+- Add `truncated` and `errors`.
+
+Why:
+
+Hosted capture is a premium research surface. Even evolving payloads need a stable summary contract.
+
+### 41. `capture_serp_page_snapshots`
+
+Surface: hosted HTTP only.
+
+Current quality: strong input schema, weak output contract.
+
+What is wrong:
+
+- No output schema.
+- No stable structured summary of per-page capture status.
+- Target handling is strong on input but not mirrored on output.
+
+Needed spec:
+
+- Add output schema:
+  - `schemaVersion`
+  - `snapshotId`
+  - `resolvedInputs`
+  - `captures[]`
+  - `captures[].url`
+  - `captures[].sourceKind`
+  - `captures[].status`
+  - `captures[].title`
+  - `captures[].screenshot`
+  - `captures[].htmlArtifact`
+  - `captures[].textArtifact`
+  - `captures[].error`
+  - `count`
+  - `failedCount`
+  - `truncated`
+- Add formatter that summarizes successes and failures.
+
+Why:
+
+Page snapshot capture often feeds downstream audits. The model needs exact URLs, statuses, and artifacts.
+
+## Required Remediation Plan
+
+### Phase 1: Make the MCP surface knowable
+
+Priority: P0
+
+Deliverables:
+
+- Generated manifest for all surfaces.
+- Tests generated from manifest or asserting manifest consistency.
+- README section with exact surface counts and hosted/local differences.
+- CI check that fails when a registered tool lacks a manifest entry.
+- Manifest fields for symptom triggers, format examples, token-budget class, produced handles, consumed handles, output schema presence, and structuredContent presence.
+
+Acceptance criteria:
+
+- One command prints the exact current tool inventory by surface.
+- Tests no longer reference stale counts like 13 or 23 unless they are correct for a named legacy surface.
+- The manifest marks each tool as having or missing `outputSchema` and `structuredContent`.
+
+### Phase 2: Fix structured output gaps
+
+Priority: P0/P1
+
+Deliverables:
+
+- Browser Agent output schemas and structuredContent for all 17 tools.
+- Structured outputs for `youtube_transcribe`, `facebook_ad_transcribe`, and hosted capture tools.
+- Side-effect metadata for local file-writing tools.
+
+Acceptance criteria:
+
+- No tool returns only stringified JSON when it has structured data.
+- Browser screenshots return image content plus structured metadata.
+- Transcript tools return transcript text, segments, metadata, artifact, and resolved input as structured data.
+
+### Phase 3: Align descriptions with return shapes
+
+Priority: P1
+
+Deliverables:
+
+- `youtube_harvest` includes dates/thumbnails or stops promising them.
+- `facebook_page_intel` includes ad copy/landing URL/domain or stops promising them.
+- `extract_url` includes the promised extraction categories or narrows its description.
+- `maps_place_intel` exposes promised evidence categories with counts/truncation.
+
+Acceptance criteria:
+
+- For every noun promised in a tool description, there is a matching structured field, artifact reference, or explicit truncation note.
+
+### Phase 4: Upgrade parameters into micro-runbooks
+
+Priority: P2
+
+Deliverables:
+
+- Recovery paths for Facebook IDs, YouTube URLs, workflow IDs, artifact IDs, replay IDs, and session IDs.
+- Do-not-invent guards for cursors, workflow IDs, artifact IDs, replay IDs, and browser session IDs.
+- Explicit defaults/caps for all limit parameters.
+- Consistent proxy default language.
+
+Acceptance criteria:
+
+- A model can recover from not knowing an ID by following the parameter description.
+- Every free-text ID-like parameter says how to obtain a valid value.
+
+### Phase 5: Add sample prompts and negative space
+
+Priority: P2
+
+Deliverables:
+
+- 2 to 3 sample prompts per tool in the generated manifest.
+- Description updates naming sibling tools and when not to use the current one.
+
+Acceptance criteria:
+
+- Each tool can be routed from natural user phrasing without relying on the tool name alone.
+
+### Phase 6: Add craft linting
+
+Priority: P2
+
+Deliverables:
+
+- A tool-description lint script that checks every registered tool for:
+  - sibling/negative-space sentence
+  - sample prompts
+  - symptom triggers
+  - examples for format-sensitive params
+  - enum values in prose
+  - default and cap language
+  - do-not-invent guards for opaque handles
+  - output schema and structuredContent
+- A report that scores each tool against the 17-point checklist.
+
+Acceptance criteria:
+
+- CI can show why a tool is below gold-standard without another manual reverse-engineering pass.
+- The lint output includes one row per tool and one row per principle.
+
+## Naming Assessment
+
+Mostly good:
+
+- Names are snake_case.
+- Names use verbs or clear action nouns.
+- Resources are generally clear.
+
+Not gold-standard:
+
+- No namespace prefix such as `mcpscraper_` or `browser_` for main tools. Browser tools do use `browser_`, but main tools like `extract_url` and `search_serp` could collide in clients that combine servers.
+- `workflow_list` is acceptable because it lists workflows, not user data.
+- `rank_tracker_blueprint` is clear but should be described as a planning tool.
+
+Recommendation:
+
+- Do not rename existing public tools abruptly.
+- Add aliases only if the MCP framework supports stable aliases.
+- Use namespacing in docs and generated manifest.
+- Consider namespaced v2 names only in a future breaking release, for example `mcpscraper_search_serp`.
+
+## Done Definition For Gold-Standard MCP Quality
+
+This MCP reaches the requested quality bar when:
+
+- The exact active tool inventory is generated from source and documented by surface.
+- Every tool has:
+  - clear description
+  - symptom triggers written in user language
+  - negative space
+  - sample prompts
+  - complete parameter descriptions
+  - examples that teach exact format for format-sensitive params
+  - defaults and caps
+  - recovery paths for ID-like inputs
+  - do-not-invent guards for cursors and handles
+  - repeated enum/runbook language where the tool must stand alone
+  - output schema
+  - structuredContent
+  - high-signal return fields only
+  - resolved inputs
+  - count and truncation metadata where relevant
+  - artifact URLs or paths where relevant
+  - correct annotations for side effects
+- No tool relies on escaped JSON in text as its primary data output.
+- README, live tests, unit tests, and install/help text all agree on tool counts and proxy defaults.