Overview

Getting Started

MARKETPLACE

Widgets

MCP Server

Find Pros

Search Pros Tools

Tools and the pro list widget for finding and comparing pros.

The server exposes four tools in the Search Pros toolset. All four are annotated as read-only, non-destructive, and idempotent, meaning AI agents can call them safely without requiring explicit user confirmation.

Recommended Workflow

The server publishes instructions in its initialize response that guide AI agents on how to use the tools of the partner's toolset. The recommended workflow is:

Agents should retain the ZIP code, category, searchID, requestFormID, the request form questions, and the collected answers across the conversation.

Search Home Service Pros

Tool name: search_home_service_pros

A unified tool that discovers service categories, fetches the request form, and searches for professionals — all in a single call. This is the primary entry point for the Thumbtack search workflow.

Input Schema

Parameter	Type	Required	Description
userQuery	string	Yes	Complete description of the home service needed (e.g., "house cleaning", "plumber for kitchen sink repair")
zipCode	string	Yes	US ZIP code to center the search (5 digits)

Output Schema

Field	Type	Description
searchID	string	Thumbtack search project ID, used in follow-up filter_home_service_pros calls
categoryID	string	ID of the best-matching Thumbtack category
categoryName	string	Human-readable name of the matched category
data	array of BusinessResult	List of matching professionals (up to 6). The MCP Apps widget shows the first 3.
metadata	SearchMetadata	Search context including location and category info
requestForm	RequestFormData (nullable)	Request form ID and its questions, for refinement. Null if fewer than 2 pros were found.
relevantCategories	array of Category	Other Thumbtack categories relevant to the user's query, each with categoryID and name

Main BusinessResult fields:

Field	Type	Description
businessID	string	Business ID, used with get_reviews_for_pros
businessName	string	Name of the business
businessIntroduction	string	The business's introduction
priceInfo	string	Human-readable price summary, e.g. "$125/service call (waived if hired)"
quote	object (optional)	startingCost, maximumCost and waivedAmount in cents, and costUnit
rating	number	Average rating on a 1–5 scale
numberOfReviews	integer	Total published reviews
yearsInBusiness	integer	How long the business has operated, in years
numberOfHires	integer	Total hires completed on Thumbtack
isTopPro	boolean (optional)	Whether the pro is recognized as a Top Pro
isBackgroundChecked	boolean (optional)	Whether the business has passed a background check
isBusinessLicenseVerified	boolean (optional)	Whether the business license has been verified
licenses	array (optional)	License number, state, type and authority URL
pills	array of string (optional)	Labels such as "In high demand", "Licensed pro", "Great value", "Limited availability"
featuredReview	string (optional)	A featured review of the business
featuredReviewerName	string (optional)	Name of the featured review's author
responseTimeHours	number (optional)	Average time to first response
servicePageURL	string	The pro's Thumbtack page. Keep its query parameters when displaying it.
businessImageURL	string	The business avatar

SearchMetadata contains categoryID, categoryName, zipCode, requestLocation (e.g. "San Francisco, CA"), and seeMoreProsURL. When no pros are found, seeMoreProsURL is replaced by searchThumbtackURL, a link to start a new search on Thumbtack.

Each request form question contains questionID, prompt, subprompt, questionType (e.g. radioOption, checkboxOption, singleLineText, multipleLineText, datePicker), answerOptions (each with text and answerID), validationConstraints, and isClarifyingQuestion.

Behavior

Translates the user query into matching Thumbtack categories via category search.
In parallel, fetches the request form and searches for businesses in the best-matching category.
Returns professionals, the request form (for refinement), and alternative categories.
If no category matches, returns the text message "We couldn't find a matching service category. Please try a different search."
If no professionals are found, returns an empty data array with a text hint to offer the relevant categories.

The pro list widget shows the first 3 professionals, and the assistant should summarize only those 3.

Filter Home Service Pros

Tool name: filter_home_service_pros

A follow-up tool for refining search results using answers to the request form's clarifying questions. Must be called after search_home_service_pros.

Input Schema

Parameter	Type	Required	Description
zipCode	string	Yes	Same US ZIP code used in the initial search (5 digits)
categoryID	string	Yes	Category ID from search_home_service_pros
searchID	string	Yes	Search project ID from search_home_service_pros
requestForm	RequestForm	Yes	Contains requestFormID and requestFormAnswers with user responses

