@digital-science-dsl/dimensions-analytics-mcp 1.0.4 → 1.2.0

package/dist/mcp/tools/similar-documents.js

@@ -0,0 +1,171 @@
+/**
+ * similar_documents MCP tool — find publications/grants with similar topics via DSL.
+ * Uses concept extraction + weighted concepts search (not vector embeddings).
+ * @module mcp/tools/similar-documents
+ */
+import { z } from "zod";
+import { applyFilters, ExtendedWhereFilterSchema, parseEntityResponse, resolveSkipAndLimit, SCHEMA_LIMITS, searchResultKey, validateSearchPaginationPolicy, } from "../../dsl/index.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import { registerTrackedTool } from "../usage-tracking.js";
+import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS, withSearchPagination, } from "../utils.js";
+import { PAGINATION_INPUT_SCHEMA, PAGINATION_OUTPUT_SCHEMA } from "./search-input.js";
+/** Entity types that support the DSL similar_documents() search function. */
+export const SIMILAR_DOCUMENTS_ENTITY_TYPES = ["publications", "grants"];
+/** Year filter field per entity (publications use year; grants use start_year). */
+const YEAR_FIELD = {
+    publications: "year",
+    grants: "start_year",
+};
+/**
+ * Builds DSL for a similar_documents search from tool arguments.
+ * @param client - Dimensions client
+ * @param entityType - publications or grants
+ * @param args - Tool arguments (after field-alias resolution)
+ * @returns DSL query string
+ */
+export function buildSimilarDocumentsDsl(client, entityType, args) {
+    const text = String(args.text ?? "");
+    const builder = client.createQueryBuilder().search(entityType).forSimilar(text);
+    const yearField = YEAR_FIELD[entityType];
+    if (typeof args.yearFrom === "number") {
+        builder.where(yearField, ">=", args.yearFrom);
+    }
+    if (typeof args.yearTo === "number") {
+        builder.where(yearField, "<=", args.yearTo);
+    }
+    const filters = args.filters;
+    if (filters?.length) {
+        applyFilters(builder, filters);
+    }
+    const fields = args.fields;
+    if (fields?.length) {
+        builder.fields(fields);
+    }
+    const sortBy = typeof args.sortBy === "string" ? args.sortBy : "score";
+    builder.sort(sortBy, "desc");
+    // Default to 20 for similarity (top-N relevance), not the search_* default of 100.
+    const { skip, limit } = resolveSkipAndLimit({
+        skip: args.skip,
+        page: args.page,
+        limit: args.limit ?? 20,
+        pageSize: args.pageSize,
+    });
+    builder.limit(limit);
+    if (skip > 0) {
+        builder.skip(skip);
+    }
+    return builder.build();
+}
+/**
+ * Registers the similar_documents tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerSimilarDocumentsTool(server, client) {
+    registerTrackedTool(server, "similar_documents", {
+        description: "Find publications or grants with similar research topics based on abstract/description text. " +
+            "Uses Dimensions concept extraction and weighted concepts search (not vector embeddings). " +
+            "Prefer this over execute_dsl for similarity. For a known record: get_by_id / get_by_doi first, " +
+            "then pass its abstract/description as text. Supported entityType: publications, grants only.",
+        inputSchema: {
+            entityType: z
+                .enum(SIMILAR_DOCUMENTS_ENTITY_TYPES)
+                .describe("Entity type to search (publications or grants)"),
+            text: z
+                .string()
+                .min(1)
+                .describe("Abstract, description, or other prose to find similar documents for. " +
+                "Longer topical text works better than short keywords."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(SCHEMA_LIMITS.maxLimit)
+                .default(20)
+                .describe(`Maximum results to return (max ${SCHEMA_LIMITS.maxLimit}, default 20)`),
+            ...PAGINATION_INPUT_SCHEMA,
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe("Fields to return. Accepts aliases or DSL names. Use dimensions://fields/{entity} for the full list."),
+            filters: z
+                .array(ExtendedWhereFilterSchema)
+                .optional()
+                .describe("Additional where-clause filters"),
+            yearFrom: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter from this year inclusive (publications: year; grants: start_year)"),
+            yearTo: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter up to this year inclusive (publications: year; grants: start_year)"),
+            sortBy: z
+                .string()
+                .optional()
+                .describe("Sort field (default: score for relevance). Examples: score, times_cited, year, start_year."),
+            confirmLargeFetch: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Required when skip≥5000, page≥5, or limit=1000 with skip>0. See dimensions://schema/policy."),
+        },
+        outputSchema: {
+            entityType: z.enum(SIMILAR_DOCUMENTS_ENTITY_TYPES).describe("Entity type searched"),
+            totalCount: z.number().describe("Total matching records"),
+            returnedCount: z.number().describe("Records returned in this response"),
+            truncated: z.boolean().optional().describe("True when more results exist beyond this page"),
+            truncationWarning: z.string().optional().describe("Warning message when truncated"),
+            ...PAGINATION_OUTPUT_SCHEMA,
+            publications: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Matching publications (when entityType is publications)"),
+            grants: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Matching grants (when entityType is grants)"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, withFieldAliases({
+        entitySource: { kind: "dynamic", argName: "entityType" },
+        fieldArrayArgs: ["fields"],
+        fieldStringArgs: ["sortBy"],
+        filterArrayArgs: ["filters"],
+    }, async (args) => {
+        try {
+            const entityType = args.entityType;
+            const record = args;
+            const { skip, limit } = resolveSkipAndLimit({
+                skip: record.skip,
+                page: record.page,
+                limit: record.limit ?? 20,
+            });
+            validateSearchPaginationPolicy({
+                skip,
+                limit,
+                confirmLargeFetch: record.confirmLargeFetch,
+            });
+            const dsl = buildSimilarDocumentsDsl(client, entityType, {
+                ...record,
+                limit,
+            });
+            const response = (await client.rawQuery(dsl));
+            const parsed = parseEntityResponse(response, entityType);
+            const rows = parsed.data;
+            const resultKey = searchResultKey(entityType);
+            return formatToolResult(withSearchPagination({
+                entityType,
+                totalCount: parsed.totalCount,
+                returnedCount: rows.length,
+                [resultKey]: rows,
+            }, parsed.totalCount, rows.length, skip, limit));
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    }));
+}
+//# sourceMappingURL=similar-documents.js.map

package/dist/mcp/tools/similar-documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"similar-documents.js","sourceRoot":"","sources":["../../../src/mcp/tools/similar-documents.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital-science-dsl/dimensions-analytics-mcp",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "Dimensions Analytics MCP server for Dimensions DSL querying",
   "type": "module",
   "main": "./dist/index.js",

package/src/dsl/schema/structured-entities.ts

@@ -13,6 +13,10 @@ export const STRUCTURED_ENTITY_TYPES = [
   "datasets",
   "policy_documents",
   "organizations",
+  "reports",
+  "source_titles",
+  "funder_groups",
+  "research_org_groups",
 ] as const;
 
 /** A source with a structured search tool. */

