MBTA MCP demonstrates solid tool design with clear naming (verb_noun pattern), comprehensive descriptions (100-250 chars each), and well-structured input schemas. All 6 tools follow consistent patterns and include parameter type definitions. However, output schemas are not documented in the visible code, and error handling guidance is minimal. Tool descriptions are good but could be more concise per LLM-optimization baselines (50-200 chars). No tool annotations (readOnlyHint, destructiveHint) are present despite all tools being read-only operations.

• Add explicit output schemas to each tool definition. Document the response structure, field types, and any pagination metadata. Example: 'Returns an array of route objects with fields: id (string), name (string), type (integer), description (string).'
• Add readOnlyHint: true to all 6 tool definitions in the MCP server code (likely in src/mbta_mcp/tools/*.py). This signals to clients that these tools are safe to cache and retry.
• Replace example values in parameter descriptions with enum constraints or format patterns. For route_id, use an enum or pattern like '^[A-Za-z0-9-]+$' instead of listing 'Red, Orange, Green-B, or 1'.
• Add error recovery guidance to tool descriptions. Example for find_stop: 'If no results, try a shorter or partial name. If still no match, use get_stops_for_route() with a known route_id.'
• Document pagination for get_routes and get_vehicles. Add limit and offset parameters (or cursor), and return total_count in the response. State the default and maximum limits in the description.