scratch-mcp defines 10 tools with complete input schemas and descriptions. Naming follows verb_noun convention (new_project, open_project, list_projects, compile, reload, run, stop, snapshot, read_state, import_sb3). Descriptions are present and contextual (avg ~120 chars), explaining WHAT each tool does and WHEN to use it. However, parameter descriptions are minimal (often single phrases like 'Project name', 'Optional project path'), lacking guidance on format, constraints, or dependencies. Output schemas are not documented, callers must infer structure from code. Error handling returns text messages but lacks recovery guidance or error classification. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk profiles (WRITE vs READ_ONLY marked in metadata). Tools are well-composed (each does one thing) and idempotent where appropriate (reload, compile are safe to retry). Baseline: avg tool description 194 chars (this server ~120), avg params 4 (this server 1-2), 100% of A+ tools have documented return types (this server has none visible).

• Document output schemas for all tools. E.g., 'Returns {success: boolean, message: string, projectPath?: string}' or 'Returns PNG image bytes with MIME type image/png'.
• Expand parameter descriptions to include format, constraints, and examples. E.g., 'path: Absolute or relative path to project directory. Must contain project.yaml. Defaults to active project if omitted.'
• Add tool annotations: mark destructive tools with destructiveHint, read-only tools with readOnlyHint, and idempotent tools with idempotentHint.
• Enhance error messages with recovery guidance. E.g., 'no project loaded, call reload(path) or import_sb3(file) first' instead of bare 'no project loaded'.
• Consider batch variants for tools agents call in loops (e.g., if agents snapshot multiple times, offer snapshot_all or snapshot_sequence).