package/src/dsl/types/vocabulary.ts

@@ -18,7 +18,11 @@ export type EntityType =
   | "clinical_trials"
   | "datasets"
   | "policy_documents"
-  | "organizations";
+  | "organizations"
+  | "reports"
+  | "source_titles"
+  | "funder_groups"
+  | "research_org_groups";
 
 /** Search indexes for `search <source> in <index> for "..."` clauses. */
 export type SearchIndex =
@@ -34,7 +38,8 @@ export type SearchIndex =
   | "acknowledgements"
   | "raw_affiliations"
   | "assignees"
-  | "title_abstract_claims";
+  | "title_abstract_claims"
+  | "name";
 
 /** Sort direction for order-by clauses. */
 export type SortOrder = "asc" | "desc";
@@ -62,6 +67,10 @@ export const VALID_ENTITIES: readonly EntityType[] = [
   "datasets",
   "policy_documents",
   "organizations",
+  "reports",
+  "source_titles",
+  "funder_groups",
+  "research_org_groups",
 ] as const;
 
 /** Valid search indexes for runtime validation. */
@@ -79,4 +88,5 @@ export const VALID_INDEXES: readonly SearchIndex[] = [
   "raw_affiliations",
   "assignees",
   "title_abstract_claims",
+  "name",
 ] as const;

package/src/mcp/examples/dsl-examples.ts

