Polygon-server provides 8 well-named, read-only financial data tools with complete input schemas and basic descriptions. All tools follow verb_noun naming (get_*, list_) and have JSON Schema definitions with required fields and enums where appropriate. However, descriptions are minimal (10-50 chars), lack context on WHEN to use each tool, and parameter descriptions are sparse. Output schemas are not documented, LLMs cannot predict response structure. Error handling returns raw API messages without recovery guidance. No tool annotations (readOnlyHint, idempotentHint) despite all being read-only. Missing pagination guidance for list_tickers and get_ticker_news. Overall: functional but below production baseline for agent reasoning.

• Expand tool descriptions to 100-200 chars. Include WHAT the tool does, WHEN to use it (vs similar tools), and what data it returns. Example: 'Get real-time bid/ask quotes for a ticker symbol. Use this for current market prices; use get_aggregates for historical bars. Returns bid, ask, last price, and timestamp.'
• Document output schemas for each tool. Specify which fields are always present, which are optional, and their types. This enables LLMs to plan downstream calls and extract the right data.
• Enhance error messages with recovery guidance. Instead of 'Error getting ticker details: ...', return 'Ticker not found. Try list_tickers(search="AAPL") to find valid symbols.' or 'API rate limit exceeded. Retry in 60 seconds.'
• Add tool annotations to the ListToolsRequestSchema response. Set readOnlyHint=true and idempotentHint=true for all tools so agents know they are safe to retry.
• Document pagination for list_tickers and get_ticker_news. Specify default limit (100, 10), max limit, and whether cursor-based or offset-based pagination is supported.