feat: add 30 specialized SerpApi tools by galetahub · Pull Request #1 · serpapi/serpapi-openclaw-plugin

galetahub · 2026-07-09T16:05:57Z

Summary

Adds 30 specialized SerpApi tools to the plugin.
Each tool follows the same pattern: a createSerpApi<X>Tool(api, ctx) factory returning an AnyAgentTool, a per-engine ALLOWED_PARAMS security allowlist, and an extract() shaping function.

Tools

Tool	Description
`serpapi_amazon`	Search Amazon for products.
`serpapi_amazon_product`	Fetch detailed Amazon product info by ASIN.
`serpapi_autocomplete`	Google search autocomplete suggestions for a partial query.
`serpapi_bing`	Web search via Bing.
`serpapi_duckduckgo`	Web search via DuckDuckGo (organic results, knowledge graph, news).
`serpapi_ebay`	Search eBay listings.
`serpapi_ebay_product`	Detailed eBay product info by product ID.
`serpapi_events`	Local events via Google Events.
`serpapi_facebook_profile`	Fetch a public Facebook profile.
`serpapi_finance`	Stock prices, currency rates, and crypto via Google Finance.
`serpapi_flights`	Real flight prices and itineraries via Google Flights.
`serpapi_hotels`	Hotels and accommodation via Google Hotels.
`serpapi_immersive_product`	Detailed Google product info by `page_token` from Shopping results.
`serpapi_instagram_profile`	Fetch a public Instagram profile.
`serpapi_jobs`	Google Jobs search.
`serpapi_lens`	Google Lens reverse image search.
`serpapi_maps`	Local businesses, restaurants, and POIs via Google Maps.
`serpapi_maps_reviews`	Reviews for a place on Google Maps.
`serpapi_news`	Recent articles via Google News.
`serpapi_scholar`	Academic papers, research articles, and citations via Google Scholar.
`serpapi_shopping`	Google Shopping product search.
`serpapi_trends`	Google Trends: interest over time, by region, related topics/queries.
`serpapi_tripadvisor`	Destinations, hotels, restaurants, and attractions via Tripadvisor.
`serpapi_walmart`	Walmart product listings.
`serpapi_walmart_product`	Detailed Walmart product info by product ID.
`serpapi_weather`	Current weather or forecast for a location via Google.
`serpapi_yahoo`	Web search via Yahoo!.
`serpapi_youtube`	YouTube search: videos, channels, shorts.
`serpapi_youtube_transcript`	Fetch the transcript of a YouTube video.
`serpapi_youtube_video`	YouTube video metadata: title, channel, views, chapters.

Changes