@@ -12,11 +12,13 @@ export const DSL_EXAMPLES_BY_ENTITY: Record<string, readonly string[]> = {
     'search publications for "machine learning" return publications[id+title+doi] limit 10',
     'search publications for "CRISPR" where year >= 2020 return publications[id+title+times_cited+year] sort by times_cited desc limit 25',
     'search publications in title_only for "gene therapy" return publications[basics] limit 10',
+    'search publications for similar_documents("After spinal cord injury, macrophages infiltrate the lesion site") where year > 2015 return publications[id+title+year] sort by score desc limit 5',
     "search publications return publications facet journal limit 20",
   ],
   grants: [
     'search grants for "cancer immunotherapy" return grants limit 10',
     'search grants where funder_org_name = "National Institutes of Health" return grants[basics] limit 10',
+    'search grants for similar_documents("Cancer immunotherapy with checkpoint inhibitors and CAR-T") where start_year >= 2020 return grants[id+title] sort by score desc limit 5',
     "search grants return grants aggregate funding_usd",
   ],
   patents: [
@@ -39,6 +41,18 @@ export const DSL_EXAMPLES_BY_ENTITY: Record<string, readonly string[]> = {
     'search organizations for "Stanford" return organizations limit 10',
     'search organizations where country = "United States" return organizations limit 10',
   ],
+  reports: [
+    'search reports for "climate change" return reports[basics] limit 10',
+    "search reports where year >= 2020 return reports[id+title+year] limit 20",
+  ],
+  source_titles: [
+    'search source_titles for "Nature" return source_titles[basics] limit 10',
+    'search source_titles where type = "journal" return source_titles[id+title+issn+sjr] limit 20',
+  ],
+  funder_groups: ['search funder_groups for "NIH" return funder_groups[basics] limit 10'],
+  research_org_groups: [
+    'search research_org_groups for "Ivy League" return research_org_groups[basics] limit 10',
+  ],
 };
 
 /** General DSL patterns (describe, functions, pagination). */

package/src/mcp/examples/usage-scenarios.ts

@@ -164,6 +164,25 @@ export const USAGE_SCENARIOS: readonly UsageScenario[] = [
     },
     dslContains: ["large language model", "citations_per_year(2018, 2024)"],
   },
+  {
+    id: "similar-documents",
+    goal: "Similar papers from an abstract",
+    prompt: "Find publications similar to this abstract about spinal cord injury macrophages.",
+    tool: "similar_documents",
+    args: {
+      entityType: "publications",
+      text: "After spinal cord injury, macrophages infiltrate the lesion site and contribute to both tissue damage and repair processes.",
+      yearFrom: 2016,
+      limit: 10,
+      fields: ["id", "title", "year"],
+    },
+    dslContains: [
+      "search publications for similar_documents(",
+      "year >= 2016",
+      "sort by score desc",
+      "limit 10",
+    ],
+  },
   {
     id: "build-complex-query",
     goal: "Build a complex query",

package/src/mcp/middleware/field-aliases.ts

@@ -103,6 +103,10 @@ export const ENTITY_ALIASES: Readonly<Record<EntityType, Readonly<Record<string,
   policy_documents: { ...POLICY_DOCUMENT_ALIASES },
   researchers: { ...RESEARCHER_ALIASES },
   organizations: { ...ORGANIZATION_ALIASES },
+  reports: {},
+  source_titles: {},
+  funder_groups: {},
+  research_org_groups: {},
 };
 
 // ---------------------------------------------------------------------------

package/src/mcp/server.ts

@@ -27,6 +27,7 @@ import { registerLookupTools } from "./tools/lookup.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerSchemaTools, validateFieldAliases } from "./tools/schema.js";
 import { registerSearchTools } from "./tools/search.js";
