get_business_reviews

Instructions

Implementation Reference

• server/tools/reviews.py:66-93 (handler)

  The async function get_business_reviews that implements the tool logic: accepts ReviewsParams, builds query params, calls YelpClient.get('businesses/{id}/reviews', ...), and returns BusinessReviewsResult.

  async def get_business_reviews(params: ReviewsParams) -> BusinessReviewsResult:
      """Retrieve user reviews for a specific Yelp business.
  
      Use this when the user wants to read what customers say about a
      business: sentiment, specific comments about food, service, or
      atmosphere.  Returns up to 50 reviews per call with text excerpts,
      star ratings, and reviewer info.
  
      The 'total' field in the response shows how many reviews exist in full;
      use 'offset' to paginate through them.
  
      Raises an error if the business ID does not exist on Yelp.
      """
      query: dict[str, object] = {
          "limit": params.limit,
          "offset": params.offset,
      }
      if params.locale:
          query["locale"] = params.locale
      if params.sort_by:
          query["sort_by"] = params.sort_by
  
      logger.info("get_business_reviews", business_id=params.business_id)
      raw = await client.get(
          f"businesses/{params.business_id}/reviews",
          params=query,
      )
      return BusinessReviewsResult.model_validate(raw)

• server/tools/reviews.py:19-54 (schema)

  ReviewsParams model - input schema for the tool with fields: business_id (required), locale, sort_by, limit (1-50), offset (>=0).

  class ReviewsParams(BaseModel):
      business_id: str = Field(
          ...,
          description=(
              "Yelp business ID or alias. "
              "Obtain from search_businesses, find_business_by_phone, or match_business."
          ),
      )
      locale: str | None = Field(
          default=None,
          description=(
              "BCP 47 locale to filter reviews by language, e.g. 'en_US', 'es_MX'. "
              "Defaults to all languages."
          ),
      )
      sort_by: str | None = Field(
          default=None,
          description=(
              "Sort order for reviews: 'yelp_sort' (default), 'newest', 'oldest', "
              "'highest_rated', or 'lowest_rated'."
          ),
      )
      limit: int = Field(
          default=20,
          ge=1,
          le=50,
          description="Number of reviews to return (1–50, default 20).",
      )
      offset: int = Field(
          default=0,
          ge=0,
          description=(
              "Zero-based offset for pagination. "
              "Use with limit to page through all reviews."
          ),
      )

• server/core/models.py:127-132 (schema)

  BusinessReviewsResult model - output schema returned by get_business_reviews, containing reviews list, total count, and possible_languages.

  class BusinessReviewsResult(_YelpBase):
      """Wrapper returned by get_business_reviews."""
  
      reviews: list[Review] = Field(default_factory=list)
      total: int = 0
      possible_languages: list[str] = Field(default_factory=list)

• server/core/models.py:109-124 (schema)

  Supporting ReviewUser and Review models used within BusinessReviewsResult to represent individual review entries.

  class ReviewUser(BaseModel):
      model_config = ConfigDict(extra="ignore")
  
      id: str | None = None
      profile_url: str | None = None
      image_url: str | None = None
      name: str | None = None
  
  
  class Review(_YelpBase):
      id: str
      url: str | None = None
      text: str | None = None
      rating: int | None = None
      time_created: str | None = None
      user: ReviewUser | None = None

• server/tools/reviews.py:57-65 (registration)

  The register() function that decorates get_business_reviews with @mcp.tool(...) to register it on the FastMCP instance, with readOnlyHint and idempotentHint annotations.

  def register(mcp: FastMCP, client: YelpClient) -> None:
      """Register the get_business_reviews tool on the FastMCP instance."""
  
      @mcp.tool(
          annotations={
              "readOnlyHint": True,
              "idempotentHint": True,
          }
      )