sourceplane-mcp demonstrates solid fundamentals: all 7 tools have clear verb-noun names (list_, read_, search_, write_), explicit descriptions (avg 85 chars), and complete Zod schemas with type definitions. Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are correctly applied. However, parameter descriptions are sparse or missing entirely, most params lack guidance on format, constraints, or when to use them. Output schemas are undocumented (tools return plain text via text() wrapper, not structured objects). Error handling is minimal: no recovery guidance, no categorization of retryable vs fatal errors. The write_file tool lacks confirmation/dry-run safeguards despite being destructive. Composition is clean (single responsibility per tool), but batch operations and pagination are absent.

• Add detailed parameter descriptions to all tools. Example: 'sourceKey (string, required): The configured source identifier (e.g. "my-repo", "github-org/project"). Use list_sources to discover available keys.'
• Document output schemas explicitly. Replace text() wrapper with structured JSON responses. Example: read_file should return {"path": string, "content": string, "size_bytes": number, "encoding": string}.
• Implement error recovery guidance. Catch common failures (file not found, permission denied, branch not found) and return actionable messages: 'File not found at path/to/file.ts. Available files in this directory: [list]. Try list_files(sourceKey, "path/to") to explore.'
• Add confirmation/dry-run for write_file. Return a confirmation token on first call; require it on second call to actually write. Or add a dry_run boolean parameter that returns what would be written without modifying.
• Add pagination to list_files, get_source_structure, search_code. Include offset/limit parameters, return total_count, and document max result limits (e.g. search_code already caps at 50, but list_files has no documented limit).