Housing Intel MCP has 5 tools with basic schemas and descriptions, but significant gaps prevent production use. All tools have descriptions (10-60 chars, below the 50-200 char baseline for LLM optimization) and input schemas with typed parameters. However, descriptions are generic and lack actionable context (e.g., 'macro market overview' does not explain WHEN to call this vs. housing_affordability_check). No output schemas are documented, LLMs cannot plan downstream calls or extract structured data. Parameters lack descriptions entirely (metro, bedrooms, income have no guidance on format, range, or valid values). Error handling is minimal, no recovery guidance, no categorization of retryable vs. fatal errors. Tools follow a read-only pattern but lack idempotent/readOnly annotations. No composition guidance (e.g., which tool chains together). Naming is verb-noun compliant but generic (housing_* prefix adds little signal).

• Add output schemas to all tools. Document the structure of market_data, property_details, rental_metrics, affordability_score, and employment_indicators. Include field types, descriptions, and example values.
• Expand tool descriptions to 50-200 chars with WHEN/WHY context. E.g., 'Get current mortgage rates, home price trends, and inventory levels for a metro area. Use this first to understand market conditions before analyzing specific properties.'
• Add descriptions to all parameters. For 'metro', specify: 'Metro area name (lowercase, e.g., austin, boston, denver). See METRO_CBSA map for valid values.' For 'bedrooms', specify: 'Number of bedrooms (1-5). Rental analysis uses this to filter comparable properties.'
• Implement error recovery guidance. Catch API errors and return actionable messages: 'ATTOM could not find address. Try: (1) verify street spelling, (2) use city name instead of metro, (3) include ZIP code.' Reference the existing ATTOM hint logic.
• Add tool annotations to the McpToolDefinition interface: readOnlyHint: true for all tools. This signals to LLMs that these tools are safe to call without confirmation and can be retried on failure.