+import { registerSimilarDocumentsTool } from "./tools/similar-documents.js";
 import { initMcpUsageTracking } from "./usage-tracking.js";
 
 /**
@@ -94,7 +95,7 @@ export function buildServerInstructions(schemaStore: SchemaStore): string {
     [
       "Workflow:",
       "(1) Discover schema — read dimensions://schema/summary, dimensions://fields/{entity}, dimensions://examples/{source}, or describe_schema;",
-      "(2) Search — search_* for keyword discovery with filters; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
+      "(2) Search — search_* for keyword discovery with filters; similar_documents for topic-similar pubs/grants from abstract text; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
       "(3) Analyze — facet_query, aggregate_query, citation_trend, funding_trend;",
       "(4) Drill down — get_by_id, search_* with filters (e.g. researchers.id, research_orgs.id), facet_query for top researchers at an org.",
     ].join(" "),
@@ -103,12 +104,16 @@ export function buildServerInstructions(schemaStore: SchemaStore): string {
       "search_researchers matches names only — topic→researcher uses facet_query (entityType publications, facetField researchers);",
       "search_grants funderOrgName needs exact Dimensions names (NCI/NSF acronyms resolve; discover funders via facet_query/aggregate_query on facetField funder_orgs);",
       "search_organizations for institution lookup — prefer GRID id in filters when the name is ambiguous;",
+      "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.",
     ].join(" "),
     [
       "Query construction:",
       "for ranked publication search (e.g. most-cited since 2020), use search_publications with query, yearFrom, sortBy (times_cited or total_citations), limit — do not hand-write execute_dsl;",
-      "use execute_dsl for boolean concept groups and DSL special functions;",
+      "for similar-document lookup, use similar_documents — do not hand-write similar_documents() in execute_dsl;",
+      "use execute_dsl for boolean concept groups and remaining DSL special functions (classify, extract_concepts);",
       "use execute_dsl only when structured tools are insufficient; DSL order is return ... sort by FIELD order limit N (never limit before sort).",
     ].join(" "),
     [
@@ -136,6 +141,7 @@ function registerAllTools(
   registerLookupTools(server, client);
   registerQueryTools(server, client, schemaStore);
   registerFunctionTools(server, client);
+  registerSimilarDocumentsTool(server, client);
   registerAnalyticsTools(server, client, schemaStore);
   registerSchemaTools(server, client, schemaContext);
 }

package/src/mcp/tools/analytics-filters.ts

@@ -14,6 +14,8 @@ const ENTITY_YEAR_FIELD: Partial<Record<EntityType, string>> = {
   clinical_trials: "year",
   datasets: "year",
   policy_documents: "year",
+  reports: "year",
+  source_titles: "start_year",
 };
 
 /**

package/src/mcp/tools/lookup.ts

@@ -136,7 +136,7 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
     "get_by_id",
     {
       description:
-        "Retrieve any entity by its Dimensions ID. Supports publications, grants, patents, clinical trials, datasets, policy documents, researchers, and organizations.",
+        "Retrieve any entity by its Dimensions ID. Supports publications, grants, patents, clinical trials, datasets, policy documents, researchers, organizations, reports, source titles, funder groups, and research org groups.",
       inputSchema: {
         entityType: EntitySchema.describe("The type of entity to look up"),
         id: z.string().describe("The Dimensions ID to look up"),

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

@@ -250,4 +250,54 @@ export const SEARCH_ENTITY_METADATA: readonly SearchEntityMetadata[] = [
       sortBy: z.enum(["name"]).optional().describe("Sort results by this field"),
     },
   },
+  {
+    source: "reports",
+    description:
+      "Search technical reports in the Dimensions database. Returns report titles, abstracts, responsible organizations, funders, and related metadata.",
+    applyConvenienceFilters: (builder, args) => {
+      yearRange("yearFrom", "yearTo", "year")(builder, args);
+    },
+    extraInputSchema: {
+      yearFrom: z.number().int().optional().describe("Filter reports from this year (inclusive)"),
+      yearTo: z.number().int().optional().describe("Filter reports up to this year (inclusive)"),
+      sortBy: z.enum(["year", "date"]).optional().describe("Sort results by this field"),
+    },
+  },
+  {
+    source: "source_titles",
+    description:
+      "Search publication source titles (journals, preprint platforms, book series, proceedings) in the Dimensions database. " +
+      "Use for journal / ISSN lookup — not for searching articles (use search_publications).",
+    applyConvenienceFilters: (builder, args) => {
+      if (typeof args.sourceTitleType === "string") {
+        builder.where("type", "=", args.sourceTitleType);
+      }
+    },
+    extraInputSchema: {
+      sourceTitleType: z
+        .enum(["journal", "book_series", "proceeding", "preprint_platform"])
+        .optional()
+        .describe("Filter by source title type"),
+      sortBy: z
+        .enum(["sjr", "snip", "start_year"])
+        .optional()
+        .describe("Sort results by this field"),
+    },
+  },
+  {
+    source: "funder_groups",
+    description:
+      "Search curated funder groups in the Dimensions database. Returns group name and member organization GRID IDs. " +
+      "Query matches group names (search index: name).",
+    applyConvenienceFilters: noop,
+    extraInputSchema: {},
+  },
+  {
+    source: "research_org_groups",
+    description:
+      "Search curated research organization groups in the Dimensions database. Returns group name and member organization GRID IDs. " +
+      "Query matches group names (search index: name).",
+    applyConvenienceFilters: noop,
+    extraInputSchema: {},
+  },
 ];

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

@@ -0,0 +1,232 @@
+/**
+ * similar_documents MCP tool — find publications/grants with similar topics via DSL.
+ * Uses concept extraction + weighted concepts search (not vector embeddings).
+ * @module mcp/tools/similar-documents
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { DimensionsClient } from "../../dsl/index.js";
+import {
+  applyFilters,
+  type ExtendedWhereFilterInput,
+  ExtendedWhereFilterSchema,
+  parseEntityResponse,
+  resolveSkipAndLimit,
+  SCHEMA_LIMITS,
+  type StructuredEntityType,
+  searchResultKey,
+  validateSearchPaginationPolicy,
+} from "../../dsl/index.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import { registerTrackedTool } from "../usage-tracking.js";
+import {
+  formatErrorResult,
+  formatToolResult,
+  READ_ONLY_API_ANNOTATIONS,
+  withSearchPagination,
+} from "../utils.js";
+import { PAGINATION_INPUT_SCHEMA, PAGINATION_OUTPUT_SCHEMA } from "./search-input.js";
+
+/** Entity types that support the DSL similar_documents() search function. */
+export const SIMILAR_DOCUMENTS_ENTITY_TYPES = ["publications", "grants"] as const;
+
+/** Entity type supported by similar_documents. */
+export type SimilarDocumentsEntityType = (typeof SIMILAR_DOCUMENTS_ENTITY_TYPES)[number];
+
+/** Year filter field per entity (publications use year; grants use start_year). */
+const YEAR_FIELD: Record<SimilarDocumentsEntityType, string> = {
+  publications: "year",
+  grants: "start_year",
+};
+
+/**
+ * Builds DSL for a similar_documents search from tool arguments.
+ * @param client - Dimensions client
+ * @param entityType - publications or grants
+ * @param args - Tool arguments (after field-alias resolution)
+ * @returns DSL query string
+ */
+export function buildSimilarDocumentsDsl(
+  client: DimensionsClient,
+  entityType: SimilarDocumentsEntityType,
+  args: Record<string, unknown>,
+): string {
+  const text = String(args.text ?? "");
+  const builder = client.createQueryBuilder().search(entityType).forSimilar(text);
+
+  const yearField = YEAR_FIELD[entityType];
+  if (typeof args.yearFrom === "number") {
+    builder.where(yearField, ">=", args.yearFrom);
+  }
+  if (typeof args.yearTo === "number") {
+    builder.where(yearField, "<=", args.yearTo);
+  }
+
+  const filters = args.filters as ExtendedWhereFilterInput[] | undefined;
+  if (filters?.length) {
+    applyFilters(builder, filters);
+  }
+
+  const fields = args.fields as string[] | undefined;
+  if (fields?.length) {
+    builder.fields(fields);
+  }
+
+  const sortBy = typeof args.sortBy === "string" ? args.sortBy : "score";
+  builder.sort(sortBy, "desc");
+
+  // Default to 20 for similarity (top-N relevance), not the search_* default of 100.
+  const { skip, limit } = resolveSkipAndLimit({
+    skip: args.skip as number | undefined,
+    page: args.page as number | undefined,
+    limit: (args.limit as number | undefined) ?? 20,
+    pageSize: args.pageSize as number | undefined,
+  });
+  builder.limit(limit);
+  if (skip > 0) {
+    builder.skip(skip);
+  }
+
+  return builder.build();
+}
+
+/**
+ * Registers the similar_documents tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerSimilarDocumentsTool(server: McpServer, client: DimensionsClient): void {
+  registerTrackedTool(
+    server,
+    "similar_documents",
+    {
+      description:
+        "Find publications or grants with similar research topics based on abstract/description text. " +
+        "Uses Dimensions concept extraction and weighted concepts search (not vector embeddings). " +
+        "Prefer this over execute_dsl for similarity. For a known record: get_by_id / get_by_doi first, " +
+        "then pass its abstract/description as text. Supported entityType: publications, grants only.",
+      inputSchema: {
+        entityType: z
+          .enum(SIMILAR_DOCUMENTS_ENTITY_TYPES)
+          .describe("Entity type to search (publications or grants)"),
+        text: z
+          .string()
+          .min(1)
+          .describe(
+            "Abstract, description, or other prose to find similar documents for. " +
+              "Longer topical text works better than short keywords.",
+          ),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(SCHEMA_LIMITS.maxLimit)
+          .default(20)
+          .describe(`Maximum results to return (max ${SCHEMA_LIMITS.maxLimit}, default 20)`),
+        ...PAGINATION_INPUT_SCHEMA,
+        fields: z
+          .array(z.string())
+          .optional()
+          .describe(
+            "Fields to return. Accepts aliases or DSL names. Use dimensions://fields/{entity} for the full list.",
+          ),
+        filters: z
+          .array(ExtendedWhereFilterSchema)
+          .optional()
+          .describe("Additional where-clause filters"),
+        yearFrom: z
+          .number()
+          .int()
+          .optional()
+          .describe("Filter from this year inclusive (publications: year; grants: start_year)"),
+        yearTo: z
+          .number()
+          .int()
+          .optional()
+          .describe("Filter up to this year inclusive (publications: year; grants: start_year)"),
+        sortBy: z
+          .string()
+          .optional()
+          .describe(
+            "Sort field (default: score for relevance). Examples: score, times_cited, year, start_year.",
+          ),
+        confirmLargeFetch: z
+          .boolean()
+          .optional()
+          .default(false)
+          .describe(
+            "Required when skip≥5000, page≥5, or limit=1000 with skip>0. See dimensions://schema/policy.",
+          ),
+      },
+      outputSchema: {
+        entityType: z.enum(SIMILAR_DOCUMENTS_ENTITY_TYPES).describe("Entity type searched"),
+        totalCount: z.number().describe("Total matching records"),
+        returnedCount: z.number().describe("Records returned in this response"),
+        truncated: z.boolean().optional().describe("True when more results exist beyond this page"),
+        truncationWarning: z.string().optional().describe("Warning message when truncated"),
+        ...PAGINATION_OUTPUT_SCHEMA,
+        publications: z
+          .array(z.record(z.string(), z.unknown()))
+          .optional()
+          .describe("Matching publications (when entityType is publications)"),
+        grants: z
+          .array(z.record(z.string(), z.unknown()))
+          .optional()
+          .describe("Matching grants (when entityType is grants)"),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    withFieldAliases(
+      {
+        entitySource: { kind: "dynamic", argName: "entityType" },
+        fieldArrayArgs: ["fields"],
+        fieldStringArgs: ["sortBy"],
+        filterArrayArgs: ["filters"],
+      },
+      async (args) => {
+        try {
+          const entityType = args.entityType as SimilarDocumentsEntityType;
+          const record = args as Record<string, unknown>;
+          const { skip, limit } = resolveSkipAndLimit({
+            skip: record.skip as number | undefined,
+            page: record.page as number | undefined,
+            limit: (record.limit as number | undefined) ?? 20,
+          });
+
+          validateSearchPaginationPolicy({
+            skip,
+            limit,
+            confirmLargeFetch: record.confirmLargeFetch as boolean | undefined,
+          });
+
+          const dsl = buildSimilarDocumentsDsl(client, entityType, {
+            ...record,
+            limit,
+          });
+          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 resultKey = searchResultKey(entityType as StructuredEntityType);
+
+          return formatToolResult(
+            withSearchPagination(
+              {
+                entityType,
+                totalCount: parsed.totalCount,
+                returnedCount: rows.length,
+                [resultKey]: rows,
+              },
+              parsed.totalCount,
+              rows.length,
+              skip,
+              limit,
+            ),
+          );
+        } catch (error) {
+          return formatErrorResult(error);
+        }
+      },
+    ),
+  );
+}