The mcp-pydantic-ai server exposes two weather tools (get_alerts, get_forecast) with extremely minimal documentation and incomplete schemas. Both tools have basic descriptions (10-20 characters) that fail to meet the 10-1024 character guideline for adequacy. Input parameters are defined with types but lack depth in their descriptions. The output schemas are completely undocumented, the code shows raw API responses being returned with no documented structure. Error handling is minimal (the source shows 'return None' on API failure with no guidance to the LLM). The implementation registers tools via FastMCP decorators, but the schema definitions visible in the source are incomplete and lack the rigor expected of production tools.
Tool descriptions are critically sparse (under 20 characters effective content). 'Get weather alerts for a US state' and 'Get weather forecast for a location' provide no context for WHEN to use each tool, no mention of prerequisites, and no guidance on the response structure. LLMs cannot reliably select between similar tools without distinguishing descriptions.
Output schemas are completely undocumented. The code shows calls to NWS API returning raw JSON (e.g., 'response.json()' with no structure declared). LLMs have no way to know what fields to expect, what type each field is, or how to chain results into subsequent tool calls. This violates the 100% requirement that A+ tools document return types.
Input parameter descriptions are minimal. 'state' is described as 'Two-letter US state code (e.g. CA, NY)', which includes example values, LLMs tend to reuse examples literally. Parameters should use enum constraints instead. 'latitude' and 'longitude' have no constraints on valid ranges, precision, or coordinate systems. LLMs may pass invalid values (e.g., latitude > 90).
Recommendations
Expand tool descriptions to 50-200 characters. For get_alerts: 'Fetch active weather alerts and warnings for a US state. Returns a list of active alerts with event type, severity, affected area, and guidance. Call this when the user asks about storms, warnings, or hazards in a specific state.' For get_forecast: 'Retrieve a point forecast for a specific geographic location (lat/lon). Returns hourly or daily predictions including temperature, precipitation, wind, and conditions. Use this to answer questions about expected weather at a place.'
Add enum constraint for state parameter: enum: ['AL', 'AK', 'AZ', ..., 'WY'] (all 50 states + territories). Replace the example-based description with: 'Two-letter US state or territory code (e.g., valid values: AL, AK, AZ, ... see enum for complete list).'
Add numeric range constraints for latitude/longitude: latitude must be -90 to +90, longitude must be -180 to +180. Update descriptions: 'Latitude in decimal degrees, range -90 to +90 (negative = south)' and 'Longitude in decimal degrees, range -180 to +180 (negative = west).'
Implement pagination for get_alerts. Add optional parameters: limit (default 20, range 1-100) and offset (default 0). Return response with structure: {alerts: [...], total_count: number, returned_count: number}. Document: 'When a state has many active alerts, call with limit=20 and iterate using offset to avoid overwhelming the context.'
Error handling provides no recovery guidance. The code shows 'if not data or' (truncated) and 'return None' on API failure. This tells the LLM nothing, no indication of whether the error is retryable, whether to ask the user for clarification, or what to do next. A bare None response leaves the agent dead-ended.
No pagination support. If get_alerts returns many alerts (e.g., 500+ for a large state during severe weather), they are all returned in a single response. This can blow the context window and degrade LLM reasoning. The tool lacks limit and offset/cursor parameters.
Parameter descriptions include literal examples ('CA, NY') which prompt LLMs to treat those as the only valid values or to reuse them verbatim. Patterns like 'Two-letter state code (e.g., CA, NY)' should be replaced with formal constraints: enum: ['CA', 'NY', 'TX', ...] or a pattern regex [A-Z]{2}.
get_alerts
Add explicit error handling with recovery guidance. Return JSON error responses like: {error: 'location_not_found', message: 'No forecast data available for latitude 91.5 (out of range). Latitude must be between -90 and +90.', suggestion: 'Try using a nearby valid location or check the coordinates.'} instead of bare None.
Add rate limiting and timeout handling. Document: 'This tool calls the National Weather Service API, which has rate limits. If you receive a rate limit error, wait 60 seconds before retrying. Calls timeout after 5 seconds; if this happens, it may indicate a temporary service issue.'
Validate input before making API calls. For state, reject values not in the 50-state enum with: {error: 'invalid_state', message: 'Invalid state code: XY. Must be a two-letter US state code (e.g., CA, NY). See full list: AL, AK, AZ, ...'} This enables the LLM to self-correct without wasting an API call.
Return only relevant fields. If the NWS API returns 50 fields per alert, filter to: event, area, severity, description, instructions, onset_time, expires_time. Strip audit fields, API metadata, and raw timestamps. This reduces token count and keeps the response focused.
Document when to use each tool. Add to get_alerts: 'Use when the user asks: "Are there any weather alerts?", "What warnings are active?", "Is there a storm in [state]?"' Add to get_forecast: 'Use when the user asks: "What\'s the weather forecast?", "Will it rain tomorrow?", or requests a forecast for a specific location (provide lat/lon).'