This server provides two simple weather tools with basic input schemas and minimal descriptions. Both tools are directly visible in main.py with explicit @mcp.tool() decorators. However, there are significant gaps in parameter descriptions, no output schemas documented, no error guidance for LLMs, and descriptions are generic without context on when to use each tool. The tools lack the depth and rigor expected of production-grade agents tools. Parameter descriptions exist but are minimal (under 50 chars each). No structured output documentation, no error classification, no guidance on partial failures or retries.
Parameter descriptions are minimal (under 20 chars). The 'state' parameter in get_alerts only says 'Two-letter US state code (e.g. CA, NY)' with no guidance on what happens if an invalid code is passed, whether it's case-sensitive, or what valid codes are. No enum constraint provided.
Error handling responses are generic strings ('Unable to fetch alerts or no alerts found') with no actionable recovery guidance. LLMs cannot distinguish between 'API is down', 'invalid input', 'rate limited', or 'no data exists'. Error messages should classify the failure type and suggest next steps.
Add enum constraint to 'state' parameter. Replace the example-based description with: state: {type: 'string', enum: ['AL', 'AK', 'AZ', ...all 50 states], description: 'Two-letter US state code'}. This self-documents valid values and prevents invalid input.
Add numeric range constraints to latitude and longitude: latitude {type: 'number', minimum: -90, maximum: 90, description: 'Latitude of the location (-90 to 90)'} and longitude {type: 'number', minimum: -180, maximum: 180, description: 'Longitude of the location (-180 to 180)'}.
Enhance tool descriptions to 50-200 characters with context: get_alerts: 'Fetch active weather alerts and severe warnings for a US state. Use this when users ask about current emergencies, watches, or warnings. Returns event type, affected area, severity level, and instructions.' get_forecast: 'Get a 5-day hourly weather forecast for any geographic location (latitude/longitude). Returns temperature, wind, and detailed conditions. Call this for weather planning or user questions about upcoming conditions.'
Tool descriptions lack context on WHEN to use each tool. 'Get weather alerts for a US state' doesn't explain whether to call this for current emergencies, or if there are alternatives. A production description should answer: what data does it return? When is it most useful? What are the prerequisites?
No documented constraints on numeric parameters. The 'latitude' and 'longitude' in get_forecast accept floats with no stated range (-90 to 90 for lat, -180 to 180 for lon). No validation or clear error if coordinates are out of bounds (e.g., latitude=999).
Results are truncated without pagination. get_forecast() slices to only 5 periods (hardcoded [:5]). If users want extended forecasts, they have no way to request them. No limit parameter, no next_cursor, no total count returned.
No timeout or rate-limit handling documented. The code sets a 30s timeout on httpx calls, but if the NWS API is slow or rate-limits responses, the tool will return generic 'Unable to fetch' with no indication of whether retrying is safe or if the agent should back off.
get_alertsget_forecast
Improve error messages with classification and recovery guidance. Replace 'Unable to fetch alerts or no alerts found' with either: (a) 'No active alerts for {state}. This is normal when no severe weather is occurring.' OR (b) 'Weather.gov API is temporarily unavailable. Retry in 30 seconds.' OR (c) '{state} is not a valid US state code. Use two-letter codes like CA, NY, TX.' Include the invalid value and valid options.
Add a 'limit' parameter to get_forecast to allow requesting more than 5 periods (default 5, max 10 to prevent context bloat). Document the limit in the description: 'Maximum forecast periods to return (1 - 10, default 5). Longer forecasts consume more tokens.'
Add explicit timeout and rate-limit handling. If httpx.get() raises a Timeout exception, return: 'Weather.gov API is responding slowly. This may indicate the service is under high load. Please retry in 10 - 30 seconds.' For rate-limit errors (429), return: 'Rate limit reached. Weather.gov allows 150 requests per hour. Please wait before retrying.' This teaches LLMs whether to retry immediately or back off.
Document the 30-second timeout in the tool description or in a 'limits' section. E.g., 'Note: This tool has a 30-second timeout. If the service is unresponsive, it will fail gracefully with a clear message.'