BabelWrap defines 16 tools with consistent naming (verb_noun pattern: babelwrap_*), all with descriptions and Zod schemas. However, descriptions are generic and lack LLM-optimization guidance. Parameter descriptions are present but minimal (10-50 chars). Output schemas are not documented, responses are JSON-stringified snapshots with no field-level guidance. Error handling is absent; no recovery guidance or categorization. The 'compact' parameter is repeated across all tools but never explained. Session management is stateless but lacks idempotency guarantees.

• Document output schemas for all snapshot-returning tools. Specify fields like 'elements' (array of {id, text, selector}), 'url', 'title', 'viewport'. This enables LLMs to extract element IDs for deterministic targeting without reverse-engineering JSON.
• Add error handling with actionable recovery guidance. Wrap tool calls in try-catch; categorize errors as retryable (network timeout, session expired) vs user-fixable (element not found, invalid selector). Return 'Element not found. Available elements: [list]. Try a different description or use an element ID from a previous snapshot.'
• Clarify the 'compact' parameter. Either remove it (simplify the API) or document precisely: 'If true, return minified JSON with no whitespace and stripped HTML tags. Use for token-constrained contexts.' Provide a baseline response size estimate.
• Document idempotency for session operations. State: 'babelwrap_close_session is idempotent, calling it twice with the same session_id is safe and returns success both times.' This guides agent retry logic.
• Add a discovery tool or enhance babelwrap_snapshot to return available element IDs and selectors. This enables agents to build deterministic targeting strategies without trial-and-error natural language matching.