wpnav_search_tools

Instructions

Implementation Reference

• src/tools/core/search-tools.ts:89-173 (handler)

  Handler for wpnav_search_tools: validates input, performs semantic search via embeddings or category filtering, and returns tool names, descriptions, and categories in JSON format.

  export async function searchToolsHandler(
    args: { query?: string; category?: string; limit?: number },
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    context: any
  ): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
    const { query, category, limit = 10 } = args;
  
    // Validate: at least one of query or category required
    if (!query && !category) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                error: 'At least one of query or category is required',
                available_categories: VALID_CATEGORIES,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  
    // Validate category if provided
    if (category && !VALID_CATEGORIES.includes(category as ValidCategory)) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                error: `Invalid category: ${category}`,
                available_categories: VALID_CATEGORIES,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  
    // Clamp limit to valid range
    const effectiveLimit = Math.max(1, Math.min(25, limit));
  
    let results: ToolSearchResult[];
  
    if (query && category) {
      // Combined: semantic search then filter by category
      // Search with higher limit to ensure we get enough after filtering
      const searchResults = embeddingsSearch(query, { limit: effectiveLimit * 3 });
      results = searchResults.filter((r) => r.category.toLowerCase() === category.toLowerCase());
      results = results.slice(0, effectiveLimit);
    } else if (query) {
      // Query only: semantic search
      results = embeddingsSearch(query, { limit: effectiveLimit });
    } else {
      // Category only: filter by category
      const categoryResults = searchByCategory(category!);
      results = categoryResults.slice(0, effectiveLimit);
    }
  
    // Build response
    const response: SearchToolsResponse = {
      tools: results.map((r) => ({
        name: r.name,
        description: r.description,
        category: r.category,
      })),
      total_matching: results.length,
      hint: 'Use wpnav_describe_tools to get full schemas for these tools',
    };
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response, null, 2),
        },
      ],
    };
  }

• src/tools/core/search-tools.ts:40-66 (schema)

  Tool definition object for wpnav_search_tools, including name, description, and detailed inputSchema with properties for query, category (enum), and limit.

  export const searchToolsDefinition = {
    name: 'wpnav_search_tools',
    description:
      'Find WP Navigator tools by natural language query or category. Returns tool names and brief descriptions only (not full schemas). Use wpnav_describe_tools to get full schemas for tools you want to use.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        query: {
          type: 'string',
          description:
            'Natural language search query (e.g., "create a blog post", "manage plugins", "edit pages")',
        },
        category: {
          type: 'string',
          enum: VALID_CATEGORIES as unknown as string[],
          description: 'Filter by tool category',
        },
        limit: {
          type: 'number',
          default: 10,
          maximum: 25,
          minimum: 1,
          description: 'Maximum number of results (default: 10, max: 25)',
        },
      },
    },
  };

• src/tools/core/search-tools.ts:178-184 (registration)

  Registration function that registers the wpnav_search_tools with the toolRegistry using its definition and handler.

  export function registerSearchTools(): void {
    toolRegistry.register({
      definition: searchToolsDefinition,
      handler: searchToolsHandler,
      category: ToolCategory.CORE,
    });
  }

• src/tools/core/index.ts:336-336 (registration)

  Invocation of registerSearchTools() as part of core tools registration in the index file.

  registerSearchTools();