Capital.com MCP has a comprehensive 40-tool suite with explicit schema definitions, type annotations, and descriptions. However, description quality is inconsistent: many tools (e.g., cap_session_status, cap_market_search) have adequate descriptions (60-150 chars), but several lack domain-specific context or usage guidance. Descriptions occasionally reference implementation details (e.g., 'limit truncates results client-side') rather than business intent. Parameter descriptions are present but often terse. Error handling and recovery guidance are minimal, tools do not explain what to do when auth fails, previews expire, or trades are rejected. No tool annotations (readOnlyHint, destructiveHint) visible despite clear risk stratification. Streaming tools (cap_stream_*) lack specifics about WebSocket behavior, reconnection, or data format. Output schemas are not explicitly documented in the tool descriptions, forcing LLMs to infer structure. The server correctly identifies write/irreversible risks but does not embed this into tool metadata or descriptions where agents can see it.

• Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to all 40 tools in schema. This enables agents and clients to infer safety without parsing descriptions.
• Document output schemas in every tool description. Format: 'Returns: { deal_id (string), confirmation_id (string), estimated_p_and_l (number), checks (array) }'. This helps agents chain calls.
• Expand descriptions for streaming tools to 150+ chars. Explain: what data is streamed, how often, what triggers closure, how to handle reconnection, and what error events look like.
• Add actionable error guidance to trading tools (cap_trade_execute_*, cap_trade_confirm_*). Example: 'If confirmation times out, the trade may have landed, call cap_trade_positions_list to check before retrying.'
• Convert string parameters with known values to enums in schema. E.g., cap_market_prices resolution: enum=['MINUTE_1', 'MINUTE_5', 'MINUTE_15', 'HOUR', 'DAY'] instead of free-form description.
• Add discovery hints to read-list tools. E.g., cap_trade_positions_list: 'Returns all open positions. Call this first, then use deal_id from the result to call cap_trade_positions_amend or cap_trade_positions_close.'
• Make authentication requirements explicit and uniform on every tool. Use a template: '[Requires authentication: yes|no]' at the end of descriptions.
• Clarify the cap_trade_confirm_get vs cap_trade_confirm_wait distinction. Add example: 'Use cap_trade_confirm_get for one-shot polling; cap_trade_confirm_wait for blocking until broker decision (up to 30s default).'