kiwix-mcp demonstrates solid definition quality with all 6 tools having clear verb-noun naming (list_archives, search, inspect_article, read_article, list_references, extract_image) and comprehensive descriptions (80-150 chars each). Input schemas are fully specified with typed parameters and descriptions. Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are correctly applied. However, output schemas are not documented in the visible code, responses are inferred from implementation rather than explicitly declared. Parameter descriptions are good but could be more prescriptive about constraints (e.g., max_chars limits, archive_id format). Error handling is present but recovery guidance is minimal. The MCP_INSTRUCTIONS string provides excellent agent guidance but is not formally integrated into tool metadata.

• Document output schemas for all tools. Define return types for list_archives (array of {archive_id, title, description, date, language}), search (array of {article_path, title, snippet}), read_article (object with {content, sections, images, links}), etc. Use JSON Schema or explicit type annotations in docstrings.
• Add min/max constraints to numeric parameters in JSON Schema. E.g., max_chars: {type: 'integer', minimum: 1, maximum: 16777216}, limit: {type: 'integer', minimum: 1, maximum: 100}.
• Enhance error messages with recovery guidance. E.g., 'Archive "wikipedia_en" not found. Available archives: [list]. Call list_archives() to refresh.' This enables LLM self-correction.
• Document pagination for search(). Add offset/cursor parameter and return total_count and has_more fields so agents can iterate through large result sets without context explosion.
• Formalize extract_image side effects. Document that images are cached locally, explain the MAX_TEMP_IMAGES=16 eviction policy, and clarify the file_path lifetime in the response schema.

Inferred effective spec: 2026-07-28+.

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