Provider Search

Overview

The provider_search tool browses and discovers healthcare providers, practices, insurance entities, labs, and pharmacies in the b.well provider directory. Call it for informational lookups when the user wants to find or learn about providers — for example, "find a cardiologist near me" or "show me pharmacies in my area." It is read-only and does not establish a data connection to any provider or data source. It accepts latitude/longitude coordinates such as those produced by the convert_zipcode_to_coordinates tool, or a raw ZIP code via the zipcode parameter.

Optional Parameters

All parameters accepted by provider_search have default values — there are no required parameters.

search_text (string, optional)

• Default: null
• Specific provider type, specialty, facility, or name to search for. Omit for general "find providers near me" queries.
• Use when the user specifies a specialty (e.g. "cardiologist", "pediatrician", "dermatologist"), a facility (e.g. "CVS Pharmacy", "Mayo Clinic", "Quest Diagnostics"), or a provider name (e.g. "Dr. Smith", "Jane Doe MD").
• Omit when the user asks something like "find doctors near me," "healthcare providers in my area," or "show me all providers."

lat (number, optional)

• Default: 43.0744554
• Latitude for geographic filtering. If provided, results will be prioritized by proximity.

lon (number, optional)

• Default: -89.3892675
• Longitude for geographic filtering. Used with lat to sort results by distance.

distance (integer, optional)

• Default: 50
• Distance in miles for geographic filtering. If provided, results are limited to this distance from the lat/lon position.

include_populated_proa_only (boolean, optional)

• Default: false
• If true, only include providers with PROA (Point of Access) connections.

include_inactive (boolean, optional)

• Default: false
• If true, include inactive providers in the results.

page_size (integer, optional)

• Default: 10
• Number of results to return per page.

page_number (integer, optional)

• Default: 0
• Page number of results to retrieve (0-based).

insurance_name (string, optional)

• Default: null
• Name of the insurance provider to filter results by.

address (string, optional)

• Default: null
• Address string to filter results by location.

gender (enum: male | female, optional)

• Default: null
• Gender to filter results by. (Note: the source code's parameter description literally reads "Gender of the insurance provider to filter results by" — this appears to be a copy/paste artifact from the neighboring insurance_name description, since the parameter actually filters on the provider's gender, not an insurance entity's.)

accepting_new (boolean, optional)

• Default: null
• Whether the provider is accepting new patients.

age_range_minimum (number, optional)

• Default: null
• Minimum age range for filtering providers.

age_range_maximum (number, optional)

• Default: null
• Maximum age range for filtering providers.

zipcode (string or integer, optional)

• Default: null
• Back-up to the convert_zipcode_to_coordinates tool. Extracts a ZIP code for geographic filtering. If lat/lon are left at their defaults (or are otherwise unset or zero), supplying zipcode causes the tool to geocode it to coordinates automatically before searching.

debug (boolean, optional)

• Default: false
• Documented as controlling display of debugging information. As currently wired, this value is accepted but not forwarded anywhere — see Notes.

Returns

A dictionary (Dict[str, Any]) containing the provider search response, with a search_providers object holding a results list. Each result entry can include:

• id, npi — identifiers for the provider or facility, including a list of NPI numbers.
• name — list of name entries (family, given, prefix, suffix, text).
• type_ — result type (PRACTICE or PRACTITIONER).
• specialty — list of specialty codings (code, display, system).
• location — list of locations, each with address (city, line, postal_code, state), description, distance_in_miles, identifier, position (lat, lon), scheduling (bookable, service_type), and telecom.
• insurance_plan — list of insurance plans, each with owned_by (payer display name) and plan (identifier, network).
• organization_affiliation — affiliated organization reference.
• practitioner_qualification — list of qualifications (code, issuer).
• bookable, next_available_slot — online/phone bookability and next available appointment slot info.
• facility_id, group, client_preferred, content, photo — supporting facility, grouping, and content metadata.

There is no pagingInfo or top-level data field in the response (see Notes).

If the underlying provider search service returns partial data alongside resolver errors, provider_search returns the partial results rather than failing. If the request fails outright (configuration, GraphQL, or HTTP error), the tool raises an error describing the failure.