@wentorai/research-plugins 1.4.2 → 1.4.4

package/src/tools/crossref.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://api.crossref.org";
 
@@ -23,7 +23,7 @@ export function createCrossRefTools(
           description: "DOI to resolve, e.g. '10.1038/nature12373'",
         }),
       }),
-      execute: async (input: { doi: string }) => {
+      execute: async (_toolCallId: string, input: { doi: string }) => {
         if (!input?.doi) {
           return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
         }
@@ -94,7 +94,7 @@ export function createCrossRefTools(
           Type.Number({ description: "Max results (default 10, max 100)" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         journal?: string;
         issn?: string;
@@ -105,8 +105,17 @@ export function createCrossRefTools(
         sort?: string;
         limit?: number;
       }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error:
+              "query parameter is required and must not be empty. " +
+              "Example: search_crossref({ query: \"PFAS machine learning\", from_year: 2023 })",
+          });
+        }
+
         const params = new URLSearchParams({
-          query: input.query,
+          query,
           rows: String(Math.min(input.limit ?? 10, 100)),
         });
 
@@ -114,16 +123,20 @@ export function createCrossRefTools(
         const filters: string[] = [];
         if (input.from_year) filters.push(`from-pub-date:${input.from_year}`);
         if (input.until_year) filters.push(`until-pub-date:${input.until_year}`);
-        if (input.type) filters.push(`type:${input.type}`);
+        const type = validParam(input.type);
+        if (type) filters.push(`type:${type}`);
         if (input.has_abstract) filters.push("has-abstract:true");
-        if (input.issn) filters.push(`issn:${input.issn}`);
+        const issn = validParam(input.issn);
+        if (issn) filters.push(`issn:${issn}`);
         if (filters.length > 0) params.set("filter", filters.join(","));
 
         // Journal name as query.container-title (separate from filter)
-        if (input.journal) params.set("query.container-title", input.journal);
+        const journal = validParam(input.journal);
+        if (journal) params.set("query.container-title", journal);
 
-        if (input.sort) {
-          params.set("sort", input.sort);
+        const sort = validParam(input.sort);
+        if (sort) {
+          params.set("sort", sort);
           params.set("order", "desc");
         }
 

package/src/tools/datacite.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://api.datacite.org";
 
@@ -31,22 +31,31 @@ export function createDataCiteTools(
           Type.Number({ description: "Published from this year onward" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         max_results?: number;
         resource_type?: string;
         from_year?: number;
       }) => {
-        const pageSize = Math.min(input.max_results ?? 10, 100);
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error:
+              "query parameter is required and must not be empty. " +
+              "Example: search_datacite({ query: \"climate dataset\" })",
+          });
+        }
+        const pageSize = Math.min(input?.max_results ?? 10, 100);
         const params = new URLSearchParams({
-          query: input.query,
+          query,
           "page[size]": String(pageSize),
         });
-        if (input.resource_type) {
-          params.set("resource-type-id", input.resource_type.toLowerCase());
+        const resourceType = validParam(input.resource_type);
+        if (resourceType) {
+          params.set("resource-type-id", resourceType.toLowerCase());
         }
-        if (input.from_year) {
-          params.set("query", `${input.query} AND publicationYear:[${input.from_year} TO *]`);
+        if (input?.from_year) {
+          params.set("query", `${query} AND publicationYear:[${input.from_year} TO *]`);
         }
 
         const tracked = await trackedFetch("datacite", `${BASE}/dois?${params}`, undefined, 15_000);
@@ -117,7 +126,7 @@ export function createDataCiteTools(
           description: "DOI to resolve, e.g. '10.5281/zenodo.1234567'",
         }),
       }),
-      execute: async (input: { doi: string }) => {
+      execute: async (_toolCallId: string, input: { doi: string }) => {
         if (!input?.doi) {
           return toolResult({ error: 'doi parameter is required (e.g., "10.5281/zenodo.1234567")' });
         }

package/src/tools/dblp.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 export function createDblpTools(
   _ctx: OpenClawPluginToolContext,
@@ -23,13 +23,20 @@ export function createDblpTools(
           Type.Number({ description: "Result offset for pagination" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         max_results?: number;
         offset?: number;
       }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error: "query parameter is required and must not be empty.",
+          });
+        }
+
         const params = new URLSearchParams({
-          q: input.query,
+          q: query,
           format: "json",
           h: String(Math.min(input.max_results ?? 10, 1000)),
         });
@@ -90,9 +97,16 @@ export function createDblpTools(
           Type.Number({ description: "Max results (default 10)" }),
         ),
       }),
-      execute: async (input: { query: string; max_results?: number }) => {
+      execute: async (_toolCallId: string, input: { query: string; max_results?: number }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error: "query parameter is required and must not be empty.",
+          });
+        }
+
         const params = new URLSearchParams({
-          q: input.query,
+          q: query,
           format: "json",
           h: String(Math.min(input.max_results ?? 10, 100)),
         });

package/src/tools/doaj.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://doaj.org/api";
 
@@ -29,17 +29,26 @@ export function createDoajTools(
           Type.String({ description: "Sort field, e.g. 'created_date:desc'" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         max_results?: number;
         page?: number;
         sort?: string;
       }) => {
-        const pageSize = Math.min(input.max_results ?? 10, 100);
-        const page = input.page ?? 1;
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error:
+              "query parameter is required and must not be empty. " +
+              "Example: search_doaj({ query: \"open access genomics\" })",
+          });
+        }
+        const pageSize = Math.min(input?.max_results ?? 10, 100);
+        const page = input?.page ?? 1;
 
