neotoma 0.4.2 → 0.4.3

package/dist/server.js

@@ -11,7 +11,7 @@ import * as yaml from "js-yaml";
 import { config } from "./config.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
 import { buildCliEquivalentInvocation } from "./shared/contract_mappings.js";
-import { getOpenApiInputSchemaOrThrow } from "./shared/openapi_schema.js";
+import { buildToolDefinitions } from "./tool_definitions.js";
 import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateRelationshipRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListEntityTypesRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RelationshipSnapshotRequestSchema, RetrieveEntitiesRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, TimelineEventsRequestSchema, UpdateSchemaIncrementalRequestSchema, RegisterSchemaRequestSchema, } from "./shared/action_schemas.js";
 import { ensureLocalDevUser } from "./services/local_auth.js";
 import { extractTextFromBuffer, getPdfFirstPageImageDataUrl, getMimeTypeFromExtension, } from "./services/file_text_extraction.js";
@@ -644,749 +644,13 @@ export class NeotomaServer {
             }
             logger.info(`[MCP Server] listTools called for authenticated user: ${userId}`);
             return {
-                tools: [
-                    {
-                        name: "retrieve_file_url",
-                        description: this.toolDescriptions.get("retrieve_file_url") ??
-                            "Retrieve a signed URL for accessing a file",
-                        inputSchema: getOpenApiInputSchemaOrThrow("retrieve_file_url"),
-                    },
-                    {
-                        name: "retrieve_entity_snapshot",
-                        description: this.toolDescriptions.get("retrieve_entity_snapshot") ??
-                            "Retrieve the current snapshot of an entity with provenance information. Supports historical snapshots via 'at' parameter.",
-                        inputSchema: getOpenApiInputSchemaOrThrow("retrieve_entity_snapshot"),
-                    },
-                    {
-                        name: "list_observations",
-                        description: this.toolDescriptions.get("list_observations") ??
-                            "List all observations for a given entity",
-                        inputSchema: getOpenApiInputSchemaOrThrow("list_observations"),
-                    },
-                    {
-                        name: "retrieve_field_provenance",
-                        description: this.toolDescriptions.get("retrieve_field_provenance") ??
-                            "Retrieve the provenance chain for a specific field in an entity snapshot",
-                        inputSchema: getOpenApiInputSchemaOrThrow("retrieve_field_provenance"),
-                    },
-                    {
-                        name: "create_relationship",
-                        description: this.toolDescriptions.get("create_relationship") ??
-                            "Create a typed relationship between two entities",
-                        inputSchema: getOpenApiInputSchemaOrThrow("create_relationship"),
-                    },
-                    {
-                        name: "list_relationships",
-                        description: this.toolDescriptions.get("list_relationships") ?? "List relationships for an entity",
-                        inputSchema: getOpenApiInputSchemaOrThrow("list_relationships"),
-                    },
-                    {
-                        name: "get_relationship_snapshot",
-                        description: this.toolDescriptions.get("get_relationship_snapshot") ??
-                            "Get the current snapshot of a specific relationship with provenance",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                relationship_type: {
-                                    type: "string",
-                                    enum: [
-                                        "PART_OF",
-                                        "CORRECTS",
-                                        "REFERS_TO",
-                                        "SETTLES",
-                                        "DUPLICATE_OF",
-                                        "DEPENDS_ON",
-                                        "SUPERSEDES",
-                                        "EMBEDS",
-                                    ],
-                                    description: "Type of relationship",
-                                },
-                                source_entity_id: {
-                                    type: "string",
-                                    description: "Source entity ID",
-                                },
-                                target_entity_id: {
-                                    type: "string",
-                                    description: "Target entity ID",
-                                },
-                            },
-                            required: ["relationship_type", "source_entity_id", "target_entity_id"],
-                        },
-                    },
-                    {
-                        name: "retrieve_entities",
-                        description: this.toolDescriptions.get("retrieve_entities") ??
-                            "Query entities with filters (type, pagination). Returns entities with their snapshots.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_type: {
-                                    type: "string",
-                                    description: "Optional entity type filter (for example: post, task, contact).",
-                                },
-                                search: {
-                                    type: "string",
-                                    description: "Canonical free-text query for lexical/semantic retrieval. Cannot be combined with published filters or non-default sorting.",
-                                },
-                                search_query: {
-                                    type: "string",
-                                    description: "Compatibility alias for `search`.",
-                                },
-                                query: {
-                                    type: "string",
-                                    description: "Compatibility alias for `search`.",
-                                },
-                                similarity_threshold: {
-                                    type: "number",
-                                    description: "Semantic distance threshold when `search` is used. Lower is stricter (typical 1.0-1.05).",
-                                },
-                                limit: {
-                                    type: "integer",
-                                    minimum: 1,
-                                    description: "Maximum number of entities to return (default 100).",
-                                },
-                                offset: {
-                                    type: "integer",
-                                    minimum: 0,
-                                    description: "Pagination offset (default 0).",
-                                },
-                                sort_by: {
-                                    type: "string",
-                                    enum: ["entity_id", "canonical_name", "observation_count", "last_observation_at"],
-                                    description: "Sort field. Non-default values cannot be combined with `search`.",
-                                },
-                                sort_order: {
-                                    type: "string",
-                                    enum: ["asc", "desc"],
-                                    description: "Sort direction. `desc` cannot be combined with `search`.",
-                                },
-                                published: {
-                                    type: "boolean",
-                                    description: "Filter by snapshot.published. Cannot be combined with `search`.",
-                                },
-                                published_after: {
-                                    type: "string",
-                                    description: "Inclusive lower bound for snapshot.published_date (ISO date/datetime). Cannot be combined with `search`.",
-                                },
-                                published_before: {
-                                    type: "string",
-                                    description: "Inclusive upper bound for snapshot.published_date (ISO date/datetime). Cannot be combined with `search`.",
-                                },
-                                include_snapshots: {
-                                    type: "boolean",
-                                    description: "When false, omit snapshot/provenance/raw_fragments payloads for lightweight responses.",
-                                },
-                                include_merged: {
-                                    type: "boolean",
-                                    description: "Whether to include merged entities (default false).",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional explicit user ID (normally inferred from auth context).",
-                                },
-                            },
-                            required: [],
-                        },
-                    },
-                    {
-                        name: "list_timeline_events",
-                        description: "Query timeline events with filters (type, date range, source). Returns chronological events derived from date fields in sources.",
-                        inputSchema: getOpenApiInputSchemaOrThrow("list_timeline_events"),
-                        annotations: {
-                            readOnlyHint: true,
-                        },
-                        _meta: {
-                            ui: {
-                                resourceUri: TIMELINE_WIDGET_RESOURCE_URI,
-                            },
-                            "openai/outputTemplate": TIMELINE_WIDGET_RESOURCE_URI,
-                        },
-                    },
-                    {
-                        name: "retrieve_entity_by_identifier",
-                        description: this.toolDescriptions.get("retrieve_entity_by_identifier") ??
-                            "Retrieve entity by identifier (name, email, etc.) across entity types or specific type.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                identifier: {
-                                    type: "string",
-                                    description: "Identifier to search for (name, email, tax_id, etc.) - will be normalized",
-                                },
-                                entity_type: {
-                                    type: "string",
-                                    description: "Optional: Limit search to specific entity type (e.g., 'company', 'person')",
-                                },
-                            },
-                            required: ["identifier"],
-                        },
-                    },
-                    {
-                        name: "retrieve_related_entities",
-                        description: this.toolDescriptions.get("retrieve_related_entities") ??
-                            "Retrieve entities connected to a given entity via relationships. Supports n-hop traversal.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_id: {
-                                    type: "string",
-                                    description: "Starting entity ID",
-                                },
-                                relationship_types: {
-                                    type: "array",
-                                    items: { type: "string" },
-                                    description: "Filter by relationship types (e.g., ['PART_OF', 'REFERS_TO']). If empty, includes all types.",
-                                },
-                                direction: {
-                                    type: "string",
-                                    enum: ["inbound", "outbound", "both"],
-                                    description: "Direction of relationships to traverse",
-                                    default: "both",
-                                },
-                                max_hops: {
-                                    type: "number",
-                                    description: "Maximum number of relationship hops (1 = direct, 2 = 2-hop, etc.)",
-                                    default: 1,
-                                },
-                                include_entities: {
-                                    type: "boolean",
-                                    description: "Whether to include full entity snapshots in response",
-                                    default: true,
-                                },
-                            },
-                            required: ["entity_id"],
-                        },
-                    },
-                    {
-                        name: "retrieve_graph_neighborhood",
-                        description: this.toolDescriptions.get("retrieve_graph_neighborhood") ??
-                            "Retrieve complete graph neighborhood around a node (entity or source): related entities, relationships, sources, and events.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                node_id: {
-                                    type: "string",
-                                    description: "Node ID (entity_id or source_id) to get neighborhood for",
-                                },
-                                node_type: {
-                                    type: "string",
-                                    enum: ["entity", "source"],
-                                    description: "Type of node ('entity' for entities, 'source' for sources)",
-                                    default: "entity",
-                                },
-                                include_relationships: {
-                                    type: "boolean",
-                                    description: "Include relationships in response",
-                                    default: true,
-                                },
-                                include_sources: {
-                                    type: "boolean",
-                                    description: "Include related sources in response",
-                                    default: true,
-                                },
-                                include_events: {
-                                    type: "boolean",
-                                    description: "Include timeline events in response",
-                                    default: true,
-                                },
-                                include_observations: {
-                                    type: "boolean",
-                                    description: "Include observations (for entities only)",
-                                    default: false,
-                                },
-                            },
-                            required: ["node_id"],
-                        },
-                    },
-                    {
-                        name: "store",
-                        description: this.toolDescriptions.get("store") ??
-                            "Unified storing for both file-backed and structured sources. For files: provide EITHER file_content (base64-encoded) + mime_type OR file_path. For structured data: provide entities array. File inputs are stored raw with content-addressed SHA-256 deduplication per user. Agents should parse and extract entities before storing when they need structured data from a file; the server no longer performs AI interpretation during store. IMPORTANT FOR STRUCTURED DATA: When storing structured entities with an unregistered entity_type, the system automatically infers and creates a user-specific schema from the data structure. Agents must include ALL fields from the source data, not just fields that match the entity schema. Schema fields are stored in observations (validated), while non-schema fields are automatically stored in raw_fragments.",
-                        inputSchema: (() => {
-                            const baseSchema = getOpenApiInputSchemaOrThrow("store");
-                            const baseProperties = (baseSchema.properties ?? {});
-                            return {
-                                ...baseSchema,
-                                type: "object",
-                                properties: {
-                                    ...baseProperties,
-                                    file_content: {
-                                        type: "string",
-                                        description: "Base64-encoded file content. Use file_path for local files instead of base64 encoding.",
-                                    },
-                                    file_path: {
-                                        type: "string",
-                                        description: "Local file path (alternative to file_content). If provided, file will be read from filesystem. MIME type will be auto-detected from extension if not provided. Works in local environments (Cursor, Claude Code) where MCP server has filesystem access. Does NOT work in web-based environments (claude.ai, chatgpt.com) - use file_content for those.",
-                                    },
-                                    mime_type: {
-                                        type: "string",
-                                        description: "MIME type (e.g., 'application/pdf', 'text/csv') - required with file_content, optional with file_path (auto-detected from extension)",
-                                    },
-                                    original_filename: {
-                                        type: "string",
-                                        description: "Original filename or source label (optional). For unstructured: auto-detected from file_path if not provided. For structured (entities): omit when data is agent-provided (no file origin); the source will have no filename. Pass only when mirroring a real file name or when a display label is desired.",
-                                    },
-                                },
-                            };
-                        })(),
-                    },
-                    {
-                        name: "store_structured",
-                        description: this.toolDescriptions.get("store_structured") ??
-                            "Store structured entities only. Use this when you already have entity objects and do not need file ingestion.",
-                        inputSchema: getOpenApiInputSchemaOrThrow("store_structured"),
-                    },
-                    {
-                        name: "store_unstructured",
-                        description: this.toolDescriptions.get("store_unstructured") ??
-                            "Store raw files only. Provide file_content (base64) + mime_type or file_path.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                idempotency_key: {
-                                    type: "string",
-                                    description: "Required. Client-provided idempotency key for replay-safe storing.",
-                                },
-                                file_content: {
-                                    type: "string",
-                                    description: "Base64-encoded file content (for unstructured storage). Use file_path for local files instead of base64 encoding.",
-                                },
-                                file_path: {
-                                    type: "string",
-                                    description: "Local file path (alternative to file_content). If provided, file will be read from filesystem.",
-                                },
-                                mime_type: {
-                                    type: "string",
-                                    description: "MIME type (e.g., 'application/pdf', 'text/csv') - required with file_content, optional with file_path",
-                                },
-                                original_filename: {
-                                    type: "string",
-                                    description: "Original filename (optional, auto-detected from file_path if not provided)",
-                                },
-                            },
-                            required: ["idempotency_key"],
-                        },
-                    },
-                    {
-                        name: "parse_file",
-                        description: this.toolDescriptions.get("parse_file") ??
-                            "Parse local or base64-encoded files into agent-readable text and page images without storing anything. Use for PDFs or other files you need to inspect before structured storing.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                file_content: {
-                                    type: "string",
-                                    description: "Base64-encoded file content.",
-                                },
-                                file_path: {
-                                    type: "string",
-                                    description: "Local file path. Preferred in local environments.",
-                                },
-                                mime_type: {
-                                    type: "string",
-                                    description: "Optional MIME type. Auto-detected from file_path when omitted.",
-                                },
-                                original_filename: {
-                                    type: "string",
-                                    description: "Optional filename hint for MIME detection and PDF parsing.",
-                                },
-                            },
-                            required: [],
-                        },
-                    },
-                    {
-                        name: "correct",
-                        description: "Create high-priority correction observation to override AI-extracted fields. Corrections always win in snapshot computation.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional. Inferred from authentication if omitted.",
-                                },
-                                entity_id: {
-                                    type: "string",
-                                    description: "Entity ID to correct",
-                                },
-                                entity_type: {
-                                    type: "string",
-                                    description: "Entity type",
-                                },
-                                field: {
-                                    type: "string",
-                                    description: "Field name to correct",
-                                },
-                                value: {
-                                    description: "Corrected value",
-                                },
-                                idempotency_key: {
-                                    type: "string",
-                                    description: "Required. Client-provided idempotency key for replay-safe corrections.",
-                                },
-                            },
-                            required: ["entity_id", "entity_type", "field", "value", "idempotency_key"],
-                        },
-                    },
-                    {
-                        name: "merge_entities",
-                        description: this.toolDescriptions.get("merge_entities") ??
-                            "Merge duplicate entities. Rewrites observations from source entity to target entity and marks source as merged.",
-                        inputSchema: getOpenApiInputSchemaOrThrow("merge_entities"),
-                    },
-                    {
-                        name: "delete_entity",
-                        description: this.toolDescriptions.get("delete_entity") ??
-                            "Delete an entity. Creates a deletion observation so the entity is excluded from snapshots and queries. Immutable and reversible for audit; use for user-initiated or GDPR-style removal from active use.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_id: {
-                                    type: "string",
-                                    description: "Entity ID to delete",
-                                },
-                                entity_type: {
-                                    type: "string",
-                                    description: "Entity type (e.g. company, person)",
-                                },
-                                reason: {
-                                    type: "string",
-                                    description: "Optional reason for deletion (audit)",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional. Inferred from authentication if omitted.",
-                                },
-                            },
-                            required: ["entity_id", "entity_type"],
-                        },
-                    },
-                    {
-                        name: "delete_relationship",
-                        description: this.toolDescriptions.get("delete_relationship") ??
-                            "Delete a relationship. Creates a deletion observation so the relationship is excluded from snapshots and queries. Immutable and reversible for audit.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                relationship_type: {
-                                    type: "string",
-                                    description: "Relationship type (e.g. PART_OF, REFERS_TO, EMBEDS)",
-                                    enum: [
-                                        "PART_OF",
-                                        "CORRECTS",
-                                        "REFERS_TO",
-                                        "SETTLES",
-                                        "DUPLICATE_OF",
-                                        "DEPENDS_ON",
-                                        "SUPERSEDES",
-                                        "EMBEDS",
-                                    ],
-                                },
-                                source_entity_id: {
-                                    type: "string",
-                                    description: "Source entity ID",
-                                },
-                                target_entity_id: {
-                                    type: "string",
-                                    description: "Target entity ID",
-                                },
-                                reason: {
-                                    type: "string",
-                                    description: "Optional reason for deletion (audit)",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional. Inferred from authentication if omitted.",
-                                },
-                            },
-                            required: ["relationship_type", "source_entity_id", "target_entity_id"],
-                        },
-                    },
-                    {
-                        name: "restore_entity",
-                        description: this.toolDescriptions.get("restore_entity") ??
-                            "Restore a deleted entity. Creates a restoration observation (priority 1001) that overrides the deletion. Entity becomes visible in snapshots and queries again. Immutable restoration for audit.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_id: {
-                                    type: "string",
-                                    description: "Entity ID to restore",
-                                },
-                                entity_type: {
-                                    type: "string",
-                                    description: "Entity type (e.g. company, person)",
-                                },
-                                reason: {
-                                    type: "string",
-                                    description: "Optional reason for restoration (audit)",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional. Inferred from authentication if omitted.",
-                                },
-                            },
-                            required: ["entity_id", "entity_type"],
-                        },
-                    },
-                    {
-                        name: "restore_relationship",
-                        description: this.toolDescriptions.get("restore_relationship") ??
-                            "Restore a deleted relationship. Creates a restoration observation (priority 1001) that overrides the deletion. Relationship becomes visible in snapshots and queries again. Immutable restoration for audit.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                relationship_type: {
-                                    type: "string",
-                                    description: "Relationship type (e.g. PART_OF, REFERS_TO, EMBEDS)",
-                                    enum: [
-                                        "PART_OF",
-                                        "CORRECTS",
-                                        "REFERS_TO",
-                                        "SETTLES",
-                                        "DUPLICATE_OF",
-                                        "DEPENDS_ON",
-                                        "SUPERSEDES",
-                                        "EMBEDS",
-                                    ],
-                                },
-                                source_entity_id: {
-                                    type: "string",
-                                    description: "Source entity ID",
-                                },
-                                target_entity_id: {
-                                    type: "string",
-                                    description: "Target entity ID",
-                                },
-                                reason: {
-                                    type: "string",
-                                    description: "Optional reason for restoration (audit)",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional. Inferred from authentication if omitted.",
-                                },
-                            },
-                            required: ["relationship_type", "source_entity_id", "target_entity_id"],
-                        },
-                    },
-                    {
-                        name: "get_entity_type_counts",
-                        description: this.toolDescriptions.get("get_entity_type_counts") ??
-                            "Return canonical entity counts by entity_type for the authenticated user, sorted by count descending. Use this when you need row counts by type; do not infer counts from list_entity_types field_count.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                user_id: {
-                                    type: "string",
-                                    description: "Optional. Inferred from authentication if omitted.",
-                                },
-                            },
-                            required: [],
-                        },
-                    },
-                    {
-                        name: "list_entity_types",
-                        description: this.toolDescriptions.get("list_entity_types") ??
-                            "List all available entity types with their schema information. Optionally filter by keyword to find entity types relevant to your data. Uses hybrid search: keyword matching first (deterministic), then vector semantic search (semantic similarity). Use this action before storing structured data to determine the correct entity_type.",
-                        inputSchema: getOpenApiInputSchemaOrThrow("list_entity_types"),
-                    },
-                    {
-                        name: "analyze_schema_candidates",
-                        description: this.toolDescriptions.get("analyze_schema_candidates") ??
-                            "Analyze raw_fragments to identify fields that should be promoted to schema fields. Returns recommendations with confidence scores based on frequency and type consistency.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_type: {
-                                    type: "string",
-                                    description: "Entity type to analyze (optional, analyzes all if not provided)",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "User ID for user-specific analysis (optional)",
-                                },
-                                min_frequency: {
-                                    type: "number",
-                                    description: "Minimum frequency threshold (default: 5)",
-                                    default: 5,
-                                },
-                                min_confidence: {
-                                    type: "number",
-                                    description: "Minimum confidence score 0-1 (default: 0.8)",
-                                    default: 0.8,
-                                },
-                            },
-                            required: [],
-                        },
-                    },
-                    {
-                        name: "get_schema_recommendations",
-                        description: "Get schema update recommendations for an entity type from raw_fragments analysis, agent suggestions, or inference.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_type: {
-                                    type: "string",
-                                    description: "Entity type to get recommendations for",
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "User ID for user-specific recommendations (optional)",
-                                },
-                                source: {
-                                    type: "string",
-                                    enum: ["raw_fragments", "agent", "inference", "all"],
-                                    description: "Recommendation source (default: all)",
-                                },
-                                status: {
-                                    type: "string",
-                                    enum: ["pending", "approved", "rejected"],
-                                    description: "Filter by recommendation status (default: pending)",
-                                },
-                            },
-                            required: ["entity_type"],
-                        },
-                    },
-                    {
-                        name: "update_schema_incremental",
-                        description: this.toolDescriptions.get("update_schema_incremental") ??
-                            "Incrementally update a schema by adding or removing fields. Adding fields creates a minor version bump; removing fields creates a major version bump. Removed fields are excluded from future snapshots via schema-projection filtering, but all observation data is preserved and can be restored by re-adding the field. Optionally migrates existing raw_fragments to observations for historical data backfill.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_type: {
-                                    type: "string",
-                                    description: "Entity type to update",
-                                },
-                                fields_to_add: {
-                                    type: "array",
-                                    description: "Fields to add to schema",
-                                    items: {
-                                        type: "object",
-                                        properties: {
-                                            field_name: { type: "string" },
-                                            field_type: {
-                                                type: "string",
-                                                enum: ["string", "number", "date", "boolean", "array", "object"],
-                                            },
-                                            required: { type: "boolean", default: false },
-                                            reducer_strategy: {
-                                                type: "string",
-                                                enum: ["last_write", "highest_priority", "most_specific", "merge_array"],
-                                            },
-                                        },
-                                        required: ["field_name", "field_type"],
-                                    },
-                                },
-                                fields_to_remove: {
-                                    type: "array",
-                                    description: "Field names to remove from schema (triggers major version bump). Observation data is preserved; fields can be restored by re-adding them later.",
-                                    items: { type: "string" },
-                                },
-                                schema_version: {
-                                    type: "string",
-                                    description: "New schema version (auto-increments if not provided)",
-                                },
-                                user_specific: {
-                                    type: "boolean",
-                                    description: "Create user-specific schema variant (default: false)",
-                                    default: false,
-                                },
-                                user_id: {
-                                    type: "string",
-                                    description: "User ID for user-specific schema (required if user_specific=true)",
-                                },
-                                activate: {
-                                    type: "boolean",
-                                    description: "Activate schema immediately so it applies to new data (default: true). If false, schema is registered but not active.",
-                                    default: true,
-                                },
-                                migrate_existing: {
-                                    type: "boolean",
-                                    description: "Migrate existing raw_fragments to observations for historical data backfill (default: false). Note: New data automatically uses updated schema after activation, migration is only for old data.",
-                                    default: false,
-                                },
-                            },
-                            required: ["entity_type"],
-                        },
-                    },
-                    {
-                        name: "register_schema",
-                        description: this.toolDescriptions.get("register_schema") ??
-                            "Register a new schema or schema version. Supports both global and user-specific schemas.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                entity_type: { type: "string" },
-                                schema_definition: {
-                                    type: "object",
-                                    description: "Schema definition with fields object",
-                                },
-                                reducer_config: {
-                                    type: "object",
-                                    description: "Reducer configuration with merge policies",
-                                },
-                                schema_version: { type: "string", default: "1.0" },
-                                user_specific: { type: "boolean", default: false },
-                                user_id: {
-                                    type: "string",
-                                    description: "User ID for user-specific schema (required if user_specific=true)",
-                                },
-                                activate: { type: "boolean", default: false },
-                            },
-                            required: ["entity_type", "schema_definition", "reducer_config"],
-                        },
-                    },
-                    {
-                        name: "get_authenticated_user",
-                        description: "Get the authenticated user ID for the current MCP session. Returns the user_id that is automatically used for all authenticated actions.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {},
-                            required: [],
-                        },
-                    },
-                    {
-                        name: "health_check_snapshots",
-                        description: this.toolDescriptions.get("health_check_snapshots") ??
-                            "Check for stale entity snapshots (snapshots with observation_count=0 but observations exist). Returns health status and count of stale snapshots.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                auto_fix: {
-                                    type: "boolean",
-                                    description: "If true, automatically recompute stale snapshots (default: false)",
-                                    default: false,
-                                },
-                            },
-                            required: [],
-                        },
-                    },
-                    {
-                        name: "npm_check_update",
-                        description: this.toolDescriptions.get("npm_check_update") ??
-                            "Check if a newer npm version is available. Returns updateAvailable, message, and suggestedCommand. Call at session start to encourage user to upgrade.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                packageName: {
-                                    type: "string",
-                                    description: "npm package name (e.g. neotoma)",
-                                },
-                                currentVersion: {
-                                    type: "string",
-                                    description: "Current version reported by the client",
-                                },
-                                distTag: {
-                                    type: "string",
-                                    description: "Dist tag to check (default: latest)",
-                                    default: "latest",
-                                },
-                            },
-                            required: ["packageName", "currentVersion"],
-                        },
-                    },
-                ],
+                tools: buildToolDefinitions(this.toolDescriptions, TIMELINE_WIDGET_RESOURCE_URI).map((def) => ({
+                    name: def.name,
+                    description: def.description,
+                    inputSchema: def.inputSchema,
+                    ...(def.annotations ? { annotations: def.annotations } : {}),
+                    ...(def._meta ? { _meta: def._meta } : {}),
+                })),
             };
         });
         const summarizeToolResultForLog = (toolName, result) => {