avatar-shell is an Electron-based MCP client UI (not a traditional MCP server). It exposes 27 tools via a custom transport layer. Critical deficiencies: (1) Tool descriptions are bilingual but extremely terse (8-25 chars in English), failing the 10-1024 char guideline. E.g., 'Call MCP tools' for callMcpTool, 'Get talk context' for getTalkContext. (2) Input schemas are either missing entirely or severely under-specified. Most tools show only object-type parameters without nested field documentation. E.g., callMcpTool accepts 'params' as type:object with description 'Tool call parameters including callId, name, and input', no schema for nested fields. (3) No output schemas documented anywhere. (4) Naming is inconsistent: camelCase mixing generic verbs (call, get) with overlapping purposes (callMcpTool vs callMcpToolDirect, setAvatarConfig vs updateMutableSetting). (5) No parameter validation constraints, enums, or ranges visible. (6) Destructive tools (deleteAvatarConfig, closeApp) lack confirmation or dry-run capability documentation. (7) Error handling patterns not evident in source. Tool definitions appear to be inferred from TypeScript function signatures rather than explicit MCP schema registration.

• Expand all tool descriptions to 50-200 characters. Explain WHAT the tool does, WHEN to use it, and any prerequisites. Example: 'callMcpTool' should be 'Invoke a tool exposed by a connected MCP server. Use this to execute tools from external services (e.g., get weather, create Jira ticket). Provide the tool name, input params, and a unique call ID for tracking.'
• Document nested fields in object-type parameters. For 'params' in callMcpTool, show the expected structure: { callId: string, name: string, input: object }. For 'conf' in setAvatarConfig, document what AvatarSetting contains (fields, types, constraints).
• Add output schemas to every tool that returns data. Example for getMcpServerInfos: 'Returns: { servers: [{name: string, version: string, capabilities: string[]}], total: number }'
• Clarify overlapping tool pairs. Rename callMcpToolDirect to invokeToolImmediate or bypass_queueing and document when to use it vs callMcpTool. Similarly, distinguish setAvatarConfig (create/replace) from updateMutableSetting (partial update).
• Add enum constraints to parameters with known valid values. E.g., if templateId must match a specific avatar type, document valid values or reference getAvatarConfigList as a discovery tool.
• Implement confirmation step for destructive operations. For deleteAvatarConfig and closeApp, add optional dry_run: boolean parameter or require a separate 'confirm' step.
• Add error handling guidance. Document what errors each tool can return and what the LLM should do. Example: 'If avatar not found, call getAvatarConfigList() to discover available avatars, then retry with a valid ID.'

Inferred effective spec: 2026-07-28+.

• Official extensions adopted: Apps