-        let url = `${BASE}/search/articles/${encodeURIComponent(input.query)}?page=${page}&pageSize=${pageSize}`;
-        if (input.sort) url += `&sort=${encodeURIComponent(input.sort)}`;
+        let url = `${BASE}/search/articles/${encodeURIComponent(query)}?page=${page}&pageSize=${pageSize}`;
+        const sort = validParam(input.sort);
+        if (sort) url += `&sort=${encodeURIComponent(sort)}`;
 
         const tracked = await trackedFetch("doaj", url);
         if (isTrackedError(tracked)) return tracked;

package/src/tools/europe-pmc.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://www.ebi.ac.uk/europepmc/webservices/rest";
 
@@ -31,20 +31,29 @@ export function createEuropePmcTools(
           Type.String({ description: "Pagination cursor (use value from previous response)" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         max_results?: number;
         sort?: string;
         cursor?: string;
       }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error:
+              "query parameter is required and must not be empty. " +
+              "Example: search_europe_pmc({ query: \"CRISPR gene editing\" })",
+          });
+        }
         const params = new URLSearchParams({
-          query: input.query,
+          query,
           format: "json",
           pageSize: String(Math.min(input.max_results ?? 10, 1000)),
           resultType: "core",
         });
-        if (input.sort) params.set("sort", input.sort);
-        params.set("cursorMark", input.cursor ?? "*");
+        const sort = validParam(input.sort);
+        if (sort) params.set("sort", sort);
+        params.set("cursorMark", validParam(input.cursor) ?? "*");
 
         const tracked = await trackedFetch("europe_pmc", `${BASE}/search?${params}`);
         if (isTrackedError(tracked)) return tracked;
@@ -91,11 +100,14 @@ export function createEuropePmcTools(
         ),
         page: Type.Optional(Type.Number({ description: "Page number (default 1)" })),
       }),
-      execute: async (input: { pmid: string; max_results?: number; page?: number }) => {
+      execute: async (_toolCallId: string, input: { pmid: string; max_results?: number; page?: number }) => {
+        if (!input?.pmid) {
+          return toolResult({ error: 'pmid parameter is required (PubMed ID, e.g., "33116299")' });
+        }
         const params = new URLSearchParams({
           format: "json",
-          pageSize: String(input.max_results ?? 25),
-          page: String(input.page ?? 1),
+          pageSize: String(input?.max_results ?? 25),
+          page: String(input?.page ?? 1),
         });
         const tracked = await trackedFetch("europe_pmc", `${BASE}/MED/${input.pmid}/citations?${params}`);
         if (isTrackedError(tracked)) return tracked;
@@ -129,10 +141,13 @@ export function createEuropePmcTools(
           Type.Number({ description: "Max references to return (default 25)" }),
         ),
       }),
-      execute: async (input: { pmid: string; max_results?: number }) => {
+      execute: async (_toolCallId: string, input: { pmid: string; max_results?: number }) => {
+        if (!input?.pmid) {
+          return toolResult({ error: 'pmid parameter is required (PubMed ID, e.g., "33116299")' });
+        }
         const params = new URLSearchParams({
           format: "json",
-          pageSize: String(input.max_results ?? 25),
+          pageSize: String(input?.max_results ?? 25),
         });
         const tracked = await trackedFetch("europe_pmc", `${BASE}/MED/${input.pmid}/references?${params}`);
         if (isTrackedError(tracked)) return tracked;

package/src/tools/hal.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam, validEnum } from "./util.js";
 
 const BASE = "https://api.archives-ouvertes.fr";
 
@@ -49,15 +49,24 @@ export function createHalTools(
           }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         rows?: number;
         sort?: string;
         doc_type?: string;
       }) => {
-        let q = input.query;
-        if (input.doc_type) {
-          q = `(${q}) AND docType_s:${input.doc_type}`;
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error:
+              "query parameter is required and must not be empty. " +
+              "Example: search_hal({ query: \"machine learning\" })",
+          });
+        }
+        let q = query;
+        const docType = validParam(input.doc_type);
+        if (docType) {
+          q = `(${q}) AND docType_s:${docType}`;
         }
 
         const params = new URLSearchParams({
@@ -66,7 +75,8 @@ export function createHalTools(
           rows: String(Math.min(input.rows ?? 10, 100)),
           wt: "json",
         });
-        if (input.sort) params.set("sort", input.sort);
+        const sort = validParam(input.sort);
+        if (sort) params.set("sort", sort);
 
         const result = await trackedFetch(
           "hal",

package/src/tools/inspire-hep.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validEnum, validParam } from "./util.js";
 
 const BASE = "https://inspirehep.net/api";
 
@@ -98,11 +98,19 @@ export function createInspireHepTools(
           }),
         ),
       }),
-      execute: async (input: { query: string; size?: number; sort?: string }) => {
+      execute: async (_toolCallId: string, input: { query: string; size?: number; sort?: string }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error: "query parameter is required and must not be empty.",
+          });
+        }
+
+        const sort = validEnum(input.sort, ["mostrecent", "mostcited", "bestmatch"] as const, "bestmatch");
         const params = new URLSearchParams({
-          q: input.query,
+          q: query,
           size: String(Math.min(input.size ?? 10, 100)),
-          sort: input.sort ?? "bestmatch",
+          sort,
         });
 
         const result = await trackedFetch(
@@ -136,7 +144,10 @@ export function createInspireHepTools(
             "Paper identifier: arXiv ID (e.g. '1207.7214') or DOI (e.g. '10.1016/j.physletb.2012.08.020')",
         }),
       }),
-      execute: async (input: { identifier: string }) => {
+      execute: async (_toolCallId: string, input: { identifier: string }) => {
+        if (!input?.identifier) {
+          return toolResult({ error: 'identifier parameter is required (arXiv ID e.g. "1207.7214" or DOI e.g. "10.1016/j.physletb.2012.08.020")' });
+        }
         // Determine if it's a DOI or arXiv ID
         const id = input.identifier.trim();
         let url: string;

package/src/tools/openaire.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://api.openaire.eu";
 
@@ -112,7 +112,7 @@ export function createOpenAireTools(
           Type.Number({ description: "Max results (default 10, max 50)" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         keywords: string;
         author?: string;
         doi?: string;
@@ -122,17 +122,30 @@ export function createOpenAireTools(
         funder?: string;
         max_results?: number;
       }) => {
+        const keywords = validParam(input?.keywords);
+        if (!keywords) {
+          return toolResult({
+            error:
+              "keywords parameter is required and must not be empty. " +
+              "Example: search_openaire({ keywords: \"machine learning\" })",
+          });
+        }
         const params = new URLSearchParams({
-          keywords: input.keywords,
+          keywords,
           format: "json",
           size: String(Math.min(input.max_results ?? 10, 50)),
         });
-        if (input.author) params.set("author", input.author);
-        if (input.doi) params.set("doi", input.doi);
-        if (input.from_date) params.set("fromDateAccepted", input.from_date);
-        if (input.to_date) params.set("toDateAccepted", input.to_date);
+        const author = validParam(input.author);
+        if (author) params.set("author", author);
+        const doi = validParam(input.doi);
+        if (doi) params.set("doi", doi);
+        const fromDate = validParam(input.from_date);
+        if (fromDate) params.set("fromDateAccepted", fromDate);
+        const toDate = validParam(input.to_date);
+        if (toDate) params.set("toDateAccepted", toDate);
         if (input.oa_only) params.set("OA", "true");
-        if (input.funder) params.set("funder", input.funder);
+        const funder = validParam(input.funder);
+        if (funder) params.set("funder", funder);
 
         const tracked = await trackedFetch("openaire", `${BASE}/search/publications?${params}`, undefined, 15_000);
         if (isTrackedError(tracked)) return tracked;

package/src/tools/openalex.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam, validEnum } from "./util.js";
 
 const BASE = "https://api.openalex.org";
 
@@ -38,7 +38,7 @@ export function createOpenAlexTools(
           }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         limit?: number;
         from_year?: number;
@@ -46,17 +46,27 @@ export function createOpenAlexTools(
         open_access?: boolean;
         sort_by?: string;
       }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({ error: "query parameter is required and must not be empty" });
+        }
+
+        const SORT_BY = ["cited_by_count", "publication_date", "relevance_score"] as const;
+
         const filters: string[] = [];
         if (input.from_year) filters.push(`from_publication_date:${input.from_year}-01-01`);
         if (input.to_year) filters.push(`to_publication_date:${input.to_year}-12-31`);
         if (input.open_access) filters.push("is_oa:true");
 
         const params = new URLSearchParams({
-          search: input.query,
+          search: query,
           per_page: String(Math.min(input.limit ?? 10, 200)),
         });
         if (filters.length > 0) params.set("filter", filters.join(","));
-        if (input.sort_by) params.set("sort", input.sort_by);
+        const sortBy = validParam(input.sort_by);
+        if (sortBy && (SORT_BY as readonly string[]).includes(sortBy)) {
+          params.set("sort", sortBy);
+        }
 
         const tracked = await trackedFetch("openalex", `${BASE}/works?${params}`, { headers });
         if (isTrackedError(tracked)) return tracked;
@@ -93,7 +103,7 @@ export function createOpenAlexTools(
             "Work identifier: OpenAlex ID (e.g. 'W2741809807'), DOI URL, or PMID",
         }),
       }),
-      execute: async (input: { work_id: string }) => {
+      execute: async (_toolCallId: string, input: { work_id: string }) => {
         if (!input?.work_id) {
           return toolResult({ error: 'work_id parameter is required (e.g., "W2741809807" or a DOI like "10.1234/example")' });
         }
@@ -137,7 +147,7 @@ export function createOpenAlexTools(
             "Author identifier: OpenAlex ID (e.g. 'A5023888391'), ORCID, or name search",
         }),
       }),
-      execute: async (input: { author_id: string }) => {
+      execute: async (_toolCallId: string, input: { author_id: string }) => {
         if (!input?.author_id) {
           return toolResult({ error: 'author_id parameter is required (OpenAlex ID e.g. "A5023888391", ORCID, or author name)' });
         }

package/src/tools/opencitations.ts

@@ -28,7 +28,7 @@ export function createOpenCitationsTools(
           description: "DOI of the paper, e.g. '10.1038/nature12373'",
         }),
       }),
-      execute: async (input: { doi: string }) => {
+      execute: async (_toolCallId: string, input: { doi: string }) => {
         if (!input?.doi) {
           return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
         }
@@ -60,7 +60,7 @@ export function createOpenCitationsTools(
           description: "DOI of the paper, e.g. '10.1038/nature12373'",
         }),
       }),
-      execute: async (input: { doi: string }) => {
+      execute: async (_toolCallId: string, input: { doi: string }) => {
         if (!input?.doi) {
           return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
         }
@@ -92,7 +92,7 @@ export function createOpenCitationsTools(
           description: "DOI of the paper, e.g. '10.1038/nature12373'",
         }),
       }),
-      execute: async (input: { doi: string }) => {
+      execute: async (_toolCallId: string, input: { doi: string }) => {
         if (!input?.doi) {
           return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
         }

package/src/tools/orcid.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://pub.orcid.org/v3.0";
 
@@ -27,9 +27,16 @@ export function createOrcidTools(
           Type.Number({ description: "Max results (default 10, max 100)" }),
         ),
       }),
