Scriptorium has 6 tools with basic descriptions but critical gaps in schema documentation and parameter clarity. Tool names are reasonably verb-based (search, expand, get, summarize, guide), but input schemas are either missing or inferred from test files rather than visible in actual tool registration code. Descriptions are present but generic (10-50 chars), falling below the 50-200 char baseline for LLM-optimized docs. No parameter descriptions visible in schemas. Output schemas are undocumented. Error handling and recovery guidance absent. The codebase shows sophisticated internal logic (diagnostics, caching, git snapshots) but this complexity is not reflected in tool interfaces designed for agent reasoning.

• Expand tool descriptions to 50-200 chars. Example: 'search' → 'Search markdown documentation by keyword. Returns matching blocks with file paths and line numbers. Use when looking for specific topics or implementation examples.'
• Add parameter descriptions to all schemas. For 'query': 'Search query string (1-500 chars). Supports partial matches. Case-insensitive.' For 'mode' in get_content: 'Content retrieval mode: full (entire block), snippet (first 200 chars), or metadata (title/path only).'
• Document output schemas for each tool. Example for search: '{results: [{id, title, path, snippet, lineNumber}], totalCount, hasMore}'. Include IDs needed for downstream tools like get_content.
• Add error handling guidance. Example: 'If search returns no results, try broader keywords or use expand_related with seed references. If refId not found in get_content, call search first to discover valid IDs.'
• Make tool registration explicit in code (not inferred from tests). Create a tools.go or registration.go file that declares all tools with full schemas, descriptions, and parameter metadata in one place for auditability.