[brandon-pereira]

Summary

Improves MCP tool metadata so clients and tool directories that validate it strictly see well-formed tools.

• clickstack_save_source.highlightedRowAttributeExpressions had no type. It shared a Zod schema instance with highlightedTraceAttributeExpressions, and the Zod-to-JSON-Schema conversion emits a reused instance as a bare $ref to its first use. The schema is now built by a factory, so each parameter is fully typed.
• Tools now set annotations.title. Every tool already had a top-level title; createRegisterTool now mirrors it into annotations.title, which some clients read for display names.

Both are covered by new tests: no top-level tool parameter may render as a bare $ref, and every tool's annotations.title must match its title.

How to reproduce

Starting point: local checkout, packages/api.

On main:

1. Call tools/list on the MCP server and inspect clickstack_save_source's input schema: highlightedRowAttributeExpressions is { "$ref": "#/properties/highlightedTraceAttributeExpressions" } with no type, and no tool has annotations.title.

On this branch:

1. yarn ci:unit src/mcp/__tests__/toolSchemas.test.ts src/mcp/__tests__/toolAnnotations.test.ts passes; the parameter is a typed array and every tool has annotations.title.

References

• Linear Issue:
• Related PRs:

[changeset-bot]

🦋 Changeset detected

Latest commit: 105aff4

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
hyperdx-oss	Ready	Preview	Nov 10, 2026 9:31pm UTC
hyperdx-storybook	Ready	Preview	Nov 10, 2026 9:31pm UTC

[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: 60 (+ 29 in test files, excluded from tier calculation)
• Branch: brandon/brandon-improve-tool-attributes
• 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]

PR Review

✅ No issues found.

[github-actions]

Duplicate code analysis

No new duplicate code introduced by this PR.

---

jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 110 in total (1.20%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

[github-actions]

Deep Review

✅ No critical issues found. This is a tightly-scoped MCP metadata fix: a shared Zod schema constant becomes a per-use factory so both highlighted-attribute params render fully typed instead of the second collapsing to a bare $ref, and createRegisterTool mirrors each tool's top-level title into annotations.title. Reviewers independently confirmed the Zod-accepted input shape is byte-for-byte unchanged (serialization/metadata only, backward-compatible), the annotations spread builds a fresh object per call (no mutation of the shared behavior-hint presets), and the spread precedence correctly lets an explicit config.annotations.title win. Both behaviors are covered by new tests.

🔵 P3 nitpicks (1)

• packages/api/src/mcp/__tests__/toolAnnotations.test.ts:31 — the new annotations.title test omits the expect(tools.length).toBeGreaterThan(0) guard present in every sibling test, so it would pass vacuously on an empty tool list; the regression is only caught indirectly by the guarded sibling at line 11.
  • Fix: add expect(tools.length).toBeGreaterThan(0); after listTools() to match the sibling tests.

---

Reviewers (6): correctness, testing, maintainability, kieran-typescript, api-contract, project-standards.

Testing gaps:

• No test asserts the spread precedence direction when a tool supplies its own annotations.title (current test only checks that annotations.title equals title, not that an explicit annotation value is preserved over the mirror).
• The $ref regression test checks only top-level parameters; a reused schema instance nested inside a property would still emit a bare $ref and escape the guard — out of scope for the top-level bug being fixed, but the guardrail does not cover the broader structural pattern.

_{No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond}

[github-actions]

E2E Test Results

✅ All tests passed • 466 passed • 1 skipped • 1382s

Status	Count
✅ Passed	466
❌ Failed	0
⚠️ Flaky	0
⏭️ Skipped	1

Tests ran across 4 shards in parallel.

View full report →