markdown-matters provides 7 well-named tools with complete input schemas and descriptions. Tool names follow verb_noun convention (md_search, md_context, md_structure, md_keyword_search, md_index, md_links, md_backlinks). All tools have descriptions (avg 140 chars, within 10-1024 baseline). Input schemas are properly typed with JSON Schema. However, output schemas are not documented, LLMs cannot predict response structure for planning. Parameter descriptions are present but some lack detail on constraints (e.g., md_search threshold 0-1 range is stated but not validated). Error handling is minimal, no recovery guidance or actionable error messages visible in tool definitions. md_index is a write operation but lacks confirmation/dry-run pattern. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles.

• Document output schemas for all 7 tools. Include field names, types, and examples. E.g., md_search returns [{path: string, section: string, score: number, content: string}].
• Add tool annotations: mark md_index with destructiveHint=true; mark all read-only tools with readOnlyHint=true. This enables clients to warn users before executing.
• Add confirmation pattern to md_index: accept a 'dry_run' boolean parameter (default false) that returns what would be indexed without modifying the database.
• Enhance error messages in handlers: catch file-not-found, permission-denied, and timeout errors; return structured errors with recovery hints (e.g., 'File not found at /docs/guide.md. Available files: /docs/intro.md, /docs/api.md').
• Make md_keyword_search require at least one filter (heading, has_code, has_list, has_table) or add a 'query' parameter to avoid ambiguous all-documents invocations.