The Weather MCP server defines 2 tools with basic schemas and descriptions. Both tools follow correct naming conventions (verb_noun: get-alerts, get-forecast) and have descriptions present. However, descriptions are minimal (under 100 chars), parameter descriptions lack critical guidance, output schemas are undocumented, and error handling is minimal. The server lacks structured output documentation, pagination guidance, and error recovery hints. Tool implementations show reasonable input validation logic but schemas are incomplete relative to production quality baseline (194 char avg tool description, 72 char avg param description in arcade baseline).
Output schemas are not documented in the MCP tool definition. Callers cannot know what fields are returned (text only? JSON structure?). Per pattern:tool, LLMs need documented output schemas to plan downstream calls and extract data.
Parameter 'state' in get-alerts lacks format/constraint documentation. Description says 'Two-letter state code (e.g. CA, NY)' but provides example values instead of enum or pattern. '^[A-Z]{2}$') rather than examples.
Latitude/longitude parameter descriptions lack range documentation. While code validates -90..90 and -180..180, descriptions do not state these constraints.
Recommendations
Expand tool descriptions to 100-150 characters. For get-alerts: 'Get active weather alerts for a US state. Returns formatted alert summaries (capped at 20) with event, severity, and headline. State must be a valid 2-letter code. Use this to inform users of critical weather events.' For get-forecast: 'Get hourly/daily forecast for a US location. Requires lat/lon coordinates; accepts only continental US. Returns temperature, wind, and short forecast for each period. Call after geocoding a city name.'
Add explicit enum or pattern constraint to 'state' parameter. Change description to: 'Two-letter US state code (e.g., CA, NY, TX). Must match [A-Z]{2}.' Better yet, add JSON Schema enum: ["AL", "AK", ..., "WY"] or a pattern: "^[A-Z]{2}$".
Add range constraints to latitude/longitude descriptions: 'Latitude of the location in decimal degrees. Must be between -90 and 90.' and 'Longitude of the location in decimal degrees. Must be between -180 and 180.'
Document output schema for both tools. Add to the tool definition or in descriptions: 'Returns a text summary with formatted alerts separated by dashes.' or return structured JSON (array of {event, area, severity, status, headline} objects) and document it.
Improve error messages with recovery guidance. Instead of 'Failed to retrieve alerts data', return 'Could not fetch alerts for state "{state}". Verify the state code is valid (e.g., CA, NY) and that you have network access. If valid, the NWS API may be unavailable; try again in a moment.' This tells the LLM what went wrong and what to try.
Error responses are plain text without recovery guidance. E.g., 'Failed to retrieve alerts data' gives no actionable next step. Per pattern:recovery-guide, errors should tell LLM what to try next (e.g., 'state code not found; verify it is a valid two-letter US state code').
No pagination or result limiting guidance. get-alerts caps at 20 items in code but description does not mention this limit. get-forecast returns all periods without guidance on typical result size. Per pattern:paginated-result, tools returning lists should document limits and pagination options.
No tool composition guidance. If an LLM has coordinates from a map tool, it can call get-forecast directly. But if it only has a city name, there is no mention of a geocoding tool or where to look up coordinates. Per pattern:tool-chain, tool A's output should contain references tool B needs, with guidance.
get-forecast
Document the 20-alert limit in get-alerts description: 'Get active weather alerts for a US state (max 20 most recent). Returns formatted alert summaries...'
Add a note in tool descriptions about geographic scope. Both tools only work for US locations; document this clearly: 'Note: This tool only returns data for continental US locations. For coordinates outside the US, the National Weather Service API will return an error.'
Consider adding a geocoding tool or document in descriptions how to get coordinates. E.g., 'To forecast a city by name, first use a geocoding service or map tool to get its latitude and longitude, then call get-forecast.'
Return structured JSON objects instead of plain text. E.g., get-alerts should return {"state": "CA", "alerts": [{"event": "...", "area": "...", "severity": "...", ...}, ...]} and get-forecast should return {"latitude": 40.7, "longitude": -74.0, "forecast": [{"period": "Tonight", "temperature": 45, ...}]}. This enables downstream tool composition and avoids LLM parsing errors.