The Tempo MCP Gateway defines 1 visible tool with basic structure but significant documentation gaps. The 'list-instances' tool has a short description (87 chars, within the acceptable 10-1024 range) and a clear action verb, but the input schema is empty (no parameters documented), which is a critical flaw. Tool annotations are present (readOnlyHint=true, destructiveHint=false, openWorldHint=false), which is good, but parameter descriptions are entirely absent. The server registers proxied tools dynamically from remote Tempo instances, adding complexity that is not well-documented in the base tool definitions. Error handling in the visible code returns error strings via mcp.NewToolResultError(), which is minimal, no guidance on recovery actions or error categorization. The tool follows a sensible verb_noun pattern ('list-instances'), matching baseline conventions, but lacks the parameter-level documentation required for production-grade agents. The descriptions meet length requirements but lack the 'WHAT/WHEN/WHY' depth that LLMs rely on for tool selection context.

• Add formal input schema documentation to list-instances. Even with zero parameters, explicitly declare mcp.WithSchema with an empty properties object and a clear type=object declaration.
• Document the output structure of list-instances: define the instances array schema (field names, types, example values like namespace, name, tenants, mcpEndpoint). Return structure should include all fields downstream tools (proxied tools) will need.
• Enhance the tool description for list-instances to ~100-150 chars, answering: 'Lists all Tempo tracing instances in the Kubernetes cluster, including their namespace, name, configured tenants, and MCP endpoint. Call this first to discover available instances before querying specific instance tools.'
• For each proxied tool, document the three injected parameters (tempoNamespace, tempoName, tenant) in the base tool definition comments or via a helper function that generates consistent parameter descriptions.
• Implement structured error messages: categorize errors as retryable (e.g. 'Tempo instance unreachable. Retry or check cluster connectivity.') vs user-fixable (e.g. 'Invalid namespace: got "default-foo". Available: default, monitoring.') vs fatal (e.g. 'No ready Tempo instances found.').
• Add an OnBeforeCallTool validation handler that checks tempoNamespace and tempoName against discovered instances and returns an early error with available options if not found, preventing unnecessary proxy calls.
• Document the pagination behavior for large clusters: if instances can exceed ~20, add limit/offset parameters to list-instances and implement result capping per the 'enforce-result-limits' pattern.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry