InsuranceXDate MCP exposes 17 tools with complete input schemas and descriptions. Naming follows verb_noun convention (search, match, filter). However, descriptions are inconsistent in depth, some tools like 'search' have extensive parameter documentation (1000+ chars), while others like 'account_status' and 'flagged_companies' have minimal descriptions (20-30 chars). Parameter schemas are well-typed with enums where appropriate (filter.param, policyoptions, addloptions). Critical gap: output schemas are not documented anywhere in the source, LLMs cannot predict response structure. Error handling is absent; no guidance on retryability, user-fixable vs fatal errors, or recovery paths. Write operations (add_note, set_flag) lack confirmation patterns despite being destructive. Paid/gated tool separation is well-architected but not reflected in tool descriptions.

• Document output schemas for all search/lookup tools. Example: 'Returns {companies: [{uid, name, state, premium, employees, carrier}], total, nextOffset}'. This enables LLMs to chain results to company_details.
• Expand descriptions on list/discovery tools to 80-150 chars. Example: 'account_status' → 'Check your prepaid XChange account balance and remaining credits. Call before expensive operations like company_details to avoid overspend.'
• Add cost/gating metadata to descriptions. Example: 'company_details (paid $0.25 per call)' and 'serff_filing (gated, requires account access)'. Help LLMs budget calls.
• Implement confirmation pattern for write operations. Add optional 'dry_run' parameter to add_note and set_flag, or require explicit 'confirm=true' with clear description of consequences.
• Add error guidance to search tools. Example: 'If no results, try broadening date range or removing class/SIC filters. Premium/mod filters only work in 8 states (CO, GA, IL, NV, NJ, OK, TX, VT).'