This server has well-structured schemas and reasonable descriptions for most tools, but suffers from several definition quality gaps that prevent it from reaching higher grades. All 8 tools have explicit definitions with input schemas and descriptions, which is a strength. However, parameter descriptions lack context about dependencies, constraints, and expected formats. Error handling is implemented (ERROR_CODES map) but not integrated into tool definitions. Output schemas are not documented, callers must infer what fields to expect from the Scrappey API. The naming convention is consistent (scrappey_* verb_noun pattern) but some tools conflate multiple responsibilities (e.g., scrappey_request_get combines URL fetching, CSS extraction, screenshot capture, and PDF generation, should be decomposed). Parameter descriptions are generic ('URL to request') without format guidance, and complex nested objects like browserActions lack per-field documentation. Descriptions are adequate (100-300 chars typical) but do not explain error recovery paths, prerequisites, or when to choose one tool over another.
scrappey_request_get and scrappey_request_post combine multiple independent concerns (URL fetch, CSS extraction, screenshot, video, PDF, header customization, cookie handling, etc.). Should be decomposed into smaller, composable tools so agents call only what they need.
Parameter descriptions are minimal and lack constraint/format guidance. Examples: 'URL to request' (4 chars), 'Session ID' (10 chars), 'Proxy in format http://user:pass@ip:port' (without stating what happens if format is wrong). Per the rubric baseline, average param descriptions should be ~72 chars and include expected format, range, or examples.
Recommendations
Document output schemas for all tools. For scrappey_create_session, explicitly state it returns {sessionId: string, fingerprint: string}. For request tools, document that response includes {html?: string, statusCode?: number, cookies?: object, screenshot?: string, ...}.
Decompose scrappey_request_get and scrappey_request_post into focused tools: scrappey_fetch_page_html (URL + session, returns HTML), scrappey_extract_page_text (HTML/URL, returns text with CSS selector), scrappey_capture_screenshot (URL/session + dimensions, returns image), etc. Each tool should do one thing.
Expand parameter descriptions to 50-100 chars. Example: instead of 'URL to request', write 'Full HTTP(S) URL to fetch (e.g., https://example.com/page). Must start with http:// or https://.'.
Add mutual-exclusivity constraints to descriptions. Example: 'Choose one of: proxy (custom proxy URL), proxyCountry (built-in proxy from country), or noProxy (no proxy). Cannot combine.'
For scrappey_browser_action, restructure the action schema with per-type sub-schemas or provide a table documenting which fields are required for each action type (navigate, click, input, select, scroll, etc.).
Integrate ERROR_CODES into tool definitions. For each tool that can fail, add to description: 'On error, response includes error code and description. See error reference for recovery steps.' Provide a public error reference or link.
Add idempotency guidance: scrappey_destroy_session should document 'This operation is idempotent, destroying a non-existent session returns success.' This tells LLMs it is safe to retry.
Score history
Overall score trend
↑ 5 points across a rubric change (v1 → v2)
50/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
50
2026-07-28+
v2
2026-03-09
F
45
-
v1
50/100
Make a GET request through Scrappey with browser rendering, anti-bot handling, and optional browser interactions
scrappey_request_postread onlyauth50/100
Make a POST request through Scrappey with browser rendering, anti-bot handling, and optional browser interactions
scrappey_browser_action has deeply nested schema (actions array, each with enum type and conditional fields). No per-action-type documentation. LLM cannot determine which fields apply to which action type without inferring from enum values.
Error handling implemented in ERROR_CODES map (38 codes) but not surfaced in tool definitions. Callers see error codes but tool descriptions do not explain recovery steps.
Tool naming lacks specificity. 'scrappey_request_get' vs 'scrappey_request_post' do not convey intent difference to LLM. Consider 'scrappey_fetch_page', 'scrappey_extract_text', 'scrappey_capture_screenshot' to disambiguate.
No pagination guidance for list_sessions. If session count grows large, response could exceed context window. Tool description should state result limits or pagination support.
No dependency hints in tool descriptions. E.g., 'scrappey_request_get requires an active session, call scrappey_create_session first if you do not have a session ID.' Agents waste calls discovering this.
Document when to use each variant. Add to scrappey_request_get: 'Use this for simple fetches with optional CSS extraction. For multi-step interactions, use scrappey_browser_action. For form submissions, use scrappey_request_post.'
Add result limits to list_sessions description: 'Returns all active sessions (max 100 per account). If count exceeds limit, consider archiving old sessions.'
For browserActions array, add dependency documentation: 'Each action in the sequence depends on previous actions. If action[0] (navigate) fails, subsequent actions are skipped. Ensure selectors account for page state after previous actions.'
Document timeout behavior: 'If request exceeds timeout (default 180 seconds), returns error CODE-0026. Use timeout parameter to adjust; retries parameter controls automatic retry count on transient failures (CODE-0001, CODE-0009).'
Add examples to tool descriptions. E.g., scrappey_request_get: 'Example: fetch a product page, extract price using CSS selector .price, and return as JSON. Equivalent to: GET https://example.com/product -> extract .price -> JSON.'
Document resource consumption: scrappey_create_session should warn 'Each session consumes browser memory. Destroy unused sessions to prevent CODE-0029 (too many sessions). Typical session limit is 10-50 depending on plan.'
For cssSelector parameter, document CSS specificity and escaping: 'Standard CSS 3 selectors. Complex selectors (e.g., .price:nth-child(2)) supported. Selector not found returns error CODE-0027 with available selectors.'
Document screenshot format: scrappey_request_get mentions 'screenshot' boolean but does not state return format (base64 PNG? URL?). Add: 'screenshot: true returns image as base64-encoded PNG in response.screenshot field.'
For filter parameter, document available fields: 'Restrict response to named fields. Valid values: response, cookies, statusCode, innerText, images, links, screenshot, redirects. Unknown fields silently ignored.'
Document retry semantics for POST: 'Retries use idempotent key (derived from body hash) to prevent duplicate submissions. Safe to retry on transient errors without side effects.'