Sugra API MCP demonstrates strong tool naming, mostly complete parameter schemas, and clear descriptions. However, there are notable gaps: several tools lack detailed output schema documentation, some parameter descriptions are generic, and error handling guidance is minimal. The 11 tools are well-named with action verbs (call_, search_, describe_, list_, resolve_, get_, fetch_, sugra_*) and most include comprehensive input schemas. All descriptions are present and substantive (100+ chars typical). Key concern: tools 2-11 appear in evals/scoring.py with no explicit registration visible in server code; tool definitions are inferred rather than directly registered, which caps confidence. The server follows good patterns for discovery tools (list_toolsets, list_sources, search_endpoints) and includes proper entity resolution (resolve_entity, sugra_entity_lookup). Security-wise, API keys are handled server-side (SUGRA_API_KEY env var), not exposed as parameters. Composition is sound: tools chain logically (search→describe→call). Main weaknesses: undocumented output schemas, sparse error guidance, and lack of visible destructiveHint/idempotentHint annotations on read-only tools.

• Document output schemas for all tools. Example for search_endpoints: 'Returns array of { operation_id (string), name (string), toolset (string), source (string), description (string) }, with total_count and next_cursor for pagination.'
• Locate and verify all tool registrations in sugra_api_mcp/server.py. Ensure tools 2-11 are explicitly registered with @server.list_tools() or equivalent fastmcp decorator, not inferred from external files.
• Add enum constraints to string parameters with known valid values. E.g., granularity: enum=['1h', '1d', '1w', '1mo'], regimes: enum=['US', 'UN', 'EU', 'UK', ...], recipe: enum=['company_snapshot', 'etf_snapshot', ...].
• Define sub-schemas for complex object parameters. E.g., 'entity parameter must have { namespace: string, id?: string, ticker?: string, name?: string }' with required/optional clarity.
• Clarify call_endpoint vs fetch_data, consolidate into a single tool or explicitly differentiate in descriptions (e.g., call_endpoint for common cases, fetch_data for advanced filtering).
• Add error handling guidance to tool descriptions. E.g., 'If operation_id not found, call search_endpoints() to discover available endpoints. If API returns 429, retry after backing off exponentially.'
• Add tool annotations: register all read-only tools with readOnlyHint: true in MCP tool schema (fastmcp annotation or direct schema field).
• Validate parameters at tool entry point and return structured errors. E.g., if regimes contains invalid value, return { error: 'Invalid regime: must be one of [US, UN, EU, UK]. Got: "UNKNOWN"' } not a 500 error.