Vitally MCP has basic tool definitions with schemas and descriptions present, but falls short of production quality. All 6 tools have descriptions (10-80 chars, mostly adequate) and input schemas with type definitions. However, parameter descriptions are minimal or absent, most params lack guidance on format, constraints, or dependencies. Output schemas are undocumented; tools return raw API responses without field documentation. Error handling is absent, no recovery guidance, no categorization of retryable vs fatal errors. The create_account_note tool (WRITE operation) lacks confirmation or dry-run support. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Naming is verb-first and clear (search_, get_, create_), but parameter naming inconsistencies exist (accountId vs email vs externalId). Overall, definitions are skeletal, sufficient to invoke but insufficient for LLM-driven composition or error recovery.

• Document output schemas for all tools. For get_account_conversations, explicitly define: { results: [{ id, subject, createdAt, updatedAt, account: { id, name } }], next: string|null }. Include field types and descriptions.
• Add parameter descriptions with format/constraint guidance. search_users should clarify: 'email (string, optional): User email address. If provided, other params ignored. externalId (string, optional): External user ID. emailSubdomain (string, optional): Email domain suffix to filter results. At least one param required.'
• Implement error categorization and recovery hints. Catch API errors and return: { error: 'User not found', retryable: false, suggestion: 'Try search_users() with a partial name or different email domain' }.
• Add tool annotations. Register create_account_note with destructiveHint=true and idempotentHint=false. Register read-only tools with readOnlyHint=true. This enables LLM safety reasoning.
• Add confirmation step for create_account_note. Return { status: 'pending_confirmation', preview: { accountId, content }, confirmationToken } and require a confirm_create_note(token) call before executing. Prevents accidental duplicates.