wp-blockmarkup-mcp presents well-structured tool definitions with consistent naming, clear descriptions, and comprehensive input schemas. All 6 tools follow verb_noun naming conventions (search_*, get_*, list_, validate_). Descriptions are concise (100-200 chars), exceeding the 10-1024 character baseline and meeting LLM-optimized expectations. Input schemas use Zod with explicit type declarations and descriptions for all parameters. However, output schemas are not formally documented, responses are formatted as markdown text rather than structured objects. Error handling is basic (try/catch with generic messages). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being read-only and idempotent. These gaps prevent a higher score despite solid naming and parameter definition.

• Convert response formatting from markdown text to structured JSON with typed fields. Example: instead of returning markdown blocks, return [{block_name, title, category, block_type, validation_status, confidence, source_name, description}] with documented field types and optional fields clearly marked.
• Add tool annotations to all 6 tools. Wrap the inputSchema in an object with readOnlyHint: true and idempotentHint: true to signal LLM safety characteristics. Example: { name: 'search_blocks', description: '...', inputSchema: {...}, readOnlyHint: true, idempotentHint: true }
• Enhance error messages with actionable recovery steps. Change 'Block not found. Use search_blocks to find blocks first.' to 'Block "<block_name>" not found. Try search_blocks(query="<partial name>") or check source indexing with the CLI tool list-sources.'
• Document output schemas explicitly. Create a schema definition for each response type (BlockResult, AttributeResult, MarkupExample, etc.) and include in the tool definition or server documentation.
• Validate limit parameters at runtime. Add explicit checks in handlers: if (args.limit && (args.limit < 1 || args.limit > 100)) { return error with 'limit must be 1-100' }.
• Add pagination support. search_blocks and search_variations return lists but lack offset/page and next_cursor fields. For large result sets, implement cursor-based pagination to avoid context window exhaustion.
• Include chaining IDs in responses. If get_block_schema returns attributes with source information, also return block_id or internal reference needed by downstream tools.