A repository containing MCP servers demonstrating remote and local agents with tool integration. Includes a temperature sensor server and weather service server.
Three tools with basic schemas but significant quality gaps. All three have action-verb names (get_temperature, get_alerts, get_forecast) which is good. However, tool descriptions are minimal (10-20 chars), parameter descriptions are absent or trivial, and output schemas are completely undocumented. No error handling guidance. Tool composition is reasonable (three distinct weather operations), but LLM-facing quality falls well below production baseline. The server exposes parameter descriptions in some cases (e.g., 'Two-letter US state code (e.g. CA, NY)' for get_alerts, 'Latitude of the location' for get_forecast) but these are vague and lack constraints. get_temperature has zero input parameters but no output schema documentation. Overall definition quality is D-tier (50-59 calibration).
No output schemas documented for any tool. LLMs cannot infer what fields to expect in responses, making it impossible to chain tools or extract specific data reliably.
Tool descriptions are too short (10-20 chars). Current descriptions are bare-minimum docstrings ('Read the current temperature from the sensor.'). They lack context for LLM selection.
Parameter descriptions are generic or missing constraints. get_alerts accepts 'state' with description 'Two-letter US state code (e.g. CA, NY)' but no enum constraint and no guidance on error handling (what if invalid state is passed?). get_forecast longitude/latitude lack range constraints (±180 for longitude, ±90 for latitude).
get_alertsget_forecast
Recommendations
Expand tool descriptions to 100-150 chars. Example for get_temperature: 'Fetch the current ambient temperature reading in Celsius from the deployed sensor hardware. Use this to monitor real-time environmental conditions. Returns temperature as a decimal value.'
Add output schemas to all three tools. get_temperature should document it returns {type: string, description: 'Temperature reading in format "Current temperature is {value} °C"'} or better yet, return JSON: {temperature_celsius: number, timestamp: string}. get_alerts should return {type: array, items: {type: object, properties: {event, area, severity, description, instructions}}, description: 'Array of active weather alerts for the specified state.'}
Add enum constraint for state parameter in get_alerts. Collect valid US state codes (CA, NY, TX, etc.) and declare as enum: ['AL', 'AK', 'AZ', ..., 'WY']. Include description: 'Two-letter US state abbreviation. Must be a valid state code.'
Add range constraints for get_forecast latitude/longitude. Document: 'latitude: number between -90 and 90 (degrees North)' and 'longitude: number between -180 and 180 (degrees East)'.
No error guidance. If NWS API fails (network timeout, invalid coordinates, rate limit), tools return bare strings like 'Unable to fetch alerts or no alerts found.' LLM has no guidance: should it retry? Ask user? Try a different tool?
Unstructured text responses. get_alerts and get_forecast return formatted strings ('Event: ...\nArea: ...\nSeverity: ...') instead of structured JSON. LLMs must parse unstructured text, wasting tokens and increasing hallucination risk. Should return arrays of alert/forecast objects with typed fields.
No pagination for get_alerts. If a state has 100+ active weather alerts, all are returned in a single concatenated string. Large responses blow context windows. Should accept limit and offset/cursor parameters and document result cap.
get_alerts
Add error classification and recovery guidance. Example: if NWS API times out, return {error: 'unable_to_fetch', message: 'Weather service did not respond within 30 seconds. The service may be overloaded. Try again in 10 seconds or contact the weather service admin.', retryable: true}. If coordinates are invalid, return {error: 'invalid_coordinates', message: 'Latitude must be -90 to 90, longitude must be -180 to 180. Got latitude={lat}, longitude={lon}.', retryable: false}.
Add pagination to get_alerts. Accept parameters: limit (1-100, default 20), offset (default 0). Return {alerts: [...], total_count: number, offset: number, limit: number, has_more: boolean} so agent can request additional pages.
Document when each tool should be used. Add context: get_temperature is for current conditions; get_alerts for urgent warnings; get_forecast for planning. This helps LLM choose the right tool.
Consider adding a get_weather_summary tool that combines current temp, active alerts, and short forecast in one call for common use cases (reduces multi-step agent reasoning).