mkdnsite provides 4 well-named, read-only documentation tools with clear descriptions and basic Zod schemas. All tools follow verb_noun naming (search_docs, get_page, list_pages, get_nav). Descriptions are concise (10-60 chars) and state what each tool does. However, schemas lack depth: parameters have minimal constraints, output schemas are undocumented (tools return JSON.stringify'd text rather than structured objects), and error handling is minimal. The search_docs tool accepts a limit parameter with proper min/max constraints (1-50), but other tools have empty input schemas. No tool annotations (readOnlyHint, idempotentHint) are present. Output is returned as plain text JSON strings rather than structured MCP response objects, forcing LLMs to parse unstructured content.

• Return structured objects instead of JSON.stringify'd text. E.g., search_docs should return {results: [{title, slug, description, excerpt, score}]} as a typed object, not a JSON string. This lets LLMs extract fields directly without parsing.
• Add tool annotations: mark all four tools with readOnlyHint=true and idempotentHint=true. This signals to agents that these tools are safe to retry and do not modify state.
• Enhance error handling in search_docs and list_pages. If search returns no results, suggest 'Try a broader query or call list_pages() to see all available pages.' If list_pages is empty, explain 'No documentation pages found. Ensure content is loaded.'
• Document output schemas explicitly. Add a comment or schema definition showing the structure of each tool's response (e.g., SearchResult = {title: string, slug: string, description?: string, excerpt: string, score: number}).
• Add a 'format' parameter to get_page to support returning HTML or plaintext variants alongside markdown. This increases utility for different agent workflows without adding new tools.