Server defines 6 tools with complete Zod schemas and descriptions. Naming follows verb_noun pattern (pyroscope_*). Descriptions are present but generic (10-80 chars, below 194-char baseline). Parameters have types and basic descriptions, but lack actionable constraints, examples, and error recovery guidance. Output is text-wrapped rather than structured. No tool annotations (readOnlyHint, etc.). Error handling is minimal, raw HTTP errors returned without recovery hints.

• Expand tool descriptions to 100-200 chars. Include WHAT (query Pyroscope for profile data), WHEN (use after identifying service/time range), and WHAT IT RETURNS (flamegraph JSON or label list). Example: 'Query Pyroscope flamegraph data for a service over a time range. Returns profile structure with stack traces. Call after pyroscope_label_names to discover available services.'
• Add readOnlyHint: true to all 6 tools in server.tool() registration. This signals to agents that these are safe, non-destructive queries.
• Document parameter formats explicitly. For 'matchers', add: 'Array of Prometheus-style matchers, e.g. ["service_name=\"api\"", "env=\"prod\"]". For 'endpoint', add: 'Connect API path, e.g. /querier.v1.QuerierService/LabelNames. See Pyroscope docs for full list.'
• Return structured output instead of text-wrapped JSON. Modify response to return { content: [{ type: 'text', text: '...' }], metadata: { result_type: 'flamegraph', fields: [...] } } or parse JSON and return typed objects.
• Enhance error handling with recovery hints. Catch HTTP errors and return: { error: 'Pyroscope unavailable (503)', retryable: true, hint: 'Service may be restarting. Retry in 5s.' } or { error: 'Invalid query syntax', retryable: false, hint: 'Check query format. Example: process_cpu:cpu:nanoseconds{service_name=\"api\"}' }