src/tools/*.ts — 30 tool implementations + barrel (src/tools/index.ts).
src/utils.ts — shared resolveToolConfig / readBooleanArg tool helpers.
index.ts — register all 30 tools alongside the web search provider.
openclaw.plugin.json — declare all 30 ids in contracts.tools.
skills/serpapi/SKILL.md — per-tool parameter and usage docs.
README.md — updated tool list.

Copilot

Pull request overview

This PR expands the SerpApi OpenClaw plugin from just a web_search provider to a broader suite of specialized SerpApi-backed tools, and wires them into the plugin contract/registration and documentation.

Changes:

Adds shared tool helpers (resolveToolConfig, readBooleanArg) to support consistent runtime config resolution and boolean argument parsing.
Introduces 30 specialized SerpApi tools (plus a barrel export) and registers them in the plugin entrypoint.
Updates plugin contracts and user-facing documentation (README + SerpApi skill docs) to reflect the new tool surface area.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/utils.ts	Adds shared helpers for tool config resolution and boolean argument parsing.
src/tools/amazon.ts	Adds `serpapi_amazon` tool implementation.
src/tools/amazon-product.ts	Adds `serpapi_amazon_product` tool implementation.
src/tools/autocomplete.ts	Adds `serpapi_autocomplete` tool implementation.
src/tools/bing.ts	Adds `serpapi_bing` tool implementation.
src/tools/duckduckgo.ts	Adds `serpapi_duckduckgo` tool implementation.
src/tools/ebay.ts	Adds `serpapi_ebay` tool implementation.
src/tools/ebay-product.ts	Adds `serpapi_ebay_product` tool implementation.
src/tools/events.ts	Adds `serpapi_events` tool implementation.
src/tools/facebook-profile.ts	Adds `serpapi_facebook_profile` tool implementation.
src/tools/finance.ts	Adds `serpapi_finance` tool implementation.
src/tools/flights.ts	Adds `serpapi_flights` tool implementation.
src/tools/hotels.ts	Adds `serpapi_hotels` tool implementation.
src/tools/immersive-product.ts	Adds `serpapi_immersive_product` tool implementation.
src/tools/instagram-profile.ts	Adds `serpapi_instagram_profile` tool implementation.
src/tools/jobs.ts	Adds `serpapi_jobs` tool implementation.
src/tools/lens.ts	Adds `serpapi_lens` tool implementation.
src/tools/maps.ts	Adds `serpapi_maps` tool implementation.
src/tools/maps-reviews.ts	Adds `serpapi_maps_reviews` tool implementation.
src/tools/news.ts	Adds `serpapi_news` tool implementation.
src/tools/scholar.ts	Adds `serpapi_scholar` tool implementation.
src/tools/shopping.ts	Adds `serpapi_shopping` tool implementation.
src/tools/trends.ts	Adds `serpapi_trends` tool implementation.
src/tools/tripadvisor.ts	Adds `serpapi_tripadvisor` tool implementation.
src/tools/walmart.ts	Adds `serpapi_walmart` tool implementation.
src/tools/walmart-product.ts	Adds `serpapi_walmart_product` tool implementation.
src/tools/weather.ts	Adds `serpapi_weather` tool implementation.
src/tools/yahoo.ts	Adds `serpapi_yahoo` tool implementation.
src/tools/youtube.ts	Adds `serpapi_youtube` tool implementation.
src/tools/youtube-video.ts	Adds `serpapi_youtube_video` tool implementation.
src/tools/youtube-transcript.ts	Adds `serpapi_youtube_transcript` tool implementation.
src/tools/index.ts	Adds barrel exports for all specialized tools.
index.ts	Registers the 30 specialized tools in the plugin entrypoint.
openclaw.plugin.json	Declares the tool IDs under `contracts.tools` and updates plugin metadata.
skills/serpapi/SKILL.md	Expands skill documentation with per-tool parameters and usage guidance.
README.md	Updates README to reflect the additional specialized tools and docs link.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 6 comments.

galetahub · 2026-07-09T19:37:06Z

+import type { AnyAgentTool } from "openclaw/plugin-sdk/plugin-entry";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-runtime";
+import { jsonResult, readStringParam } from "openclaw/plugin-sdk/provider-web-search";
+import { callSerpApi } from "../serpapi-client.js";
+import { type SerpApiToolCtx, resolveToolConfig } from "../utils.js";
+
+const ALLOWED_PARAMS = ["search_query", "hl", "sp", "zero_trace"] as const;
+
+function extract(raw: Record<string, unknown>): Record<string, unknown> {
+  return {
+    engine: "youtube",
+    channel_results: raw.channel_results ?? [],
+    video_results: raw.video_results ?? [],
+    shorts_results: raw.shorts_results ?? [],
+  };
+}


Thanks for flagging this. We're intentionally not wrapping these fields with wrapWebContent for now.

The engine youtube returns the raw SerpApi result objects as structured JSON.

+    execute: async (_toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal) => {
+      const cfg = resolveToolConfig(api, ctx);
+      const raw = await callSerpApi({
+        cfg,
+        engine: "google_flights",
+        allowedParams: ALLOWED_PARAMS,
+        params: {
+          departure_id: readStringParam(args, "departure_id", { required: true }),
+          arrival_id: readStringParam(args, "arrival_id", { required: true }),
+          outbound_date: readStringParam(args, "outbound_date", { required: true }),
+          return_date: readStringParam(args, "return_date") ?? undefined,
+          type: readStringParam(args, "type") ?? undefined,
+          adults: readNumberParam(args, "adults", { integer: true }) ?? undefined,
+          currency: readStringParam(args, "currency") ?? undefined,
+          gl: readStringParam(args, "gl") ?? undefined,
+        },
+        signal,
+      });
+      return jsonResult(extract(raw));
+    },


galetahub · 2026-07-09T19:38:25Z

+import {
+  jsonResult,
+  readNumberParam,
+  readStringParam,
+} from "openclaw/plugin-sdk/provider-web-search";


Thanks for flagging this. We're intentionally not wrapping these fields with wrapWebContent for now.

The engine google_news returns the raw SerpApi result objects as structured JSON.

galetahub · 2026-07-09T19:38:53Z

+function extract(raw: Record<string, unknown>, maxCount: number): Record<string, unknown> {
+  const results = Array.isArray(raw.news_results)
+    ? (raw.news_results as unknown[]).slice(0, maxCount)
+    : [];
+  return {
+    engine: "google_news",
+    results,
+    menu_links: raw.menu_links ?? [],
+    related_topics: raw.related_topics ?? [],
+    related_publications: raw.related_publications ?? [],
+  };
+}


Thanks for flagging this. We're intentionally not wrapping these fields with wrapWebContent for now.

The engine google_news returns the raw SerpApi result objects as structured JSON.

galetahub · 2026-07-09T19:39:14Z

+import {
+  jsonResult,
+  readNumberParam,
+  readStringParam,
+} from "openclaw/plugin-sdk/provider-web-search";


Thanks for flagging this. We're intentionally not wrapping these fields with wrapWebContent for now.

The engine google_scholar returns the raw SerpApi result objects as structured JSON.

galetahub · 2026-07-09T19:39:09Z

+function extract(raw: Record<string, unknown>, maxCount: number): Record<string, unknown> {
+  const results = Array.isArray(raw.organic_results)
+    ? (raw.organic_results as unknown[]).slice(0, maxCount)
+    : [];
+  return {
+    engine: "google_scholar",
+    results,
+    related_searches: raw.related_searches ?? [],
+  };
+}


Thanks for flagging this. We're intentionally not wrapping these fields with wrapWebContent for now.

The engine google_scholar returns the raw SerpApi result objects as structured JSON.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 6 comments.

galetahub · 2026-07-10T14:10:21Z

+      const cfg = resolveToolConfig(api, ctx);
+      const searchAssist = readBooleanArg(args, "search_assist");
+      const searchAssistParam = searchAssist === true ? "true" : undefined;
+      const m = readNumberParam(args, "m", { integer: true });


Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 3 comments.

galetahub · 2026-07-13T14:33:21Z

+    execute: async (_toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal) => {
+      const cfg = resolveToolConfig(api, ctx);
+      const raw = await callSerpApi({
+        cfg,
+        engine: "google_autocomplete",
+        allowedParams: ALLOWED_PARAMS,
+        params: {
+          q: readStringParam(args, "query", { required: true }),
+          gl: readStringParam(args, "gl") ?? undefined,
+          hl: readStringParam(args, "hl") ?? undefined,
+          cp: readNumberParam(args, "cp", { integer: true }) ?? undefined,
+          client: readStringParam(args, "client") ?? undefined,
+        },


We should not send an explicit cp default here.

Unlike safeSearch: "Moderate" or type: "all", cp is not a fixed enum default it is derived from the query string. Computing query.length in the plugin assumes we replicate Google/SerpApi cursor semantics exactly, including edge cases we do not control (UTF-16 code units vs graphemes, combining characters, surrogate pairs, etc.). A wrong guess would change suggestion ranking for non-ASCII queries.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated no new comments.

feat: add 30 specialized SerpApi tools

c5b065c

galetahub requested a review from Copilot July 9, 2026 16:06

Copilot started reviewing on behalf of galetahub July 9, 2026 16:06 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread skills/serpapi/SKILL.md

Comment thread openclaw.plugin.json Outdated

Comment thread index.ts Outdated

galetahub self-assigned this Jul 9, 2026

docs: add enabled flag, clarify provider scope

90f1f0b

galetahub requested a review from Copilot July 9, 2026 17:12

Copilot started reviewing on behalf of galetahub July 9, 2026 17:12 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/tools/hotels.ts Outdated

fix: hotels date validation

6718f3a

galetahub requested a review from Copilot July 9, 2026 18:57

Copilot started reviewing on behalf of galetahub July 9, 2026 18:57 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

galetahub requested a review from Copilot July 9, 2026 19:39

Copilot started reviewing on behalf of galetahub July 9, 2026 19:39 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/tools/trends.ts

Comment thread src/tools/trends.ts Outdated

Comment thread src/tools/hotels.ts

Comment thread src/tools/flights.ts Outdated

fix: switch cat to number/integer

db704ee

galetahub requested a review from Copilot July 10, 2026 09:59

Copilot started reviewing on behalf of galetahub July 10, 2026 10:00 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

docs: align tool defaults and schemas with SKILL.md documentation

d3d9472

galetahub requested a review from Copilot July 10, 2026 14:10

Copilot started reviewing on behalf of galetahub July 10, 2026 14:11 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/tools/amazon.ts

fix: remove duplicated relevanceblender value for s param

cb6aa20

galetahub requested a review from Copilot July 10, 2026 16:41

Copilot started reviewing on behalf of galetahub July 10, 2026 16:42 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/tools/yahoo.ts

fix: return empty array for related_searches

b354273

galetahub requested a review from Copilot July 13, 2026 11:20

Copilot started reviewing on behalf of galetahub July 13, 2026 11:21 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

fix: send documented defaults for bing safeSearch and lens type

3d411ba

galetahub requested a review from Copilot July 13, 2026 14:34

Copilot started reviewing on behalf of galetahub July 13, 2026 14:34 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

galetahub requested a review from ilyazub July 13, 2026 14:57

Uh oh!

Conversation

galetahub commented Jul 9, 2026

Summary

Tools

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

galetahub Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

galetahub Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

galetahub Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

galetahub Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

galetahub Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

galetahub Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

galetahub Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment