Bolsai MCP server provides 11 well-named financial tools with consistent verb_noun patterns (get_*, list_, search_, screen_). All tools have descriptions meeting the 10-1024 character guideline. Input schemas are present and typed for all tools. However, output schemas are NOT documented, descriptions state what data is returned but do not formally specify response structure. Parameter descriptions are present but lack detail on valid ranges, constraints, and interdependencies. Error handling is basic (generic _error() function) and does not guide recovery. No tool annotations (readOnlyHint, destructiveHint) despite all tools being READ_ONLY. This is a solid community-grade server with good naming and basic structure, but falls short of production-grade polish on output documentation and error messaging.

• Document output schemas formally. For each tool, add a 'Returns' section specifying field names, types, and whether fields are always present or conditional. Example: 'Returns {ticker: string, price: float, change_pct: float, high_52w: float, low_52w: float, ytd_return: float}'. This enables LLMs to chain tools and extract data correctly.
• Enhance error messages with actionable recovery guidance. Instead of 'Not found: {e.detail}', return 'Stock ticker not found: INVALID_TICKER. Did you mean PETR4? Call search_companies to find valid tickers by name.' or 'Rate limit exceeded. Upgrade to Pro at https://usebolsai.com or retry after 60 seconds.'
• Add tool annotations. Mark all 11 tools with readOnlyHint: true in the tool registration. This signals to LLMs that these tools are safe to retry without side effects.
• Formalize parameter constraints. For screen_stocks 'filters', provide a BNF or explicit syntax: 'Comma-separated filters: metric_operator=value. Operator: gt (>), lt (<). Example: pl_lt=15,roe_gt=10,dividend_yield_gt=5'. Validate at entry and return clear errors.
• Document parameter interdependencies in screen_stocks. Clarify: 'sector and filters are combined (AND logic), both conditions must be met. sort and order apply to the column specified by sort; if sort is not in filters/available metrics, the result is undefined. limit caps the result count after filtering and sorting.'
• Add pagination support. Tools like list_sectors, search_companies, and screen_stocks return unbounded lists. Accept limit and offset/cursor parameters and return total_count and next_cursor. Example: 'Returns {sectors: [...], total: 42, next_cursor: "..."}'.