Each entry in requestFormAnswers includes:

Field	Type	Description
questionID	string	Question ID from the request form
answerIDs	array of string	Selected answer IDs, for choice-based questions. Submit the answerID, not the display text.
freeFormAnswer	array of string	Text answer, for singleLineText and multipleLineText questions
dateAnswers	array of string	Dates in YYYY-MM-DD format, for datePicker questions
shouldRemoveQuestion	boolean	Clears a previously submitted answer to this question

Each answer must set exactly one of answerIDs, freeFormAnswer or dateAnswers, or set shouldRemoveQuestion on its own. An answer that sets more than one is rejected with a validation error.

Output Schema

Field	Type	Description
searchID	string	Updated search project ID
data	array of BusinessResult	Filtered list of matching professionals (up to 6)
metadata	SearchMetadata	Updated search context

Behavior

Updates the existing search project with the user's request form answers. Filtered results replace the previous professional list.
If requestFormAnswers is empty, returns the current results of the existing search unchanged.
If the original search project has expired (search projects are deleted after 7 days), the tool automatically creates a new search with the same parameters as a fallback. Answers marked shouldRemoveQuestion are left out of the new search.
If no professionals match, returns an empty data array and the text message "We couldn't find any professionals matching your criteria."

Get Category Recommendations

Tool name: get_category_recommendations

Returns home service category recommendations for a given ZIP code, sorted by popularity or trending status.

Input Schema

Parameter	Type	Required	Description
zipCode	string	Yes	US ZIP code (5 digits)
recommendationType	enum	Yes	Either popular or trending
limit	integer	No	Maximum categories to return (default 10, max 20; larger values are capped at 20)

Output Schema

Field	Type	Description
data	array of CategoryRecommendation	Recommended categories
zipCode	string	The ZIP code used for the recommendation

Each CategoryRecommendation includes:

Field	Type	Description
categoryID	string	Thumbtack category ID
name	string	Human-readable category name
nearMeURL	string (nullable)	URL to the "near me" page for this category. Assistants can show categories as links to it.
imageURL	string (nullable)	URL to an image representing the category

Get Reviews For Pros

Tool name: get_reviews_for_pros

Retrieves customer reviews for one or more professionals. Supports sorting by relevance, rating, or date.

Input Schema

Parameter	Type	Required	Description
businessIDs	array of string	Yes	Business IDs to get reviews for (from previous search results)
sortBy	enum	Yes	One of: most_relevant, highest_rated, lowest_rated, newest_first, oldest_first
categoryID	string	Conditional	With most_relevant, provide either categoryID or searchQuery
searchQuery	string	Conditional	With most_relevant, provide either categoryID or searchQuery
limit	integer	No	Reviews per professional (default 10, max 20; larger values are capped at 20)

Output Schema

Field	Type	Description
data	map (string to array of ReviewResult)	Map of business IDs to their reviews
notFound	array of string (optional)	Requested business IDs that were not found

Each ReviewResult includes:

Field	Type	Description
reviewText	string (optional)	Review content
rating	number	1–5 star rating
createTime	string	RFC 3339 timestamp
reviewerName	string (optional)	Reviewer's display name
responseText	string (optional)	Business owner's response
responseTime	string (optional)	When the business responded (RFC 3339)

The Search Pros Toolset has one resource, pro_list_widget.

URI: ui://widgets/pro_list.html

An interactive MCP Apps widget that renders a visual list of home service professionals.

Property	Value
Name	pro_list_widget
Title	Pro List Widget
MIME Type	text/html;profile=mcp-app
Description	A widget that displays a list of home service professionals

search_home_service_pros and filter_home_service_pros declare the widget in their tool metadata as _meta.ui.resourceUri: "ui://widgets/pro_list.html". Hosts that support MCP Apps render the tool's structured result in the widget. Other hosts can ignore it and render from structuredContent. The widget shows the first 3 professionals in data.

The resource contents carry _meta.ui with:

csp: The widget's Content Security Policy. connectDomains lists Thumbtack's API and GraphQL hosts, and resourceDomains lists the CDNs for images, static assets, and fonts.
prefersBorder: false.
domain: The sandbox origin for the widget, for hosts that use it.

Last Updated: Oct 21st, 2026

On this page

Search Pros Tools

Recommended Workflow

Search Home Service Pros

Filter Home Service Pros

Get Category Recommendations

Get Reviews For Pros