The AletaIndex MCP server defines 2 tools with clear action verbs and reasonable descriptions. Both tools have complete input schemas with type information and detailed parameter descriptions. The naming follows verb_noun conventions ('get_narratives', 'get_portfolio_risk'). However, output schemas are not documented, the code shows @mcp.tool() decorators but does not explicitly declare return types or response structures. Error handling is comprehensive with detailed, actionable error messages for validation failures and API errors. The server demonstrates good input validation (ticker format, date parsing, holdings parsing) with specific error recovery guidance. Main gaps: no tool annotations (readOnlyHint, destructiveHint, idempotentHint), output schemas not formally documented, and no pagination support documented despite potential for large narrative datasets.

• Add explicit return type documentation to both tools. Declare the response structure: e.g., 'Returns: {"global_narratives": [{"theme": str, "sentiment": float, "articles": [...]}], "daily_clusters": [...], "articles": [...], "metadata": {...}}' This enables agents to extract the correct fields without guessing.
• Add readOnlyHint tool annotation to both tools (via FastMCP, if supported, or in tool metadata) to signal they are safe idempotent reads. This helps agents understand they can retry without side effects.
• Add pagination parameters to get_narratives: 'limit' (default 20, max 100) and 'offset' or 'cursor'. Document in description: 'Results are paginated to max 100 articles per request. Use limit and offset to iterate through large datasets.'
• Document the response size constraint explicitly: 'Maximum 100 articles per response. To retrieve more, use offset parameter or narrow the date range.'
• Improve parameter descriptions with concrete examples of expected output ranges. E.g., 'from_date: Start date in YYYY-MM-DD format. Defaults to 7 days ago. Narrative data available for up to 2 years historical.'
• Consider adding a 'fields' or 'detail_level' parameter to reduce response size for common use cases, following the strip-api-responses pattern.
• Add enum constraint to portfolio 'holdings' format in description (already validated in code) to help LLMs understand the TICKER:WEIGHT syntax without guessing: Use pattern 'SYMBOL:0.00-1.00 (e.g., NVDA:0.30,AAPL:0.70).'
• Document error recovery paths explicitly in tool descriptions. E.g., 'If ticker not available in your tier, call get_available_tickers() first.' (if such a discovery tool exists, or add it).