Four read-only tools with clear verb-noun naming (pcloud_list_folder, pcloud_read_file, pcloud_search, pcloud_get_file_link). All have descriptions (34 - 50 chars) and input schemas with typed parameters. Tool annotations present (readOnlyHint, idempotentHint). However, descriptions are minimal (below the 50 - 200 char LLM-optimized baseline), parameter descriptions lack detail on constraints/formats, and output schemas are not documented in the visible code. Error handling is implemented (PCloudApiError, PCloudContentLimitError, etc.) but recovery guidance is not visible in tool definitions. Security is strong: no credentials in parameters, rate limiting, and byte budgets enforced server-side.

• Expand tool descriptions to 80 - 150 characters. Include WHAT the tool does, WHEN to use it (e.g., 'Call this first to explore folder structure'), and what it returns. Example: 'List all files and folders in a pCloud directory. Returns metadata including names, sizes, and types. Use this to explore the folder hierarchy before reading files.'
• Add constraint details to parameter descriptions. For 'path': 'Virtual pCloud folder path (max 16 KB UTF-8, must start with /)'. For 'maxBytes': 'Maximum bytes to read (1 - 1048576, default 262144). Larger files are truncated.'
• Document output schemas in tool definitions. Specify that pcloud_list_folder returns {contents: [{name, isFolder, metadata}], ...}, pcloud_read_file returns {content, mimeType, size}, etc. This enables LLMs to chain tools correctly.
• Add recovery guidance to error messages. Instead of generic errors, return: 'File too large (5 MB > 1 MB limit). Try pcloud_search to find a smaller file, or use maxBytes=1048576 to read in chunks.'
• Add pagination to pcloud_search: accept 'limit' (1 - 100, default 20) and 'offset' (0+) parameters. Return {results: [...], total_count, has_more} so agents can iterate through large result sets without context explosion.