fix(mcp): improve alias descriptions and examples for readable chart legends

[brandon-pereira]

Fixes HDX-4453

Problem

When the MCP generates dashboard tiles or query charts, series legends often show raw ClickHouse expressions like count() or quantile(0.95)(Duration) instead of human-readable labels. This happens because:

1. The alias field description in the JSON schema was minimal ("Display label for this series") with no urgency to include it
2. All 5 example tiles in mcpTilesParam omitted aliases entirely — LLMs copy these patterns

Changes

• Add aliases to every example tile in mcpTilesParam (except heatmap which doesn't use aliases): "Errors", "Requests", "Avg Duration", "P95 Latency"
• Expand the alias field description in both dashboard and query schemas to explain what aliases are used for (legends, table headers, CSV exports, onClick templates) and what happens without them (raw ClickHouse expressions in the UI)

These are description-only changes to the Zod schemas — no runtime behavior changes. The JSON schema description is what every MCP client sees on every tool call, making this the highest-impact place to guide LLMs toward always including aliases.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jun 4, 2026 5:31pm
hyperdx-storybook	Ready	Preview, Comment	Jun 4, 2026 5:31pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 3e01388

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 2
• Production lines changed: 26
• Branch: brandon/brandon-mcp-alias-tweak
• Author: brandon-pereira

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

E2E Test Results

✅ All tests passed • 194 passed • 3 skipped • 1327s

Status	Count
✅ Passed	194
❌ Failed	0
⚠️ Flaky	5
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

Deep Review

✅ No critical issues found.

This is a description-only change: expanded alias field .describe() text in two Zod schemas plus alias keys added to the example tiles embedded in mcpTilesParam. .describe() does not affect validation, and the example JSON lives inside a description string that is never parsed, so the no-runtime-behavior-change claim holds. Reviewers confirmed all five example tiles parse as valid JSON and satisfy mcpTileSelectItemSchema (including its superRefine), the single-quote escaping inside the JS strings is well-formed, and the description's factual claims (alias drives legends, table column headers, and onClick templates; heatmap is the lone exception) match the actual UI/handlebars code.

🔵 P3 nitpicks (1)

• packages/api/src/mcp/tools/dashboards/schemas.ts:105 — the expanded alias description shares three lines verbatim with mcpSelectItemSchema in packages/api/src/mcp/tools/query/schemas.ts, so future edits to the alias guidance must be made in two places and can silently drift apart.
  • Fix: extract the shared lead text into a single exported constant and append the dashboards-only heatmap sentence at that call site.

---

Reviewers (5): correctness, testing, maintainability, project-standards, kieran-typescript.

Testing gaps: No automated test asserts that the example tiles embedded in mcpTilesParam parse and validate against mcpTileSchema/mcpTileSelectItemSchema, so a future schema-shape change could desync the examples from the live schema without CI catching it.