Tool naming uses hyphens instead of verb_noun pattern (e.g., 'download-to-local-file' vs 'download_file'). LLM naming baselines show 90% of A+ tools use verb_noun with underscores. Hyphenated names are Web-friendly but conflict with LLM parsing conventions and make tool intent harder to infer from name alone.
Parameter descriptions are minimal and lack actionable constraints. For example, 'filePath' in upload-local-file has description 'Path to the file to upload' but lacks: (1) absolute vs relative path acceptance, (2) supported file types, (3) maximum file size. Similarly, 'attachmentId' in download tools lacks guidance on valid ID ranges or what happens when ID is invalid.
Rename all tools to use verb_noun underscore convention: 'upload_local_file', 'download_file', 'download_thumbnail', 'upload_from_base64', 'download_as_base64', 'download_thumbnail_as_base64'. This aligns with LLM naming baselines and makes tool intent obvious from name alone.
Expand every parameter description to 50 - 150 characters and include format constraints. Example: 'filePath: Absolute or relative path to the local file to upload. Supported formats: PDF, images (JPEG, PNG), documents (DOCX, XLS). Max file size: 100 MB.'
Document output schemas in tool definitions. Add a 'resultDescription' or 'returns' field explaining the structure: '{success: boolean, filePath: string (if write operation), content: string (if base64), filename: string, message: string}'.
Add decision guidance to each tool description. Example for 'download_file': 'Use this when you need to save a file to the agent's local disk (e.g., for integration with local scripts). Use download_as_base64 if you need to embed the content in a message or pass it to another tool without filesystem access.'
Document error cases and recovery paths for each tool. Example: 'If attachment ID is invalid, error is "Attachment not found". Verify the ID by calling list_attachments(). If outputDir is not writable, error is "Permission denied", check directory permissions or provide an alternative outputDir.'
Add support for human-readable attachment lookup (by filename or partial name match) alongside numeric IDs. This reduces LLM discovery calls and matches the chat data model.
Output schemas are not documented in tool definitions. Handlers return structured JSON (success, filePath/content, filename, message) but this is not visible in the MCP tool schema. LLMs cannot plan downstream tool calls or extract fields without documented output schemas. All tools affected.
Missing context for tool selection and composition. With 6 tools focused on attachments, LLMs need guidance on WHEN to use each. E.g., when should an agent choose 'download-as-base64-content' vs 'download-to-local-file'? No tool description answers this. Lack of dependency hints forces agents to guess.
Error handling and recovery guidance is absent. Tools have no documented error cases or recovery paths. What happens when attachment ID is invalid? What if file is too large? What if outputDir does not exist or is not writable? No tool description provides error recovery guidance (pattern:recovery-guide).
No natural identifier support. All tools require opaque IDs (attachmentId as number). No support for human-friendly lookups (e.g., 'download attachment named report.pdf'). This forces agents into extra discovery calls and mismatches the chat data model where users speak in names, not IDs.
Optional parameters lack clear semantics. E.g., 'outputDir' is optional in download tools and 'defaults to OS temp directory', but: (1) Which OS? On what path? (2) Does the user have write access? (3) Will the agent know where the file was saved? These ambiguities force defensive coding or failed calls.
No idempotency guarantees documented. If 'upload-local-file' is called twice with the same file, does it create two attachments or overwrite? If 'download-to-local-file' downloads to an existing filename, does it overwrite or fail? Agents retry on ambiguous failures, non-idempotent tools risk duplicate side effects.
Clarify optional parameter semantics. For 'outputDir', document: 'If omitted, files download to [standard temp dir: /tmp on Linux, %TEMP% on Windows, /var/folders on macOS]. Verify write access before calling. The tool returns the full path, so you always know where the file was saved.'
Declare idempotency guarantees. Example: 'Uploading the same file twice creates two separate attachments (not idempotent). If you need idempotent upsert, call delete_attachment(id) first, then upload.' Or if download is idempotent: 'Downloading the same attachment multiple times with the same outputDir will overwrite the previous file (idempotent).'
Consider adding 'delete_attachment' and 'list_attachments' tools to complete the CRUD cycle and reduce discovery friction.
Add file size and format constraints to handler implementations (not just descriptions) to catch errors early and provide actionable feedback to the LLM.