match_business

Instructions

Implementation Reference

• server/handlers/tools.py:201-210 (handler)

  The actual implementation of the match_business tool handler. It validates arguments via MatchParams, calls the Yelp API 'businesses/matches' endpoint, and returns a JSON response of matched businesses using BusinessDetail model.

  async def _match_business(
      arguments: dict[str, Any],
      client: YelpClient,
  ) -> ToolContent:
      params = MatchParams.model_validate(arguments)
      query: dict[str, object] = params.model_dump(exclude_none=True)
      raw = await client.get("businesses/matches", params=query)
      businesses: list[object] = raw.get("businesses", [])  # type: ignore[assignment]
      results = [BusinessDetail.model_validate(b).model_dump(exclude_none=True) for b in businesses]
      return _json({"businesses": results, "total": len(results)})

• server/handlers/params.py:102-125 (schema)

  The MatchParams Pydantic model defining input validation schema for match_business. Required fields: name, address1, city, state, country. Optional: zip_code, phone, match_threshold (default: DEFAULT).

  class MatchParams(BaseModel):
      name: str = Field(..., description="Business name, e.g. 'Tartine Bakery'.")
      address1: str = Field(..., description="Street address, e.g. '600 Guerrero St'.")
      city: str = Field(..., description="City name, e.g. 'San Francisco'.")
      state: str = Field(
          ...,
          description="ISO 3166-2 state/region code, e.g. 'CA'.",
      )
      country: str = Field(
          ...,
          description="ISO 3166-1 alpha-2 country code, e.g. 'US'.",
      )
      zip_code: str | None = Field(
          default=None,
          description="Postal code. Improves match accuracy.",
      )
      phone: str | None = Field(
          default=None,
          description="E.164 phone number. Improves match accuracy.",
      )
      match_threshold: str = Field(
          default="DEFAULT",
          description="Match strictness: 'NONE', 'DEFAULT', or 'STRICT'.",
      )

• server/handlers/tools.py:96-107 (registration)

  Registration of the 'match_business' tool in the TOOLS catalogue. Sets description, associates MatchParams schema, and marks it as idempotent.

  _tool(
      "match_business",
      (
          "Match a business by name and address to its canonical Yelp listing. "
          "Use when you have structured address data and need to verify or enrich "
          "it with Yelp data such as ID, rating, hours, and URL. "
          "name + address1 + city + state + country are required. "
          "Adding zip_code and phone significantly improves match precision."
      ),
      MatchParams,
      idempotent=True,
  ),

• server/core/models.py:76-94 (schema)

  BusinessDetail output model used by match_business (and get_business) to deserialize the Yelp API response into structured data.

  class BusinessDetail(_YelpBase):
      """Full business record returned by get_business and match_business."""
  
      id: str
      name: str
      url: str | None = None
      phone: str | None = None
      display_phone: str | None = None
      rating: float | None = None
      review_count: int | None = None
      price: str | None = None
      is_closed: bool = False
      location: Location | None = None
      categories: list[Category] = Field(default_factory=list)
      coordinates: Coordinates | None = None
      image_url: str | None = None
      photos: list[str] = Field(default_factory=list)
      hours: list[Hours] = Field(default_factory=list)
      alias: str | None = None

• server/handlers/tools.py:249-250 (helper)

  Helper _json function used by _match_business to serialize the response as JSON text content.

  def _json(data: object) -> ToolContent:
      return [types.TextContent(type="text", text=json.dumps(data, indent=2))]