Server has 2 tools with clear naming (verb_noun format) and functional schemas using Zod, but descriptions are minimal and lack LLM-optimization guidance. Parameters are typed and constrained but descriptions do not explain WHEN to use each tool, prereq conditions, or what distinguishes them. Output is text-only (free-form) with no structured schema documentation. No error recovery guidance. Averages to Fair (C), noticeable gaps in descriptions and output documentation, but schemas are present.
Descriptions are minimal (35-38 chars) and lack LLM-optimization. Do not explain WHEN to use each tool, prerequisite conditions (US-only), or what data is returned. Below 50-200 char baseline for A+ tools.
get-alerts input includes example values ('CA, NY') in description instead of enum constraint. LLMs will reuse examples literally, passing invalid states like 'ZZ'. Should declare enum of all 50 US state codes.
Coordinate precision and format not documented. Code rounds to 4 decimals (toFixed(4)); description does not explain this. Non-US coordinates silently fail with a text error message, no structured error or recovery guidance (e.g., 'Try a US city like San Francisco, CA').
Recommendations
Expand tool descriptions to 50-200 chars. Example: 'Get active weather alerts for a US state (passed as 2-letter code). Alerts include event, area, severity, status, and headline. Call this when the user asks about severe weather, emergency alerts, or warnings for a state. Returns text-formatted alerts. US locations only (NWS API).'
Add structured output schema documentation. Define the forecast response as an array of {name, temperature, unit, windSpeed, windDirection, shortForecast} objects. Define alerts as {event, area, severity, status, headline}. Document these in tool docstrings or return value specs.
Replace example values in parameter descriptions with enum constraints. For get-alerts, create an enum of all 50 US state codes (AL, AK, AZ, ..., WY). This prevents invalid state codes and is machine-parseable.
Add error categorization and recovery guidance. When coordinates are out of bounds or invalid, return: 'Invalid latitude: must be -90 to 90. If you have a city name, try searching for its coordinates first.' When NWS API is unreachable, return: 'NWS API temporarily unavailable. This is retryable, try again in 30 seconds.'
Document coordinate precision. Add to get-forecast description: 'Coordinates should be decimal degrees (e.g., 37.7749 for San Francisco). Precision: ~0.0001 degrees (~10 meters). Only US locations are supported.'
Add pagination support to get-alerts. If a state has many alerts, return a paginated response with a limit parameter (default 20) and a next_cursor field. Document in the tool description: 'Large states may have many alerts. Use the limit parameter to control results; use next_cursor to fetch more.'
No error categorization or recovery guidance. When makeNWSRequest fails, tools return generic 'Failed to retrieve...' text. LLM does not know: is this retryable? Should I ask the user for different coordinates? Or is the service down?
No tool composition. get-forecast returns unstructured forecast text; agents cannot filter by date, extract next-day forecast, or compare with alerts from get-alerts. Responses are chat-oriented (human-readable text) rather than agent-oriented (structured data + references).
No pagination or result limits documented. If a state has 100+ active alerts, get-alerts returns all in one unstructured text block. get-forecast may return 50+ forecast periods. No mention of limit in descriptions or pagination support.
get-alertsget-forecast
Consider returning structured JSON instead of free-form text. Return tools that produce {alerts: [{event, area, severity, status, headline}]} or {forecast: [{name, temperature, tempUnit, windSpeed, windDir, shortForecast}]}. This enables downstream tool composition (filter by severity, extract next 3 days, etc.).
Document idempotency. Both tools are read-only and should always return the same result for the same input. Add a note: 'Idempotent, calling with the same coordinates/state multiple times always returns the current forecast/alerts.' This assures agents they can retry safely.