yacli presents a moderately complex MCP server with 31 tools across mail, calendar, and disk domains. Strengths: all tools have non-empty descriptions (avg ~50 chars), input parameters are typed with descriptions, and output schemas are partially documented through structured implementations in Rust. Weaknesses: descriptions are uniformly terse (under 60 chars), many lack context about when to use them or what the LLM should do with results; parameter descriptions are minimal (1-3 word labels rather than explanatory prose); no visible output schema documentation in the MCP tool registration layer; error handling patterns are present in implementation but not surfaced to the MCP interface; tool compositions assume agent capability to chain calls across domains without explicit guidance on the proper sequences. The tool set is well-structured by domain (mail, calendar, disk, account, doctor, goal, update, app) with clear naming conventions (namespace.domain.action), but lacks the descriptive depth and output documentation expected of A-grade tooling.
Tool descriptions are uniformly terse (under 60 characters) and lack context about when to use each tool or what the agent should do with results. Current descriptions do not guide tool selection or downstream composition.
Expand tool descriptions to 100-200 characters. Each should answer: What does this tool do? When should I call it instead of a similar tool? What kind of result should I expect? Example: yacli.mail.send is currently 'Send a mail message', expand to 'Send a new email message to one or more recipients. Returns confirmation of send time and message ID. Use yacli.mail.forward to forward an existing message, or yacli.mail.send_link to attach a file via Yandex Disk.'
Add detailed parameter descriptions explaining format and constraints. Replace 'Account identifier' with 'The account name or ID (string, e.g. 'john@example.com' or 'acc-123'). Call yacli.account.list() to see available accounts if you don't have one.' Similarly, explain what 'path' means for disk operations (absolute path from Disk root, starting with '/').
Document output schemas for all tools. At minimum, list the top-level fields returned and their types. For yacli.mail.list, document something like: 'Returns {messages: [{uid: integer, from: string, subject: string, date: ISO8601 string, preview: string}], total_count: integer, has_more: boolean}'. This lets agents know what to extract from the result.
Add error handling guidance to descriptions of WRITE and DESTRUCTIVE tools. E.g., yacli.calendar.delete: 'Deletes an event permanently (cannot be undone). Returns success or error (e.g., event not found). If deletion fails, check that the event_id is correct and that you have permission to delete it.'
Add dry_run parameters to yacli.calendar.delete and yacli.disk.unpublish to match the safety pattern of similar tools.
Parameter descriptions are minimal (1-3 word labels: 'Account identifier', 'Mail folder name', 'Calendar name') without guidance on expected format, examples, or constraints. LLMs cannot infer whether 'account' means a string ID, email, or account number; 'path' on disk could be absolute or relative. Descriptions should explain format, valid ranges, and dependencies.
Output schemas are not documented in the MCP tool registration. While implementation code (src/mcp/server.rs) contains structured logic, the tool definitions visible in the MCP server do not include documented return types, field names, or response structure. Agents cannot plan downstream tool calls without knowing what fields will be returned. E.g., yacli.mail.list presumably returns messages with IDs for yacli.mail.read to consume, but this is not documented.
Error handling and recovery guidance are not surfaced in tool descriptions. Tools like yacli.mail.send, yacli.calendar.delete, yacli.disk.upload expose WRITE and DESTRUCTIVE operations but descriptions do not clarify what errors are possible, when to retry, or how to recover from failures. Per pattern:recovery-guide, error responses should tell the LLM what to do next. Current descriptions make no mention of error scenarios.
Destructive tools (yacli.calendar.delete, yacli.mail.send, yacli.disk.upload with overwrite=true) do not document dry-run or confirmation support. Per pattern:confirmation-request, irreversible operations should offer a preview or confirmation step. The source code shows dry_run parameters on some mail tools (yacli.mail.send, yacli.mail.send_link, yacli.disk.upload, yacli.disk.upload_link), but yacli.calendar.delete and yacli.disk.unpublish lack this safeguard in their parameter lists.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) visible in the registration code. Risk markers are noted in the evaluation (READ_ONLY, WRITE, DESTRUCTIVE) but are not formalized in the MCP schema as tool annotations per the current spec (2026-07-28). This prevents MCP clients from automatically adjusting UI/access control based on tool risk.
Mail attachment selector parameter (used in yacli.mail.attachment_export, yacli.mail.invite_inspect, yacli.mail.invite_create_event) is typed as 'object' with no sub-schema or description. LLMs cannot determine how to construct a valid selector without a schema defining its fields, constraints, and meaning.
Account and calendar parameters (yacli.app.snapshot, yacli.auth.status, many calendar and disk tools) accept string identifiers but do not clarify whether these are human-friendly names, system IDs, emails, or UUIDs.
Multiple mail tools operate on 'folder' and 'uid' parameters without clarifying how the LLM should obtain these values. Agents would need to call yacli.mail.folders then yacli.mail.list before calling tools like yacli.mail.read or yacli.mail.send. Descriptions should hint at this dependency: 'Call mail.folders() first to list available folders, then mail.list() to search for messages by UID.'
Add tool annotations (readOnlyHint, destructiveHint) to the MCP schema registration for all WRITE and DESTRUCTIVE tools. This enables MCP clients to apply access controls and UI warnings automatically.
Replace 'object' type for attachment selector with an explicit schema or enum. Define the expected structure: e.g., {by: 'index' | 'content_type', value: string | integer}.
Clarify identifier formats in parameter descriptions. If 'account' can be a name or ID, say so explicitly. If only IDs are accepted, provide an example (e.g., 'Account ID (UUID format, e.g., 550e8400-e29b-41d4-a716-446655440000)').
Add dependency hints to mail tool descriptions. E.g., yacli.mail.read: 'Fetch details of a specific mail message. First call yacli.mail.folders() to list folders, then yacli.mail.list(folder) or yacli.mail.search() to find messages by UID.'
Review limit parameters (yacli.mail.list, yacli.disk.list, yacli.mail.search) and document expected ranges (e.g., 'limit: integer 1-100, default 20'). State what happens if limit exceeds maximum.
Add explicit return-value constraints to descriptions. E.g., 'yacli.disk.list returns up to 100 items per call. Use pagination to retrieve more.' This prevents agents from expecting unbounded results.
For tools that require account/calendar/folder context, add a sentence clarifying scope. E.g., 'yacli.calendar.events lists events in a single calendar. Call yacli.calendar.list() first to see all calendars if you need to search across multiple.'
Consider a 'dry_run' or 'preview' mode for all destructive operations. Add corresponding parameter to yacli.mail.forward (currently can send mail but has no preview option).