Summary

• A custom field has two separate, unrelated identifiers , fieldKey (the object key in customFieldDefinitions, and the actual value stored as field_id in crm_conversation_field_values) and definition.id (an opaque rename-tracking identifier that is never a valid query key for an ordinary custom field). config-read's list-fields action returned both with no indication of which is which, and an agent this session picked definition.id for a run-sql query, got a silent zero-row false negative, and nearly reported a real field as having no data.
• Adds a disambiguating .describe() to FieldDefinitionDataSchema.id (config-tool-shared.ts) so the correct guidance travels with the tool's own response, mirrors the same fix into the canonical CustomFieldDefinition.id TSDoc in aop-schema.ts (which had the identical stale claim), and adds matching gotchas to the run-sql and field-query skill docs.
• While writing the disambiguation, found and documented (but did not fix , separate, higher-risk issue) a real pre-existing bug: config-write-tool.ts's delete-field and remove-field-option actions key their crm_conversation_field_values lookups off definition.id instead of fieldKey, via field-deletion-safety.ts and option-reconciliation.ts , for a field whose id ≠ fieldKey (the common case for ordinary custom fields), this means deleting a custom field likely doesn't delete its stored values, and removing a picklist option likely doesn't find/remap the values that used it.

Test plan

• apps/server/src/mastra/tools/config/__tests__/config-read-output-schema.test.ts , new test asserting FieldDefinitionDataSchema.id's description warns against use as a query key and points to fieldKey; 3/3 pass.
• pnpm --filter @zero/server exec vitest run src/mastra/tools/config/__tests__ , 169/169 pass.
• pnpm --filter @zero/server exec vitest run src/ (full server suite) , 1136 passed, 34 skipped.
• pnpm --filter @zero/mail exec jest --config jest.config.cjs --no-coverage --ci under TZ=UTC (matching this repo's CI env for that step) , 540/540 suites pass. (One unrelated pre-existing test, tests/modules/chat-store/chatHistoryList.test.ts, is a local-timezone-only flake outside the local ambient TZ; verified it passes cleanly under TZ=UTC and is untouched by this diff.)
• pnpm --filter @zero/mail run test:tz , 5/5 pass.
• pnpm --filter @zero/server run types (tsc -b) , clean.
• pnpm deps:check , clean, no violations.
• Three rounds of fresh, context-free thermo review (no author bias) , first pass found two 🟡 (an overclaiming description, a misleading worked example), both fixed; second pass found one more 🟡 (the aop-schema.ts TSDoc still disagreed with the fixed schema description), fixed; third pass came back clean , 0 🔴, 0 🟡.

Verify in prod

This is a documentation/schema-description change only , no new runtime branching, no new log lines, and no behavior change to any tool response's actual data. There is nothing to query in Axiom/CloudWatch for this change itself; the correctness of the fix was verified via code tracing and tests (see above), not runtime telemetry. The one thing worth confirming post-merge, informally, is that the next agent to query a custom field's field_id via run-sql or list-fields uses fieldKey rather than id , but that's an agent-behavior outcome, not something with a dedicated metric.

🤖 Generated with Claude Code