@digital-science-dsl/dimensions-analytics-mcp 1.3.1 → 1.4.0

package/src/mcp/identity-fields.ts

@@ -0,0 +1,65 @@
+/**
+ * Identity fields that structured search/lookup always returns (WEBAPPDEV-13816).
+ * Default DSL fieldsets omit `doi` on publications, and agents often request
+ * title-only field lists — both make it hard to open or cite a record.
+ *
+ * @module mcp/identity-fields
+ */
+
+/** Fields that uniquely identify a record, by entity type. */
+const IDENTITY_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  publications: ["id", "doi"],
+  grants: ["id"],
+  researchers: ["id"],
+  patents: ["id"],
+  clinical_trials: ["id"],
+  datasets: ["id"],
+  policy_documents: ["id"],
+  organizations: ["id"],
+  reports: ["id"],
+  source_titles: ["id"],
+  funder_groups: ["id"],
+  research_org_groups: ["id"],
+};
+
+/** DSL fieldset that matches the API default list payload. */
+const DEFAULT_FIELDSET = "basics";
+
+/**
+ * Identity fields for a source (defaults to `id`).
+ * @param entityType - DSL source name
+ */
+export function identityFieldsFor(entityType: string): readonly string[] {
+  return IDENTITY_FIELDS[entityType] ?? ["id"];
+}
+
+/**
+ * Deduplicates strings while preserving first-seen order.
+ * @param items - Field names
+ */
+function unique(items: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of items) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * Ensures identity fields are present in a return-clause field list.
+ * When the caller omits `fields`, keeps the default `basics` fieldset and
+ * adds identifiers (so publication lists include `doi` without dropping authors).
+ *
+ * @param entityType - DSL source name
+ * @param fields - Caller-requested fields after alias resolution
+ */
+export function mergeIdentityFields(entityType: string, fields?: readonly string[]): string[] {
+  const identity = identityFieldsFor(entityType);
+  if (!fields?.length) {
+    return unique([DEFAULT_FIELDSET, ...identity]);
+  }
+  return unique([...identity, ...fields]);
+}

package/src/mcp/profile-urls.ts

