feat(search-tool): align search filters and returned fields with GQL schema

[tjackowiak]

Summary

Aligns search-tool MCP parameters and returned fields with the current GQL schema (stable + dev). Several filters available in the API were not exposed, and some indexed_data fields were not returned.

New input parameters

Parameter	Applies to	GQL version
dateRange (created_before/after, updated_before/after)	ITEMS, BOARD, DOCUMENTS, UPDATES, WORKSPACES, TIMELINE_ITEMS, DASHBOARDS	stable
boardIds	BOARD, TIMELINE_ITEMS (previously ITEMS, UPDATES only)	stable
workspaceIds	WORKSPACES, TIMELINE_ITEMS (previously ITEMS, BOARD, DOCUMENTS, DASHBOARDS only)	stable
itemIds	TIMELINE_ITEMS	stable
workspaceKind	WORKSPACES	stable
timelineItemType	TIMELINE_ITEMS	stable
timelineProductKind	TIMELINE_ITEMS	stable
overviewKinds	DASHBOARDS	dev

New returned fields

Entity	New fields
BOARD	description, creatorId
UPDATES	createdAt, updatedAt
WORKSPACES	kind, state
TIMELINE_ITEMS	type, productKind, createdAt, updatedAt
DASHBOARDS	kind, state, createdBy, createdAt, updatedAt

Notes on typing choices

The two kinds of "kind" arguments are deliberately modelled differently, following one rule: a GQL enum becomes z.nativeEnum; a GQL String stays z.string() with the known values documented.

• timelineItemType / timelineProductKind are backed by the real TimelineItemKind / TimelineItemProductKind enums, so they use z.nativeEnum on the generated enums. TimelineItemKind has 23 values — hand-listing them would drift from the schema as new kinds are added.
• workspaceKind is z.string(). search.workspaces(kind:) is a plain String, and WorkspaceKind itself carries a third value (template) beyond the two named in the argument's description, so narrowing would reject valid input.
• overviewKinds is z.array(z.string()). search.overviews(kinds:) is [String!] and the casing is inconsistent across layers — the DashboardKind enum is uppercase while the search index documents lowercase — so the values are passed through rather than guessed.

dateRange is intentionally not validated with .datetime(): the API accepts date-only strings that a strict ISO8601-with-time check would reject. The expected format is documented in the field descriptions instead.

strategy (SPEED/BALANCED/QUALITY) is out of scope for this PR — it trades search quality against latency and needs a separate decision on defaults before being exposed.

Generated types were produced by yarn codegen against both schemas, which also validated every new argument and field name. No manual edits to generated files.

Test plan

yarn test — 1382 passing (152 in search-tool.test.ts). yarn build and yarn lint clean.

Existing fixtures were repaired where the response types gained required fields, and 26 tests were added covering:

• Filter pass-through for every new parameter on every entity that accepts it
• Each newly returned field, including the nullable ones being omitted when the index has none
• timelineItemType accepts less-obvious enum values (note, phoneCall, aiSummary) and rejects invalid ones — regression guard against re-narrowing the enum
• workspaceKind: 'template' accepted and forwarded
• Empty creatorIds / overviewKinds arrays normalize to "no filter" rather than being sent as []
• All pre-existing search types unaffected when none of the new optional params are passed

Not covered by automated tests: no live API call was made against either schema version, so the filters are verified against the schema and mocked client only.

🤖 Generated with Claude Code