DocumentMCP has two tools with basic schemas and descriptions, but significant gaps limit production readiness. Both tools have descriptions (10-20 chars baseline met), but descriptions lack depth on WHEN to use them and what happens on error. Schemas are present but minimal, parameters have types and descriptions, but no enums, ranges, or validation guidance. No output schemas documented. Error handling is minimal (ValueError raised but not actionable for LLMs). Tool names follow verb_noun pattern (read_*, edit_*) which is good, but descriptions don't explain state mutations or recovery paths. No tool annotations (readOnlyHint, destructiveHint) despite edit_document being destructive. Composition is reasonable (two focused tools), but no pagination, batch operations, or chaining support.

• Add tool annotations: @mcp.tool(..., annotations={'readOnlyHint': False, 'destructiveHint': True}) for edit_document to signal state mutation and non-idempotence.
• Expand descriptions to 100-150 chars. Example: 'Read the full text contents of a document by ID. Returns plain text. Use before edit_document to see current state. If doc not found, call list_docs() to see available IDs.'
• Document output schemas explicitly. E.g., 'Returns: string (plain text content)' for read_doc_contents; 'Returns: object {success: bool, new_content: string}' for edit_document.
• Enhance error messages with recovery paths. Catch ValueError and return structured error: {'error': 'Document not found', 'available_docs': list(docs.keys()), 'suggestion': 'Try one of the available IDs above.'}
• Add validation and guidance for edit_document's old_str parameter. Document: 'Must match exactly, including leading/trailing whitespace. For multi-line text, use \n. If no match found, call read_doc_contents first to verify current content.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry