The Letterboxd MCP server defines 12 tools with consistent naming patterns (verb_noun: search, get_*) and clear descriptions (avg ~80 chars, all >20 chars). All tools have documented input schemas with proper JSON Schema structure (type, properties, additionalProperties: false, required arrays). Parameter descriptions are present and explain the semantic meaning. However, there are meaningful gaps: (1) Output schemas are NOT documented, the server does not declare what fields tools return, forcing LLMs to reason about response structure; (2) Error handling is implicit (timeout wrapper exists, but no tool-level error categorization, recovery guidance, or user-fixable vs retryable classification); (3) Parameters lack constraints (enums, min/max bounds) in many cases, e.g., 'limit' and 'maxPages' accept unbounded integers; (4) Pagination is well-designed (nextCursor, fetchAll, maxPages, maxItems) but response structure is assumed, not documented. Tool definitions are directly visible in index.js (lines with 'name', 'description', 'inputSchema'), so inference risk is minimal. Overall composition is strong, tools are single-responsibility and chain-friendly (username resolution, film slugs). This is a solid B- implementation: good naming, adequate descriptions, proper schema structure, but missing output documentation and error guidance.

• Document output schemas for all 12 tools. Define the structure of 'items', 'meta', and optional fields (e.g., 'list' in get_list responses). Example: 'Returns {items: [{id, title, year, ...}], meta: {count, pages, nextCursor?}, list?: {name, description, ...}}'.
• Add min/max bounds to numeric parameters. E.g., limit: {type: 'integer', minimum: 1, maximum: 100} to prevent LLMs from requesting excessive page sizes. Set reasonable defaults (limit=20) and document them.
• Add error recovery guidance to tool descriptions. E.g., 'If the film is not found, try search() with a title keyword to confirm it exists on Letterboxd.' Include common failure modes (404, timeout) and recovery paths.
• Clarify the 'username' parameter dependency. Update description to: 'Letterboxd username, profile URL, or "me" (resolves to the logged-in user, requires LETTERBOXD_USERNAME/LETTERBOXD_PASSWORD environment variables). If "me" is passed without login credentials, an error will guide you to provide them.'
• Document pagination behavior explicitly in tool descriptions. E.g., 'Supports pagination. Set fetchAll=false to get a single page; use cursor + maxItems to fetch specific ranges. Response includes nextCursor only if more pages exist.'
• Add tool annotations (readOnlyHint, idempotentHint) to signal to MCP clients that these tools are safe to retry and do not modify Letterboxd data. This is a protocol-level improvement (see protocolReadiness section).