demosmith-mcp provides 20 well-structured tools with explicit Zod schemas and descriptions. Most tools follow verb_noun naming (demosmith_start, demosmith_click, demosmith_fill) and include actionable descriptions (10 - 200 chars). However, several issues reduce the score: (1) descriptions for many tools are minimal or vague (e.g., demosmith_status: 'Get the status...', under 50 chars); (2) no documented output schemas, the code shows input validation but does not specify what each tool returns, forcing LLMs to infer structure; (3) error handling logic is not visible in the sample code, so recovery guidance cannot be verified; (4) parameters like 'type' in demosmith_wait and 'type' in demosmith_assert lack constraint clarity (enum vs free-form); (5) no security or permission-gating patterns visible for sensitive tools like demosmith_upload (file upload) and demosmith_start (browser automation with file system access). The Zod-to-JSON-Schema conversion is sound, but the underlying schemas themselves lack depth (e.g., no minLength, maxLength, pattern, or enum constraints visible for most params). This is a solid mid-range implementation that works but needs refinement for production readiness.

• Document output schemas for all 20 tools. For example, demosmith_start should document: returns {sessionId: string, browserId: string, startTime: ISO8601, status: 'recording'}. demosmith_snapshot should specify: returns {nodes: Array<{ref: string, tag: string, text?: string, children?: Array<nodeRef>}>}. Use a TypeScript/Zod export to keep schemas DRY and maintainable.
• Expand descriptions for discovery tools from ~50 chars to 150 - 250 chars. Example: 'Get the status of the current demo session, including the number of recorded steps, elapsed time, current URL, and recording progress. Call this before ending the session to verify capture is complete.' This tells the LLM when and why to invoke the tool.
• Add explicit enum constraints to free-form type parameters. Change demosmith_wait to: type as z.enum(['timeout', 'selector', 'navigation', 'load']) with .describe() for each. Same for demosmith_assert: type as z.enum(['text', 'visibility', 'url', 'title', 'value', 'attribute']).
• Implement structured error responses. When demosmith_click fails with 'element not found', return: {success: false, error: {code: 'ELEMENT_NOT_FOUND', message: 'Element ref "42" not found. Snapshot may be stale. Call demosmith_snapshot() to refresh.', recoveryHint: 'call_snapshot_then_retry'}}. This gives LLMs actionable recovery paths.
• Add permission checks and audit logging for sensitive tools (start, upload, screenshot). Log who invoked the tool, with which parameters, and what happened. Return a 403 error if the agent lacks the required scope (e.g., 'capability:browser_automation', 'capability:filesystem_write').