@@ -0,0 +1,180 @@
+/**
+ * Canonical Dimensions web profile URLs.
+ *
+ * DSL `dimensions_url` is a publication discover facet for researchers and
+ * organizations, not a profile page. LLMs then invent paths such as
+ * `/discover/researcher/{id}` which 404 (WEBAPPDEV-13680 / DIMENTRY-10160).
+ *
+ * @module mcp/profile-urls
+ */
+
+/** Default Dimensions web host when `DIMENSIONS_BASE_URL` is unset. */
+export const DEFAULT_INSTANCE_BASE_URL = "https://app.dimensions.ai";
+
+/**
+ * Path builders for entity types that have a canonical profile page.
+ * Researcher and organization templates are from WEBAPPDEV-13680; other
+ * document types match the live DSL `dimensions_url` path.
+ */
+const PROFILE_URL_PATHS = {
+  publications: (id: string) => `/details/publication/${id}`,
+  grants: (id: string) => `/details/grant/${id}`,
+  patents: (id: string) => `/details/patent/${id}`,
+  clinical_trials: (id: string) => `/details/clinical_trial/${id}`,
+  datasets: (id: string) => `/details/data_set/${id}`,
+  policy_documents: (id: string) => `/details/policy_documents/${id}`,
+  researchers: (id: string) => `/details/entities/publication/author/${id}`,
+  organizations: (id: string) => `/details/organization/${id}`,
+} as const;
+
+/** Entity types that have a canonical Dimensions web profile. */
+export type ProfileEntityType = keyof typeof PROFILE_URL_PATHS;
+
+/** Entity types that have a canonical Dimensions web profile. */
+export const PROFILE_ENTITY_TYPES = Object.keys(PROFILE_URL_PATHS) as ProfileEntityType[];
+
+/**
+ * Facet fields whose bucket `id` is a profile entity (not a category label).
+ */
+const FACET_FIELD_PROFILE_ENTITY: Readonly<Record<string, ProfileEntityType>> = {
+  researchers: "researchers",
+  research_orgs: "organizations",
+  funder_orgs: "organizations",
+  current_research_org: "organizations",
+};
+
+/**
+ * Strips trailing slashes from an instance base URL.
+ * @param baseUrl - Raw instance URL
+ * @returns Normalized origin with no trailing slash
+ */
+export function normalizeInstanceBaseUrl(baseUrl?: string): string {
+  const raw = (baseUrl ?? process.env.DIMENSIONS_BASE_URL ?? DEFAULT_INSTANCE_BASE_URL).trim();
+  return raw.replace(/\/+$/, "") || DEFAULT_INSTANCE_BASE_URL;
+}
+
+/**
+ * Whether `entityType` has a canonical Dimensions profile page.
+ * @param entityType - DSL source or entity name
+ */
+export function isProfileEntityType(entityType: string): entityType is ProfileEntityType {
+  return Object.hasOwn(PROFILE_URL_PATHS, entityType);
+}
+
+/**
+ * Builds a canonical Dimensions profile URL, or `undefined` when the entity
+ * type has no profile page or the id is empty.
+ * @param entityType - DSL source name (e.g. `researchers`)
+ * @param id - Dimensions record id
+ * @param instanceBaseUrl - Web instance origin (defaults to `DIMENSIONS_BASE_URL`)
+ */
+export function buildProfileUrl(
+  entityType: string,
+  id: string,
+  instanceBaseUrl?: string,
+): string | undefined {
+  if (!isProfileEntityType(entityType)) return undefined;
+  const trimmed = id.trim();
+  if (!trimmed) return undefined;
+  const base = normalizeInstanceBaseUrl(instanceBaseUrl);
+  return `${base}${PROFILE_URL_PATHS[entityType](encodeURIComponent(trimmed))}`;
+}
+
+/**
+ * Returns the profile entity type for a facet field, if bucket ids are profiles.
+ * @param facetField - Facet field name after alias resolution
+ */
+export function profileEntityForFacetField(facetField: string): ProfileEntityType | undefined {
+  return FACET_FIELD_PROFILE_ENTITY[facetField];
+}
+
+/**
+ * Adds `profile_url` when the record has an id and the entity has a profile page.
+ * @param entityType - DSL source name
+ * @param record - Result row
+ * @param instanceBaseUrl - Web instance origin
+ */
+export function attachProfileUrl<T extends Record<string, unknown>>(
+  entityType: string,
+  record: T,
+  instanceBaseUrl?: string,
+): T {
+  const id = record.id;
+  if (typeof id !== "string" && typeof id !== "number") return record;
+  const profileUrl = buildProfileUrl(entityType, String(id), instanceBaseUrl);
+  if (!profileUrl) return record;
+  return { ...record, profile_url: profileUrl };
+}
+
+/**
+ * Adds `profile_url` to each record that has a usable id.
+ * @param entityType - DSL source name
+ * @param records - Result rows
+ * @param instanceBaseUrl - Web instance origin
+ */
+export function attachProfileUrls<T extends Record<string, unknown>>(
+  entityType: string,
+  records: readonly T[],
+  instanceBaseUrl?: string,
+): T[] {
+  return records.map((record) => attachProfileUrl(entityType, record, instanceBaseUrl));
+}
+
+/**
+ * Adds `profile_url` to facet buckets when the facet field is a profile entity.
+ * @param facetField - Facet field name after alias resolution
+ * @param buckets - Facet buckets
+ * @param instanceBaseUrl - Web instance origin
+ */
+export function attachFacetProfileUrls(
+  facetField: string,
+  buckets: readonly object[],
+  instanceBaseUrl?: string,
+): Record<string, unknown>[] {
+  const rows = buckets.map((bucket) => ({ ...(bucket as Record<string, unknown>) }));
+  const profileEntity = profileEntityForFacetField(facetField);
+  if (!profileEntity) return rows;
+  return attachProfileUrls(profileEntity, rows, instanceBaseUrl);
+}
+
+/** Catalog entry for one profile URL template. */
+export interface ProfileUrlTemplate {
+  readonly entityType: ProfileEntityType;
+  readonly path: string;
+  readonly exampleId: string;
+  readonly exampleUrl: string;
+}
+
+const TEMPLATE_EXAMPLES: Readonly<Record<ProfileEntityType, string>> = {
+  publications: "pub.1015581115",
+  grants: "grant.2438800",
+  patents: "ZW-9994-A1",
+  clinical_trials: "chictr-trc-14005205",
+  datasets: "dataset.99999999",
+  policy_documents: "policy.9999",
+  researchers: "ur.01222634304.39",
+  organizations: "grid.168010.e",
+};
+
+/**
+ * Documented profile URL templates for MCP resources and agent instructions.
+ * @param instanceBaseUrl - Web instance origin
+ */
+export function profileUrlCatalog(instanceBaseUrl?: string): {
+  instanceBaseUrl: string;
+  warning: string;
+  templates: ProfileUrlTemplate[];
+} {
+  const base = normalizeInstanceBaseUrl(instanceBaseUrl);
+  return {
+    instanceBaseUrl: base,
+    warning:
+      "Never invent Dimensions web URLs. Researcher profiles are /details/entities/publication/author/{id}, not /discover/researcher/{id}. Organization profiles are /details/organization/{id}. DSL dimensions_url for researchers and organizations is a publication discover facet, not a profile.",
+    templates: PROFILE_ENTITY_TYPES.map((entityType) => {
+      const exampleId = TEMPLATE_EXAMPLES[entityType];
+      const exampleUrl = buildProfileUrl(entityType, exampleId, base) ?? "";
+      const path = exampleUrl.slice(base.length).replace(encodeURIComponent(exampleId), "{id}");
+      return { entityType, path, exampleId, exampleUrl };
+    }),
+  };
+}

