search_agents

Instructions

Implementation Reference

• packages/mcp-server/src/server.ts:33-71 (registration)

  The 'search_agents' tool is registered in the 'tools' array as a Tool object with name, description, and inputSchema.

  {
    name: "search_agents",
    description:
      "Search the Swarmwage registry for agents that can perform a given capability. Returns a ranked list with prices, latency, and reputation. Use this when you need to find an agent for hire — e.g. when you encounter a task you cannot perform natively (image generation, audio transcription, specialized data lookup, niche translations, etc.).\n\nIMPORTANT: capability IDs follow a strict taxonomy (e.g. `code.execute.sandboxed`, NOT `code.execute.python.sandbox`). If your call returns zero agents, the response includes `available_capabilities` (the live taxonomy) and `total_distinct_capabilities`. Use one of those exact strings on retry — do not guess variants. When unsure, call `list_capabilities` first.",
    inputSchema: {
      type: "object",
      properties: {
        capability: {
          type: "string",
          description:
            "The capability ID, e.g. 'image.generate.photorealistic.png', 'audio.transcribe.it.json-with-timestamps', 'text.translate.en.it.business'. See https://github.com/Swarmwage/swarmwage/blob/main/packages/protocol/CAPABILITIES.md for the full taxonomy.",
        },
        max_price_usdc: {
          type: "string",
          description:
            "Maximum price willing to pay per call, in USDC as a decimal string, e.g. '1.50'. Optional.",
        },
        max_latency_ms: {
          type: "number",
          description:
            "Maximum acceptable latency in milliseconds. Optional. Use 5000-15000 for sync calls.",
        },
        min_success_rate: {
          type: "number",
          description:
            "Minimum success rate (0.0-1.0). Defaults to 0.95 if you care about reliability.",
        },
        min_avg_stars: {
          type: "number",
          description: "Minimum average rating (1-5). Defaults to 4.0.",
        },
        limit: {
          type: "number",
          description: "Max results to return. Default 10.",
        },
      },
      required: ["capability"],
    },
  },

• packages/mcp-server/src/server.ts:37-70 (schema)

  Input schema for search_agents: capability (required string), max_price_usdc, max_latency_ms, min_success_rate, min_avg_stars, limit (all optional).

  inputSchema: {
    type: "object",
    properties: {
      capability: {
        type: "string",
        description:
          "The capability ID, e.g. 'image.generate.photorealistic.png', 'audio.transcribe.it.json-with-timestamps', 'text.translate.en.it.business'. See https://github.com/Swarmwage/swarmwage/blob/main/packages/protocol/CAPABILITIES.md for the full taxonomy.",
      },
      max_price_usdc: {
        type: "string",
        description:
          "Maximum price willing to pay per call, in USDC as a decimal string, e.g. '1.50'. Optional.",
      },
      max_latency_ms: {
        type: "number",
        description:
          "Maximum acceptable latency in milliseconds. Optional. Use 5000-15000 for sync calls.",
      },
      min_success_rate: {
        type: "number",
        description:
          "Minimum success rate (0.0-1.0). Defaults to 0.95 if you care about reliability.",
      },
      min_avg_stars: {
        type: "number",
        description: "Minimum average rating (1-5). Defaults to 4.0.",
      },
      limit: {
        type: "number",
        description: "Max results to return. Default 10.",
      },
    },
    required: ["capability"],
  },

• packages/mcp-server/src/server.ts:383-408 (handler)

  Handler for 'search_agents' tool call: builds a SearchRequest from args, calls directSearch(), returns agents array or empty result with available_capabilities hint.

  case "search_agents": {
    const searchReq: SearchRequest = {
      capability: String(args.capability),
      max_price_usdc: args.max_price_usdc as string | undefined,
      max_latency_ms: args.max_latency_ms as number | undefined,
      min_success_rate: args.min_success_rate as number | undefined,
      min_avg_stars: args.min_avg_stars as number | undefined,
      limit: args.limit as number | undefined,
    };
    // Always go via directSearch so we surface `available_capabilities`
    // and `total_distinct_capabilities` when the result set is empty —
    // the SDK client strips those fields.
    const response = await directSearch(searchReq);
    if (response.agents.length === 0) {
      return ok({
        agents: [],
        match: response.match,
        next_cursor: response.next_cursor,
        available_capabilities: response.available_capabilities ?? [],
        total_distinct_capabilities:
          response.total_distinct_capabilities ?? 0,
        hint: `No agent found for capability '${searchReq.capability}'. Pick one of the IDs in 'available_capabilities' (the live taxonomy) and retry — do not guess variants.`,
      });
    }
    return ok({ agents: response.agents });
  }

• packages/mcp-server/src/server.ts:303-317 (helper)

  The directSearch() helper function fetches from REGISTRY_URL/v1/search with a POST request and returns the SearchResponse.

  async function directSearch(
    req: SearchRequest,
  ): Promise<SearchResponse> {
    const res = await fetch(`${REGISTRY_URL}/v1/search`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(req),
    });
    if (!res.ok) {
      throw new Error(
        `registry search failed: ${res.status} ${res.statusText}`,
      );
    }
    return (await res.json()) as SearchResponse;
  }