shelby-mcp has 5 tools with clear verb-noun naming (shelby_upload, shelby_download, shelby_list, shelby_delete, shelby_account). All tools have descriptions (avg ~120 chars, within baseline 34-392). Input schemas are present and use Zod with type definitions. However, critical gaps: (1) No output schemas documented, LLMs cannot predict response structure; (2) Parameter descriptions lack format/constraint details (e.g., blob_name has no length/pattern guidance); (3) No error handling guidance, failures return raw CLI stderr; (4) shelby_list has a fallback catch block that silently swallows errors and returns account balance instead, violating error-classification pattern; (5) No pagination support despite list tool; (6) shelby_upload/delete lack confirmation/dry-run for destructive ops. Naming is solid but schema and error handling are weak.

• Document output schemas for all tools. shelby_upload should return {blob_name, size, expiration_timestamp, url}. shelby_list should return {blobs: [{name, size, created, expires}], total_count, next_cursor}. shelby_account should return {name, address, balance, network}.
• Add format constraints to parameters: blob_name (max 255 chars, no leading/trailing slashes, alphanumeric + hyphens/underscores), expiration (ISO 8601 or relative: 'in 7 days', 'tomorrow', '2025-12-31').
• Replace shelby_list error fallback with explicit error response: 'Failed to list blobs: {error}. Verify prefix is valid and account has blobs.' Let LLM decide next step.
• Add optional dry_run parameter to shelby_upload and shelby_delete. When true, validate inputs and return what would happen without executing. Prevents accidental data loss.
• Add pagination to shelby_list: limit (1-100, default 20), offset (default 0). Return total_count and next_offset in response so agent can iterate.