Skip to main content
Glama
mnhlt

WebSearch-MCP

by mnhlt
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

web_search

Search the web to retrieve up-to-date information on any topic, including news, blogs, companies, and events.

Instructions

Search the web for information. Use this tool when you need to search the web for information. You can use this tool to search for news, blogs, or all types of information. You can also use this tool to search for information about a specific company or product. You can also use this tool to search for information about a specific person. You can also use this tool to search for information about a specific product. You can also use this tool to search for information about a specific company. You can also use this tool to search for information about a specific event. You can also use this tool to search for information about a specific location. You can also use this tool to search for information about a specific thing. If you request search with 1 result number and failed, retry with bigger results number.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesThe search query to look up
numResultsNoNumber of results to return (default: 5)
languageNoLanguage code for search results (e.g., 'en')
regionNoRegion code for search results (e.g., 'us')
excludeDomainsNoDomains to exclude from results
includeDomainsNoOnly include these domains in results
excludeTermsNoTerms to exclude from results
resultTypeNoType of results to return

Implementation Reference

  • src/index.ts:52-172 (registration)
    Registers the 'web_search' tool on the MCP server using server.tool() with tool name 'web_search', description, Zod schema for input params, and the async handler callback.
    server.tool(
  "web_search",
  "Search the web for information.\n"
  + "Use this tool when you need to search the web for information.\n"
  + "You can use this tool to search for news, blogs, or all types of information.\n"
  + "You can also use this tool to search for information about a specific company or product.\n"
  + "You can also use this tool to search for information about a specific person.\n"
  + "You can also use this tool to search for information about a specific product.\n"
  + "You can also use this tool to search for information about a specific company.\n"
  + "You can also use this tool to search for information about a specific event.\n"
  + "You can also use this tool to search for information about a specific location.\n"
  + "You can also use this tool to search for information about a specific thing.\n"
  + "If you request search with 1 result number and failed, retry with bigger results number.",
  {
    query: z.string().describe("The search query to look up"),
    numResults: z
      .number()
      .optional()
      .describe(
        `Number of results to return (default: ${MAX_SEARCH_RESULT})`
      ),
    language: z
      .string()
      .optional()
      .describe("Language code for search results (e.g., 'en')"),
    region: z
      .string()
      .optional()
      .describe("Region code for search results (e.g., 'us')"),
    excludeDomains: z
      .array(z.string())
      .optional()
      .describe("Domains to exclude from results"),
    includeDomains: z
      .array(z.string())
      .optional()
      .describe("Only include these domains in results"),
    excludeTerms: z
      .array(z.string())
      .optional()
      .describe("Terms to exclude from results"),
    resultType: z
      .enum(["all", "news", "blogs"])
      .optional()
      .describe("Type of results to return"),
  },
  async (params) => {
    try {
      console.error(`Performing web search for: ${params.query}`);

      // Prepare request payload for crawler API
      const requestPayload: CrawlRequest = {
        query: params.query,
        numResults: params.numResults ?? MAX_SEARCH_RESULT,
        language: params.language,
        region: params.region,
        filters: {
          excludeDomains: params.excludeDomains,
          includeDomains: params.includeDomains,
          excludeTerms: params.excludeTerms,
          resultType: params.resultType as "all" | "news" | "blogs",
        },
      };

      // Call the crawler API
      console.error(`Sending request to ${API_URL}/crawl`);
      const response = await axios.post<CrawlResponse>(
        `${API_URL}/crawl`,
        requestPayload
      );

      // Format the response for the MCP client
      const results = response.data.results.map((result) => ({
        title: result.title,
        snippet: result.excerpt,
        text: result.text,
        url: result.url,
        siteName: result.siteName || "",
        byline: result.byline || "",
      }));

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                query: response.data.query,
                results: results,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      console.error("Error performing web search:", error);

      if (axios.isAxiosError(error)) {
        const errorMessage = error.response?.data?.error || error.message;
        return {
          content: [{ type: "text", text: `Error: ${errorMessage}` }],
          isError: true,
        };
      }

      return {
        content: [
          {
            type: "text",
            text: `Error: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
        isError: true,
      };
    }
  }
);
  • src/index.ts:65-97 (schema)
    Zod schema defining input parameters for web_search: query (string, required), numResults (optional number), language (optional string), region (optional string), excludeDomains (optional string array), includeDomains (optional string array), excludeTerms (optional string array), resultType (optional enum: 'all'|'news'|'blogs').
    {
  query: z.string().describe("The search query to look up"),
  numResults: z
    .number()
    .optional()
    .describe(
      `Number of results to return (default: ${MAX_SEARCH_RESULT})`
    ),
  language: z
    .string()
    .optional()
    .describe("Language code for search results (e.g., 'en')"),
  region: z
    .string()
    .optional()
    .describe("Region code for search results (e.g., 'us')"),
  excludeDomains: z
    .array(z.string())
    .optional()
    .describe("Domains to exclude from results"),
  includeDomains: z
    .array(z.string())
    .optional()
    .describe("Only include these domains in results"),
  excludeTerms: z
    .array(z.string())
    .optional()
    .describe("Terms to exclude from results"),
  resultType: z
    .enum(["all", "news", "blogs"])
    .optional()
    .describe("Type of results to return"),
},
  • src/index.ts:98-172 (handler)
    Async handler function that executes the web search logic: builds a CrawlRequest payload from params, calls an external crawler API via axios.post(), formats the response results (title, snippet, text, url, siteName, byline), and returns the formatted content as JSON string. Includes error handling for Axios errors and general exceptions.
      async (params) => {
    try {
      console.error(`Performing web search for: ${params.query}`);

      // Prepare request payload for crawler API
      const requestPayload: CrawlRequest = {
        query: params.query,
        numResults: params.numResults ?? MAX_SEARCH_RESULT,
        language: params.language,
        region: params.region,
        filters: {
          excludeDomains: params.excludeDomains,
          includeDomains: params.includeDomains,
          excludeTerms: params.excludeTerms,
          resultType: params.resultType as "all" | "news" | "blogs",
        },
      };

      // Call the crawler API
      console.error(`Sending request to ${API_URL}/crawl`);
      const response = await axios.post<CrawlResponse>(
        `${API_URL}/crawl`,
        requestPayload
      );

      // Format the response for the MCP client
      const results = response.data.results.map((result) => ({
        title: result.title,
        snippet: result.excerpt,
        text: result.text,
        url: result.url,
        siteName: result.siteName || "",
        byline: result.byline || "",
      }));

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                query: response.data.query,
                results: results,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      console.error("Error performing web search:", error);

      if (axios.isAxiosError(error)) {
        const errorMessage = error.response?.data?.error || error.message;
        return {
          content: [{ type: "text", text: `Error: ${errorMessage}` }],
          isError: true,
        };
      }

      return {
        content: [
          {
            type: "text",
            text: `Error: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
        isError: true,
      };
    }
  }
);
  • src/index.ts:8-10 (helper)
    Configuration constants: API_URL (from env, default http://localhost:3001) and MAX_SEARCH_RESULT (from env, default 5) used by the web_search tool.
    // Configuration
const API_URL = process.env.API_URL || "http://localhost:3001";
const MAX_SEARCH_RESULT = parseInt(process.env.MAX_SEARCH_RESULT || "5", 10);
  • src/index.ts:13-41 (helper)
    TypeScript interfaces (CrawlRequest, CrawlResult, CrawlResponse) defining the data structures used by the web_search tool when communicating with the backend crawler API.
    interface CrawlRequest {
  query: string;
  numResults?: number;
  language?: string;
  region?: string;
  filters?: {
    excludeDomains?: string[];
    includeDomains?: string[];
    excludeTerms?: string[];
    resultType?: "all" | "news" | "blogs";
  };
}

interface CrawlResult {
  url: string;
  title: string;
  excerpt: string;
  text?: string;
  html?: string;
  siteName?: string;
  byline?: string;
  error?: string | null;
}

interface CrawlResponse {
  query: string;
  results: CrawlResult[];
  error: string | null;
}

Tool Definition Quality

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not mention potential side effects, rate limits, or permissions. The only behavioral detail is the retry advice, which is insufficient for a tool performing external web requests.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly repetitive, listing 'You can also use this tool to search for...' multiple times, which adds no value and wastes tokens. The retry advice is useful but could be condensed. A single sentence covering the core function and filtering options would suffice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters and no output schema, the description provides a basic overview but lacks details on pagination, error handling beyond the retry note, and the structure of results. The schema covers parameter details, but the description does not fully fill the gaps for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 8 parameters have descriptions in the schema, so the schema coverage is 100%. The description adds no additional parameter-specific information beyond what is in the schema, matching the baseline expectation. The retry advice does not relate to parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search the web for information,' which defines the tool's purpose. However, it lacks specificity and reads as a general search tool rather than highlighting unique capabilities. There are no sibling tools, so no need for differentiation, but the description could be more concise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit guidance on when to use ('when you need to search the web') and a specific retry strategy for failed requests with small result numbers. No siblings exist, so no alternatives to discuss, but the guidance is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mnhlt/WebSearch-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server