otlp-mcp demonstrates a well-intentioned design focused on snapshot-centric observability, but suffers from incomplete schema documentation, inconsistent parameter descriptions, and missing guidance on tool interactions. The tool naming is clear and verb-driven (get_, create_, add_, remove_, query, manage_, clear_), which is excellent. However, the source code excerpt is truncated at a critical point, the actual parameter schemas and output types are cut off mid-sentence ('OTLP gRPC endpoint address (accepts traces, logs, and metr'). This prevents full assessment of schema quality. Based on visible code: 6 of 9 tools have descriptions; input schemas are declared in Go struct types but not fully visible in the excerpt; parameter types are strongly-typed in Go but descriptions are sparse or missing. Error handling and recovery guidance are absent. The 'query' tool has the most complex schema (12+ parameters) but lacks clear documentation on mutually exclusive fields or how attribute filtering interacts. The destructive 'clear_data' tool has no confirmation pattern.

• Add complete output schemas (return type, field descriptions, example values) for all 9 tools. For get_stats, document the exact fields (e.g., 'buffer_utilization_percent': number, 'event_count': number, 'oldest_event_timestamp': string). For query, document whether results are grouped by signal type and what fields each signal type includes.
• Split manage_snapshots into two tools: list_snapshots (no input, returns array of snapshot metadata) and delete_snapshot (required name parameter, returns deletion confirmation). This follows single-responsibility and makes each tool's contract clear.
• Replace example values with enum constraints. For log_severity, document as enum: ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'] rather than 'INFO, WARN, ERROR, etc'. For snapshot names, document the character constraints (alphanumeric + hyphen, max 64 chars) instead of listing examples.
• For the query tool, explicitly document filter logic: Are filters AND-ed or OR-ed? Is 'errors_only' a shortcut that conflicts with 'span_status' (i.e., cannot both be specified)? Does 'has_attribute' match attribute keys substring or exact? Document the output structure: is it { traces: [], logs: [], metrics: [] } or a flat list with a 'type' discriminator?
• Add recovery guidance to every tool. For add_otlp_port, document: 'If the response is "port already in use", try a different port or call get_stats to see active ports.' For query, if results are empty: 'Try relaxing filters: remove span_status filter or expand the time range.' For clear_data: add a confirmation pattern, document a required parameter 'confirm_wipe=true' that the agent must explicitly pass, not infer.