tfl-ts MCP server presents a well-structured tool collection with strong naming conventions and comprehensive parameter schemas. All 7 tools follow verb_noun patterns (get_*, resolve_*, plan_*), descriptions are consistently present and informative (avg ~100 chars), and input schemas are formally defined with JSON Schema. Parameter descriptions are detailed and include practical guidance (e.g., 'resolve_stop_id' explains the 490G hub expansion for bus mode; 'docs' includes operation guidance). However, there are notable gaps: (1) Output schemas are entirely undocumented, no tool specifies what fields the response will contain, breaking pattern:tool and pattern:response-shaper; (2) Error handling is minimal, no error recovery guidance, no retryable vs fatal classification; (3) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) present despite all tools being read-only; (4) Some parameter relationships are undocumented (e.g., 'docs' anyOf constraints could be clearer); (5) Missing batch/pagination patterns on list operations. Tools are clearly callable and well-named, but the absence of documented output structure is a significant production gap.

• Add explicit output schema definitions to all 7 tools. At minimum, define the response as a TypeScript interface in code comments, then document in the tool description. Example for get_arrivals: 'Returns {arrivals: Array<{line: string, towards: string, minutes: number, platform?: string}>}'.
• Document error conditions for API-calling tools (resolve_stop_id, get_line_status, get_arrivals, plan_journey). Specify which errors are transient (retry suggested) vs permanent (invalid input, missing resource). Example: 'Returns 400 if stopPointId is invalid, check with resolve_stop_id first.'
• Add readOnlyHint annotations to all 7 tool definitions in the MCP protocol response (tools response includes 'annotations': {readOnlyHint: true}). This tells agents these tools are safe for concurrent execution and caching.
• Refine 'plan_journey' from/to parameter description to specify accepted formats with examples: 'Stop ID (e.g. "940GZZLUOXC"), postcode (e.g. "SW1A1AA"), or lat,lng string (e.g. "51.5074,-0.1278"). Use resolve_stop_id or a postcode lookup first if you only have a name.'
• Add limit parameter to 'docs' list operation with sensible default (e.g. limit=50) and document max result set size. Return total_count in response so agents know when to paginate.
• Document cache TTLs in tool descriptions as promises, not implementation details. E.g., 'Results are cached for 60 seconds, if you need fresher data, retry after a short delay.' This sets agent expectations for freshness.
• Consider batch variants for tools used in loops. E.g., add 'get_arrivals_batch' accepting array of stopPointIds, returning keyed results. Reduces token overhead for common patterns like 'show arrivals for all nearby stops.'