PyreCrawl demonstrates solid tool naming (verb-first: scrape, extract, map_site, crawl, search, batch_scrape, deep_research, document, monitor, search_papers, session, cache, health) and comprehensive descriptions covering WHAT and WHEN for most tools. Strengths: clear use-case guidance in tool descriptions (e.g., scrape explicitly states 'Use this when the user shares a URL and wants its content'), escalation strategy well-documented (fast→stealth→llm ladder), and batch operations exposed (batch_scrape, deep_research). Gaps: (1) schemas are present but parameter descriptions lack specificity, e.g., 'prefer' parameter describes modes but omits what happens on failures or cost tradeoffs; (2) output schema documentation is absent, markdown field is mentioned but shape, max length, and field presence guarantees are not documented; (3) error responses not specified, no guidance on what error structure LLMs should expect, recovery hints, or retryability classification; (4) session/cache tools are write-capable but lack confirmation or dry-run patterns; (5) several parameters lack constraints, timeout as integer has no min/max, limit has no stated cap despite being mentioned as defaulting to 200. The tool descriptions themselves (50-150 chars, averaging ~120) fall within production baseline but could be tightened. Parameter annotations average 40-80 chars, acceptable but some (js, wait_for) are verbose. Schemas visible in source are properly typed (string, integer, boolean, object, array) with Pydantic-backed validation, but output structures are not formally declared in the tool registration.

• Add formal output schema documentation to every tool. Specify field names, types, and presence guarantees. Example for scrape: 'Returns {url: string, final_url: string, status: integer, markdown: string (up to 60k chars), title: string, method: string, elapsed_ms: integer, meta: object with keys: js_result (optional), links (optional)}.'
• Add min/max constraints to all numeric parameters: timeout ∈ [1, 300], limit ∈ [1, 500], max_concurrency ∈ [1, 16], interval_seconds ∈ [60, 86400], max_checks ∈ [1, 100], iterations ∈ [1, 10].
• Document error recovery for each tool: e.g., 'scrape returns {error: string, tool: "scrape", url: string, hint: string} on failure. Hint guides next step: "User not found. Try search_users()" or "Cloudflare detected. Retry with prefer=\'stealth\'.". Retryable errors include timeout (retry later), Cloudflare block (retry with prefer=stealth). Non-retryable: invalid URL, invalid schema.',
• Add tool-scope disambiguation in server instructions: clarify when to use search (quick web search) vs search_papers (academic) vs deep_research (iterative research with refinement). Example: 'Use search for one-off queries, deep_research for complex topics requiring multiple passes with query refinement.'
• Document session tool state machine: 'Actions must follow order: open() first, then click/fill/type/eval/screenshot in any order, then close(). Each action is validated against current page state; e.g., click() fails if selector not found. Use eval() to check DOM state before subsequent actions.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry