kra-mcp defines 6 tax-compliance tools with basic schemas and descriptions. All tools are READ_ONLY and DEMO-marked. Naming follows verb_noun convention (paye_calculator, pin_registration_guide, vat_guide, tax_filing_calendar, withholding_tax_rates, tax_incentives_guide). Descriptions are present (avg ~80 chars) but generic and lack actionable context for LLM selection. Input schemas are visible with type declarations, but most parameters lack detailed constraints (enums, ranges, format hints). Output schemas are not documented, LLMs cannot predict response structure. Error handling is absent; no recovery guidance. Parameter descriptions are minimal (e.g., 'Query about VAT' does not explain valid query values or expected response). No tool demonstrates idempotency, pagination, or composition patterns. Overall: functional but below production baseline.

• Document output schemas for all tools. Example for paye_calculator: {gross_annual: float, net_paye_annual: float, net_paye_monthly: float, nhif_annual?: float, nssf_annual?: float, breakdown: [{band_kes: float, rate_pct: float, tax_kes: float}], source: string}.
• Convert free-form parameters to enums. vat_guide(query) should accept enum: ['registration', 'rate', 'filing', 'refund', 'withholding_vat']. withholding_tax_rates(payment_type) should enumerate all valid types.
• Expand descriptions to 100 - 200 chars with actionable context. Example: 'Calculate Kenya PAYE tax for 2025. Returns annual/monthly tax, NHIF, NSSF, and tax breakdown by bracket. Use this to estimate employee payroll costs. DEMO data only, verify at itax.kra.go.ke for production.'
• Add error handling with recovery hints. If applicant_type is invalid, return: 'Invalid applicant_type. Must be "individual" or "company". Received: "xyz".'
• Provide a data freshness/production upgrade path. Document when tax brackets, rates, and deadlines are last updated and how to switch from DEMO to live KRA API data.