hou_tea_browse

Instructions

Implementation Reference

• src/tools/registry.ts:106-106 (handler)

  The executor function for hou_tea_browse — calls houTea.catalog() with the parsed arguments. This is the actual handler that executes the tool logic.

  execute: (args) => houTea.catalog(args as Parameters<typeof houTea.catalog>[0]),

• src/tools/registry.ts:97-105 (schema)

  Input schema for hou_tea_browse: defines category (string), price_min/price_max (number), season (enum: spring/summer/autumn/winter), difficulty (enum: beginner/intermediate/advanced), per_page (integer 1-100, default 20), and page (integer min 1, default 1).

  inputSchema: obj({
    category: { type: "string" },
    price_min: { type: "number", minimum: 0 },
    price_max: { type: "number", minimum: 0 },
    season: { type: "string", enum: ["spring", "summer", "autumn", "winter"] },
    difficulty: { type: "string", enum: ["beginner", "intermediate", "advanced"] },
    per_page: { type: "integer", minimum: 1, maximum: 100, default: 20 },
    page: { type: "integer", minimum: 1, default: 1 },
  }),

• src/tools/registry.ts:89-118 (registration)

  Tool registration as a ToolDef in the CORE_TOOLS array. Includes name 'hou_tea_browse', group 'core', summary, description, uiComponent, inputSchema, execute function, and nextAction helper that suggests calling hou_tea_explain on the first result.

  const CORE_TOOLS: ToolDef[] = [
    {
      name: "hou_tea_browse",
      group: "core",
      summary: "Browse hou-tea catalog (filter by category / price / season / difficulty).",
      description:
        "Browse the hou-tea Chinese tea catalog. Returns products with name, price (USD/USDC), images, taste profile, fermentation level, season, and a ready-to-render `card` object.",
      uiComponent: "TeaRecommendationGrid",
      inputSchema: obj({
        category: { type: "string" },
        price_min: { type: "number", minimum: 0 },
        price_max: { type: "number", minimum: 0 },
        season: { type: "string", enum: ["spring", "summer", "autumn", "winter"] },
        difficulty: { type: "string", enum: ["beginner", "intermediate", "advanced"] },
        per_page: { type: "integer", minimum: 1, maximum: 100, default: 20 },
        page: { type: "integer", minimum: 1, default: 1 },
      }),
      execute: (args) => houTea.catalog(args as Parameters<typeof houTea.catalog>[0]),
      nextAction: (_args, data) => {
        const id = firstSkillId(data);
        if (!id) return undefined;
        return [
          {
            tool: "hou_tea_explain",
            reason: "Show a deep guide for the most relevant product.",
            args_hint: { skill_id: id },
          },
        ];
      },
    },

• src/client.ts:130-134 (helper)

  The actual catalog() method on the houTea client — makes a GET request to /api/agent/catalog with query params. This is the underlying API call invoked by the hou_tea_browse handler.

  export const houTea = {
    catalog: async (p: CatalogParams = {}) => {
      const merged = withDefaults({ store_id: DEFAULT_STORE_ID, ...p });
      return getJson<unknown>(`${DEFAULT_BASE}/api/agent/catalog${qs(merged as Record<string, unknown>)}`);
    },

• src/client.ts:73-82 (helper)

  The CatalogParams interface defining the typed parameters for the catalog API call that backs hou_tea_browse.

  export interface CatalogParams {
    store_id?: string;
    category?: string;
    price_min?: number;
    price_max?: number;
    season?: string;
    difficulty?: "beginner" | "intermediate" | "advanced";
    page?: number;
    per_page?: number;
  }