fix(mcp): guide agents to size dashboard tiles correctly (HDX-4661)

[brandon-pereira]

Summary

Agents building dashboards through the MCP clickstack_save_dashboard / patch_dashboard tools were leaving nearly every tile at the 12x4 layout default. The result is poorly proportioned dashboards: tables and search lists lose rows below the fold, number-tile KPIs are oversized and waste a whole row, and markdown notes crammed into h: 1 get clipped. There was no per-displayType sizing guidance anywhere the model reads, so it had nothing to anchor on.

This change adds tile-sizing guidance in the two places the LLM consumes context:

• packages/api/src/mcp/tools/dashboards/schemas.ts — expand the shared tile-layout w and h .describe() text with per-displayType recommended ranges (number stays small and shares a row, line/stacked_bar/pie mid-size, tables/search take the full row, heatmap mid-size, markdown h: 2-3). These descriptions surface directly in the tool's JSON schema.
• packages/api/src/mcp/prompts/dashboards/content.ts — replace the cramped h: 1 markdown advice in the TILE TYPE GUIDE with "size it to fit the text (h: 2-3)", and add design-checklist rule 14 "SIZE TILES TO FIT THEIR CONTENT" with the same per-type w/h ranges. Checklist rules stay numbered contiguously 1..14.
• packages/api/src/mcp/__tests__/dashboards/prompts.test.ts — extend the existing design-checklist test to assert the checklist now runs 1..14 and that rule 14's substantive content (per-type ranges, full-row tables) is present.

Prose stays ASCII-only (no em/en-dashes), which the existing prompts.test voice assertions enforce.

How to test on Vercel preview

N/A — non-UI change (MCP tool descriptions and prompt content only).

References

• Linear Issue: HDX-4661 ("Better Generation of Tile Heights")
• Related PRs:

  

[changeset-bot]

🦋 Changeset detected

Latest commit: bba571d

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jun 30, 2026 3:58pm
hyperdx-storybook	Ready	Preview, Comment	Jun 30, 2026 3:58pm

[greptile-apps]

Greptile Summary

This PR adds per-displayType tile-sizing guidance in two places the LLM consumes at runtime — the Zod schema field descriptions for w/h and a new rule 14 in the design checklist — to stop agents from leaving every dashboard tile at the 12x4 default.

• schemas.ts: Expanded .describe() text on w and h with concrete per-type ranges (number 6-8 / 3-4, line/pie 8-12 / 4-6, table/search 12-24 / 6-10, heatmap 12 / 5-6, markdown 2-3).
• content.ts: Updated the markdown tile description to recommend h: 2-3 instead of the old h: 1 (which clips content), and appended rule 14 "SIZE TILES TO FIT THEIR CONTENT" with the same per-type ranges.
• prompts.test.ts: Extended the design-checklist test to assert rule count is now 14 and that rule 14's key phrases are present.

Confidence Score: 5/5

Safe to merge — changes are limited to prompt text and Zod field descriptions with no runtime logic affected.

All changes are string literals in prompt content and schema .describe() calls. No runtime logic, no API surface, and no data schema is modified. The test update correctly tracks the new rule count and spot-checks key phrases. The only rough edge is a minor prose inconsistency between the schema's table / search 12-24 range and rule 14's stronger w 24 recommendation, which could leave an LLM with a slightly ambiguous lower bound for table widths, but this does not break anything.

The w description in schemas.ts for table / search (starting at 12) is slightly looser than rule 14 in content.ts (pinned to 24); aligning them would remove any ambiguity for the model.

Important Files Changed

Filename	Overview
packages/api/src/mcp/tools/dashboards/schemas.ts	Expanded w and h Zod .describe() text with per-displayType sizing ranges; minor prose inconsistency where table/search width starts at 12 here but is pinned to 24 in rule 14.
packages/api/src/mcp/prompts/dashboards/content.ts	Added rule 14 with concrete per-type w/h ranges; updated markdown tile description to recommend h: 2-3 instead of h: 1. Changes are internally consistent.
packages/api/src/mcp/tests/dashboards/prompts.test.ts	Updated rule count assertion from 13 to 14 and added targeted content assertions for rule 14 (SIZE TILES TO FIT THEIR CONTENT, number tile range, full-row tables). Coverage is appropriate.
.changeset/hdx-4661-tile-height-guidance.md	Standard changeset file for a patch release of @hyperdx/api.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[LLM calls clickstack_save_dashboard] --> B{Read tile sizing context}
    B --> C[schemas.ts w/h .describe text\nper-displayType ranges]
    B --> D[content.ts Rule 14\nSIZE TILES TO FIT THEIR CONTENT]
    C --> E{displayType?}
    D --> E
    E -->|number| F[w 6-8, h 3-4\n3-4 KPIs per row]
    E -->|line / stacked_bar / pie| G[w 8-12, h 4-6]
    E -->|table / search| H[w 24, h 6-10\nfull row]
    E -->|heatmap| I[w 12, h 5-6]
    E -->|markdown| J[w 24, h 2-3\nnever h 1]
    F & G & H & I & J --> K[Dashboard saved with\ncorrect tile proportions]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[LLM calls clickstack_save_dashboard] --> B{Read tile sizing context}
    B --> C[schemas.ts w/h .describe text\nper-displayType ranges]
    B --> D[content.ts Rule 14\nSIZE TILES TO FIT THEIR CONTENT]
    C --> E{displayType?}
    D --> E
    E -->|number| F[w 6-8, h 3-4\n3-4 KPIs per row]
    E -->|line / stacked_bar / pie| G[w 8-12, h 4-6]
    E -->|table / search| H[w 24, h 6-10\nfull row]
    E -->|heatmap| I[w 12, h 5-6]
    E -->|markdown| J[w 24, h 2-3\nnever h 1]
    F & G & H & I & J --> K[Dashboard saved with\ncorrect tile proportions]

Loading

_{Reviews (3): Last reviewed commit: "fix(mcp): reconcile search tile height g..." | Re-trigger Greptile}

[github-actions]

E2E Test Results

✅ All tests passed • 223 passed • 3 skipped • 1489s

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

Tests ran across 4 shards in parallel.

View full report →

[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: 18 (+ 23 in test files, excluded from tier calculation)
• Branch: cursor/hdx-4661-tile-height-guidance
• 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.