package/src/mcp/resources/schema.ts

@@ -23,6 +23,7 @@ import {
   getDslExamplesForSource,
 } from "../examples/dsl-examples.js";
 import { buildReverseAliasMap } from "../middleware/field-aliases.js";
+import { profileUrlCatalog } from "../profile-urls.js";
 import type { SchemaContext } from "../schema/context.js";
 
 /**
@@ -132,6 +133,25 @@ export function registerSchemaResources(server: McpServer, context: SchemaContex
     }),
   );
 
+  server.registerResource(
+    "schema-profile-urls",
+    "dimensions://schema/profile-urls",
+    {
+      description:
+        "Canonical Dimensions web profile URL templates — use these instead of inventing /discover/researcher/ paths",
+      mimeType: "application/json",
+    },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(profileUrlCatalog(), null, 2),
+        },
+      ],
+    }),
+  );
+
   server.registerResource(
     "dsl-examples",
     "dimensions://examples",

package/src/mcp/server.ts

@@ -24,6 +24,7 @@ import { registerAnalyticsTools } from "./tools/analytics.js";
 import { registerFetchSearchPagesTools } from "./tools/fetch-search-pages.js";
 import { registerFunctionTools } from "./tools/functions.js";
 import { registerLookupTools } from "./tools/lookup.js";
+import { registerProfileUrlTool } from "./tools/profile-url.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerSchemaTools, validateFieldAliases } from "./tools/schema.js";
 import { registerSearchTools } from "./tools/search.js";
@@ -107,7 +108,9 @@ export function buildServerInstructions(schemaStore: SchemaStore): string {
       "search_source_titles for journals / ISSN lookup (not articles); search_reports for technical reports;",
       "search_funder_groups / search_research_org_groups for curated group name → member GRID ids;",
       "similar_documents finds concept-similar publications/grants from prose (not embeddings); for a known ID, get_by_id then pass abstract/description as text;",
-      "facet_query supports yearFrom/yearTo for year-scoped facets.",
+      "facet_query supports yearFrom/yearTo for year-scoped facets;",
+      "never invent Dimensions web URLs — use profile_url from results or construct_profile_url (see dimensions://schema/profile-urls); researcher profiles are /details/entities/publication/author/{id}, not /discover/researcher/{id}; org profiles are /details/organization/{id};",
+      "search_* / get_by_* / similar_documents always include id (and doi for publications) even if fields omits them.",
     ].join(" "),
     [
       "Query construction:",
@@ -139,6 +142,7 @@ function registerAllTools(
     registerFetchSearchPagesTools(server, client, schemaStore);
   }
   registerLookupTools(server, client);
+  registerProfileUrlTool(server);
   registerQueryTools(server, client, schemaStore);
   registerFunctionTools(server, client);
   registerSimilarDocumentsTool(server, client);

package/src/mcp/tools/analytics.ts

@@ -15,6 +15,7 @@ import {
   SUPPORTED_CURRENCIES,
 } from "../../dsl/index.js";
 import { resolveFacetFieldName, withFieldAliases } from "../middleware/field-aliases.js";
+import { attachFacetProfileUrls } from "../profile-urls.js";
 import type { SchemaStore } from "../schema/index.js";
 import { registerTrackedTool } from "../usage-tracking.js";
 import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
@@ -200,11 +201,12 @@ export function registerAnalyticsTools(
             includeRaw: false,
           });
           const facets = parsed.facets[facetField];
+          const buckets = attachFacetProfileUrls(facetField, facets.buckets);
           return formatToolResult({
             entityType: args.entityType,
             facetField,
-            totalBuckets: facets.buckets.length,
-            buckets: facets.buckets,
+            totalBuckets: buckets.length,
+            buckets,
           });
         } catch (error) {
           return formatErrorResult(error);
@@ -308,12 +310,13 @@ export function registerAnalyticsTools(
             includeRaw: false,
           });
           const facets = parsed.facets[facetField];
+          const buckets = attachFacetProfileUrls(facetField, facets.buckets);
           return formatToolResult({
             entityType: args.entityType,
             facetField,
             indicators: args.indicators,
-            totalBuckets: facets.buckets.length,
-            buckets: facets.buckets,
+            totalBuckets: buckets.length,
+            buckets,
           });
         } catch (error) {
           return formatErrorResult(error);

package/src/mcp/tools/fetch-search-pages.ts

@@ -23,6 +23,7 @@ import {
 import { queryHashFromDsl, runAggregateFetch, runFileFetch } from "../batch-fetch.js";
 import { resolveExportFormat } from "../export-format.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { attachProfileUrls } from "../profile-urls.js";
 import { registerTrackedTool } from "../usage-tracking.js";
 import {
   formatErrorResult,
@@ -302,7 +303,7 @@ export function registerFetchSearchPagesTools(
           const dsl = buildDsl(skip, limit);
           const response = (await client.rawQuery(dsl)) as Record<string, unknown>;
           const parsed = parseEntityResponse(response, entityType);
-          const rows = parsed.data as Record<string, unknown>[];
+          const rows = attachProfileUrls(entityType, parsed.data as Record<string, unknown>[]);
           const resultKey = searchResultKey(entityType);
 
           return formatToolResult(

package/src/mcp/tools/lookup.ts

@@ -6,7 +6,9 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { type DimensionsClient, EntitySchema, type EntityType } from "../../dsl/index.js";
+import { mergeIdentityFields } from "../identity-fields.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { attachProfileUrl } from "../profile-urls.js";
 import { registerTrackedTool } from "../usage-tracking.js";
 import {
   asArray,
@@ -51,13 +53,14 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
             .search("publications")
             .where("doi", "=", args.doi)
             .limit(1);
-          if (args.fields?.length) qb.fields(args.fields);
+          qb.fields(mergeIdentityFields("publications", args.fields));
           const dsl = qb.build();
 
           const response = await client.rawQuery(dsl);
           const publications = asArray(response.publications);
+          const publication = publications[0];
 
-          if (publications.length === 0) {
+          if (!publication) {
             return formatToolResult({
               found: false,
               message: `No publication found with DOI: ${args.doi}`,
@@ -66,7 +69,7 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
 
           return formatToolResult({
             found: true,
-            publication: publications[0],
+            publication: attachProfileUrl("publications", publication),
           });
         } catch (error) {
           return formatErrorResult(error);
@@ -105,13 +108,14 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
             .search("publications")
             .where("pmid", "=", args.pmid)
             .limit(1);
-          if (args.fields?.length) qb.fields(args.fields);
+          qb.fields(mergeIdentityFields("publications", args.fields));
           const dsl = qb.build();
 
           const response = await client.rawQuery(dsl);
           const publications = asArray(response.publications);
+          const publication = publications[0];
 
-          if (publications.length === 0) {
+          if (!publication) {
             return formatToolResult({
               found: false,
               message: `No publication found with PMID: ${args.pmid}`,
@@ -120,7 +124,7 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
 
           return formatToolResult({
             found: true,
-            publication: publications[0],
+            publication: attachProfileUrl("publications", publication),
           });
         } catch (error) {
           return formatErrorResult(error);
@@ -158,13 +162,14 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
             .search(args.entityType as EntityType)
             .where("id", "=", args.id)
             .limit(1);
-          if (args.fields?.length) qb.fields(args.fields);
+          qb.fields(mergeIdentityFields(args.entityType, args.fields));
           const dsl = qb.build();
 
           const response = await client.rawQuery(dsl);
           const entities = asArray(response[args.entityType]);
+          const entity = entities[0];
 
-          if (entities.length === 0) {
+          if (!entity) {
             return formatToolResult({
               found: false,
               message: `No ${args.entityType.slice(0, -1)} found with ID: ${args.id}`,
@@ -173,7 +178,7 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
 
           return formatToolResult({
             found: true,
-            entity: entities[0],
+            entity: attachProfileUrl(args.entityType, entity),
             entityType: args.entityType,
           });
         } catch (error) {

package/src/mcp/tools/profile-url.ts

@@ -0,0 +1,70 @@
+/**
+ * MCP tool for constructing canonical Dimensions profile URLs.
+ * @module mcp/tools/profile-url
+ */
+
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { buildProfileUrl, isProfileEntityType, PROFILE_ENTITY_TYPES } from "../profile-urls.js";
+import { registerTrackedTool } from "../usage-tracking.js";
+import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
+
+const profileEntityEnum = z.enum(PROFILE_ENTITY_TYPES as [string, ...string[]]);
+
+/**
+ * Registers `construct_profile_url`.
+ * @param server - MCP server instance
+ */
+export function registerProfileUrlTool(server: McpServer): void {
+  registerTrackedTool(
+    server,
+    "construct_profile_url",
+    {
+      description:
+        "Build a canonical Dimensions web profile URL from an entity type and Dimensions ID. " +
+        "Use this instead of inventing paths — researcher profiles are " +
+        "/details/entities/publication/author/{id} (not /discover/researcher/{id}); " +
+        "organization profiles are /details/organization/{id}. " +
+        "search_*, get_by_*, similar_documents, and facet_query already attach profile_url when possible.",
+      inputSchema: z.object({
+        entityType: profileEntityEnum.describe(
+          "Entity type with a web profile (e.g. researchers, organizations, publications)",
+        ),
+        id: z.string().min(1).describe("Dimensions ID (e.g. ur.01222634304.39, grid.168010.e)"),
+      }),
+      outputSchema: z.object({
+        entityType: z.string().describe("Entity type"),
+        id: z.string().describe("Dimensions ID"),
+        profile_url: z.string().describe("Canonical Dimensions web profile URL"),
+      }),
+      annotations: {
+        ...READ_ONLY_API_ANNOTATIONS,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const entityType = args.entityType as string;
+        const id = args.id as string;
+        if (!isProfileEntityType(entityType)) {
+          return formatErrorResult(
+            new Error(
+              `No canonical Dimensions profile URL for entity type: ${entityType}. Supported: ${PROFILE_ENTITY_TYPES.join(", ")}`,
+            ),
+          );
+        }
+        const profileUrl = buildProfileUrl(entityType, id);
+        if (!profileUrl) {
+          return formatErrorResult(new Error("A non-empty Dimensions ID is required"));
+        }
+        return formatToolResult({
+          entityType,
+          id: id.trim(),
+          profile_url: profileUrl,
+        });
+      } catch (error) {
+        return formatErrorResult(error);
+      }
+    },
+  );
+}