-      execute: async (input: { query: string; limit?: number }) => {
+      execute: async (_toolCallId: string, input: { query: string; limit?: number }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error: "query parameter is required and must not be empty.",
+          });
+        }
+
         const params = new URLSearchParams({
-          q: input.query,
+          q: query,
           rows: String(Math.min(input.limit ?? 10, 100)),
         });
 
@@ -71,7 +78,7 @@ export function createOrcidTools(
           description: "ORCID iD, e.g. '0000-0002-1825-0097'",
         }),
       }),
-      execute: async (input: { orcid: string }) => {
+      execute: async (_toolCallId: string, input: { orcid: string }) => {
         if (!input?.orcid) {
           return toolResult({ error: 'orcid parameter is required (e.g., "0000-0002-1825-0097")' });
         }

package/src/tools/osf-preprints.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam } from "./util.js";
 
 const BASE = "https://api.osf.io/v2";
 
@@ -28,16 +28,17 @@ export function createOsfPreprintsTools(
           Type.Number({ description: "Page number (default 1)" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         provider?: string;
         size?: number;
         page?: number;
       }) => {
         const params = new URLSearchParams({
-          "page[size]": String(Math.min(input.size ?? 10, 100)),
+          "page[size]": String(Math.min(input?.size ?? 10, 100)),
         });
-        if (input.provider) params.set("filter[provider]", input.provider);
-        if (input.page) params.set("page", String(input.page));
+        const provider = validParam(input?.provider);
+        if (provider) params.set("filter[provider]", provider);
+        if (input?.page) params.set("page", String(input.page));
 
         const result = await trackedFetch(
           "osf_preprints",
@@ -57,7 +58,7 @@ export function createOsfPreprintsTools(
 
         return toolResult({
           total_results: linksMeta?.total,
-          page: input.page ?? 1,
+          page: input?.page ?? 1,
           source: "osf_preprints",
           preprints: (items ?? []).map((item) => {
             const attrs = item.attributes as Record<string, unknown> | undefined;

package/src/tools/pubmed.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError, validParam, validEnum } from "./util.js";
 
 const EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 
@@ -34,24 +34,37 @@ export function createPubMedTools(
           Type.String({ description: "Max publication date (YYYY/MM/DD)" }),
         ),
       }),
-      execute: async (input: {
+      execute: async (_toolCallId: string, input: {
         query: string;
         max_results?: number;
         sort?: string;
         min_date?: string;
         max_date?: string;
       }) => {
+        const query = validParam(input?.query);
+        if (!query) {
+          return toolResult({
+            error:
+              "query parameter is required and must not be empty. " +
+              "Example: search_pubmed({ query: \"CRISPR[Title] AND 2024[PDAT]\" })",
+          });
+        }
+
+        const sort = validEnum(input.sort, ["relevance", "pub_date"] as const, "relevance");
+        const minDate = validParam(input.min_date);
+        const maxDate = validParam(input.max_date);
+
         const searchParams = new URLSearchParams({
           db: "pubmed",
-          term: input.query,
+          term: query,
           retmax: String(Math.min(input.max_results ?? 10, 100)),
           retmode: "json",
-          sort: input.sort ?? "relevance",
+          sort,
           usehistory: "y",
         });
-        if (input.min_date) searchParams.set("mindate", input.min_date);
-        if (input.max_date) searchParams.set("maxdate", input.max_date);
-        if (input.min_date || input.max_date) searchParams.set("datetype", "pdat");
+        if (minDate) searchParams.set("mindate", minDate);
+        if (maxDate) searchParams.set("maxdate", maxDate);
+        if (minDate || maxDate) searchParams.set("datetype", "pdat");
 
         const searchTracked = await trackedFetch("pubmed", `${EUTILS}/esearch.fcgi?${searchParams}`);
         if (isTrackedError(searchTracked)) return searchTracked;
@@ -108,7 +121,7 @@ export function createPubMedTools(
       parameters: Type.Object({
         pmid: Type.String({ description: "PubMed ID (numeric string)" }),
       }),
-      execute: async (input: { pmid: string }) => {
+      execute: async (_toolCallId: string, input: { pmid: string }) => {
         if (!input?.pmid) {
           return toolResult({ error: 'pmid parameter is required (numeric PubMed ID, e.g., "33116299")' });
         }