org-mcp provides 8 tools with basic schemas and descriptions, but falls short of production quality. All tools have descriptions (10-50 chars, below the 50-200 char baseline for LLM optimization) and input schemas are present but minimal. Parameter descriptions are sparse or missing entirely. No error handling guidance, no output schema documentation, and no tool annotations. The server reads and writes org files but lacks idempotency guarantees, confirmation steps for destructive operations, and structured error recovery paths.

• Expand tool descriptions to 50-200 chars. Example: 'list_org_files_tool' → 'List all .org files in the configured directory (ORG_DIR env var, default ~/org). Returns relative paths and full paths for each file. Use this to discover available files before reading or searching.'
• Document output schemas explicitly. Add a Returns section to each tool docstring specifying field names, types, and meanings. E.g., read_file_headings returns list[{level: int, title: str, content: str, todo_state: str|null}].
• Add parameter descriptions with format constraints. E.g., 'file_path: Relative path to the org file (e.g., notes/2024.org). Must not contain .. or absolute paths. Max 255 chars.'
• Implement structured error responses. Return {error: str, error_type: 'not_found'|'permission_denied'|'invalid_input'|'internal', recovery_hint: str} instead of plain error strings.
• Add dry-run support to destructive tools (add_org_file, add_heading, modify_heading). Accept an optional 'dry_run: bool' parameter that validates the operation without writing, enabling agents to preview changes before committing.