package/src/mcp/tools/search-entity-metadata.ts

@@ -131,7 +131,8 @@ export const SEARCH_ENTITY_METADATA: readonly SearchEntityMetadata[] = [
     source: "researchers",
     description:
       "Search researcher profiles by name in the Dimensions database. The query matches researcher names, not research topics — " +
-      "for topic→researcher discovery use facet_query with entityType publications and facetField researchers.",
+      "for topic→researcher discovery use facet_query with entityType publications and facetField researchers. " +
+      "Each result includes profile_url (canonical /details/entities/publication/author/{id} — never invent /discover/researcher/{id}).",
     applyConvenienceFilters: noop,
     extraInputSchema: {
       sortBy: z
@@ -229,7 +230,8 @@ export const SEARCH_ENTITY_METADATA: readonly SearchEntityMetadata[] = [
   {
     source: "organizations",
     description:
-      "Search research organizations in the Dimensions database. Returns universities, research institutes, hospitals, and companies with research output.",
+      "Search research organizations in the Dimensions database. Returns universities, research institutes, hospitals, and companies with research output. " +
+      "Each result includes profile_url (canonical /details/organization/{id}).",
     applyConvenienceFilters: (builder, args) => {
       if (typeof args.orgType === "string") {
         builder.where("types", "=", args.orgType);

package/src/mcp/tools/search-input.ts

@@ -45,7 +45,7 @@ export const SHARED_SEARCH_INPUT = {
     .array(z.string())
     .optional()
     .describe(
-      "Fields to return. Accepts aliases or DSL names. Use dimensions://fields/{entity} for the full list.",
+      "Fields to return. Accepts aliases or DSL names. id is always included; publications also always include doi. Use dimensions://fields/{entity} for the full list.",
     ),
   filters: z
     .array(ExtendedWhereFilterSchema)

package/src/mcp/tools/search.ts

@@ -17,7 +17,9 @@ import {
   searchToolName,
   validateSearchPaginationPolicy,
 } from "../../dsl/index.js";
+import { mergeIdentityFields } from "../identity-fields.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { attachProfileUrls } from "../profile-urls.js";
 import { registerTrackedTool } from "../usage-tracking.js";
 import {
   formatErrorResult,
@@ -58,10 +60,7 @@ export function buildStructuredSearchDsl(
     applyFilters(builder, filters);
   }
 
-  const fields = args.fields as string[] | undefined;
-  if (fields?.length) {
-    builder.fields(fields);
-  }
+  builder.fields(mergeIdentityFields(source, args.fields as string[] | undefined));
 
   if (typeof args.sortBy === "string") {
     builder.sort(args.sortBy, "desc");
@@ -144,7 +143,7 @@ export function registerSearchTools(
             const dsl = buildStructuredSearchDsl(client, source, record);
             const response = (await client.rawQuery(dsl)) as Record<string, unknown>;
             const parsed = parseEntityResponse(response, source);
-            const rows = parsed.data as Record<string, unknown>[];
+            const rows = attachProfileUrls(source, parsed.data as Record<string, unknown>[]);
 
             return formatToolResult(
               withSearchPagination(

package/src/mcp/tools/similar-documents.ts

@@ -17,7 +17,9 @@ import {
   searchResultKey,
   validateSearchPaginationPolicy,
 } from "../../dsl/index.js";
+import { mergeIdentityFields } from "../identity-fields.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { attachProfileUrls } from "../profile-urls.js";
 import { registerTrackedTool } from "../usage-tracking.js";
 import {
   formatErrorResult,
@@ -67,10 +69,7 @@ export function buildSimilarDocumentsDsl(
     applyFilters(builder, filters);
   }
 
-  const fields = args.fields as string[] | undefined;
-  if (fields?.length) {
-    builder.fields(fields);
-  }
+  builder.fields(mergeIdentityFields(entityType, args.fields as string[] | undefined));
 
   const sortBy = typeof args.sortBy === "string" ? args.sortBy : "score";
   builder.sort(sortBy, "desc");
@@ -205,7 +204,7 @@ export function registerSimilarDocumentsTool(server: McpServer, client: Dimensio
           });
           const response = (await client.rawQuery(dsl)) as Record<string, unknown>;
           const parsed = parseEntityResponse(response, entityType as StructuredEntityType);
-          const rows = parsed.data as Record<string, unknown>[];
+          const rows = attachProfileUrls(entityType, parsed.data as Record<string, unknown>[]);
           const resultKey = searchResultKey(entityType as StructuredEntityType);
 
           return formatToolResult(

package/test/identity-fields.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Tests for always-on identity fields (WEBAPPDEV-13816).
+ * @module test/identity-fields
+ */
+
+import { describe, expect, it } from "vitest";
+import { identityFieldsFor, mergeIdentityFields } from "../src/mcp/identity-fields.js";
+
+describe("identityFieldsFor", () => {
+  it("requires id and doi for publications", () => {
+    expect(identityFieldsFor("publications")).toEqual(["id", "doi"]);
+  });
+
+  it("requires id for other searchable entity types", () => {
+    expect(identityFieldsFor("grants")).toEqual(["id"]);
+    expect(identityFieldsFor("researchers")).toEqual(["id"]);
+    expect(identityFieldsFor("organizations")).toEqual(["id"]);
+    expect(identityFieldsFor("patents")).toEqual(["id"]);
+  });
+});
+
+describe("mergeIdentityFields", () => {
+  it("uses basics plus identity fields when the caller omits fields", () => {
+    expect(mergeIdentityFields("publications")).toEqual(["basics", "id", "doi"]);
+    expect(mergeIdentityFields("grants")).toEqual(["basics", "id"]);
+  });
+
+  it("prepends missing identity fields to an explicit field list", () => {
+    expect(mergeIdentityFields("publications", ["title", "year"])).toEqual([
+      "id",
+      "doi",
+      "title",
+      "year",
+    ]);
+  });
+
+  it("does not duplicate identity fields the caller already requested", () => {
+    expect(mergeIdentityFields("publications", ["id", "title", "doi"])).toEqual([
+      "id",
+      "doi",
+      "title",
+    ]);
+  });
+});