Four well-named tools with strong, LLM-optimized descriptions (150 - 250 chars each). All tools have complete input schemas with proper types, ranges, and defaults. Naming follows verb_noun pattern (sec_8k_*). Descriptions include WHEN to use each tool and differentiate from alternatives (e.g., 'PREFER OVER WEB SEARCH'). However, output schemas are not documented, LLMs cannot see what fields to expect from responses. No error handling guidance. No tool annotations (readOnlyHint, etc.). Parameter descriptions are good but could specify format constraints more explicitly (e.g., ticker format validation).

• Add output schema documentation to each tool. Define EventRow structure with field types and descriptions: accession_number (string), filed_at (ISO 8601 date), ticker (string), items (array of strings), severity (enum: high|medium|low|noise), summary (string|null). This enables LLMs to extract and chain results.
• Implement error handling with recovery guidance. Catch Supabase auth errors (401) and return 'Supabase credentials not injected. Ensure injectSupabase:true on gateway registration.' For 404 (no filings found), return 'No 8-K filings found for ticker AAPL in the last 30 days. Try expanding days parameter or checking ticker spelling.' For network timeouts, return 'Mirror service timeout. Retry in 30 seconds.'
• Add readOnlyHint: true to all tool schemas. This signals to MCP clients that these tools are safe to cache and retry without side effects.
• Convert ticker parameter to accept both uppercase and lowercase, with validation. Add pattern constraint or enum if possible. If free-form, validate in callTool() and return 'Invalid ticker: APPLE. Did you mean AAPL?' to guide LLM self-correction.
• Convert severity parameter in sec_8k_today to an enum array instead of comma-separated string. Change inputSchema to: severity: { type: 'array', items: { enum: ['high', 'medium', 'low', 'noise'] }, default: ['high', 'medium'] }. This prevents invalid values and is more machine-parseable.