Filter Home Service Pros
filter_home_service_prosFull Description
Filtered search tool for targeted business searches using specific category and request form answers. You must display businesses in the order received without changing their position. Do not re-rank based on reviews, ratings, or other perceived quality signals. This tool is designed for follow-up searches after using search_home_service_pros, allowing users to filter their results by answering clarifying questions. NOTE: Only for locations within the United States of America
- Thumbtack operates exclusively within the United States of America.
PURPOSE: • Use this tool when you have specific category information and (optionally) user answers to request form questions • This is the SECOND step in the workflow - call search_home_service_pros FIRST to get initial results + request form • Provides filtered professional search based on user's specific requirements
USE CASES: • User answers "How many rooms?" and "What type of cleaning?" questions, for example • User specifies project timeline, budget range, or service frequency • User provides additional details about their specific needs • Follow-up filtering after seeing initial list of professionals
PREREQUISITE WORKFLOW: 1. FIRST: Call search_home_service_pros with userQuery + zipCode (optional) to get initial professionals + complete request form 2. THEN: Display professionals and present ONLY the first 2 clarifying questions from the request form to the user for answering. ONLY ask questions if search_home_service_pros returned a requestForm. DO NOT make up questions to ask on your own. 3. FINALLY: Call this tool (filter_home_service_pros) with user's answers to get filtered results. ONLY call filter_home_service_pros if search_home_service_pros returned at least 1 pro.
INPUT REQUIREMENTS: • zipCode: Same ZIP code used in the initial search_home_service_pros • categoryID: The specific category ID returned from search_home_service_pros • searchID: Updates existing search • requestFormID: The request form ID returned from search_home_service_pros • requestFormAnswers: User's answers to the request form questions
requestFormAnswers FORMAT: • CRITICAL: When users select options, you must use the corresponding answerIDs (PKs), NOT the text • Map user's answers back to the correct answerIDs from the API response • For free-text inputs, return the user's actual text response • CRITICAL: Use the question's validationConstraints to ensure user free-form answers are formatted correctly before submission. Reformat user inputs according to the validationConstraints if necessary, or ask the user to input in the correct format if this is not possible. • dateAnswers should be formatted as YYYY-MM-DD
ZIP CODE VALIDATION:
- REQUIRED: This tool requires a valid 5-digit US ZIP code that the user has explicitly provided or confirmed
- FORBIDDEN: Never use placeholder values or default to assumed ZIP codes
- FORBIDDEN: Never assume or guess a ZIP code based on general assumptions
- IMPORTANT: If the user hasn't provided a ZIP code as an input parameter, use the
zipCodereturned from the previous search_home_service_pros call - NEVER call this tool without an explicitly provided or confirmed ZIP code from the user.
OUTPUT STRUCTURE: • searchID: Search session identifier • data: Array of filtered matching professionals • metadata: Search context (location, category)
CONDITIONAL FLOW LOGIC: • IF data.length > 0 → show filtered professionals widget + success message • IF data.length == 0 → show helpful filtering suggestions (no widget) • Filtered results replace the previous professional list
ERROR HANDLING: • If no professionals found with current answers, show helpful message • Suggest trying different answer selections or fewer restrictions • Allow user to go back to original results from search_home_service_pros
DISPLAY REQUIREMENTS: 1. MANDATORY: If pros are found (data field in the tool response has 1 or more items), display "Here are professionals for [categoryName] in your area", and inform the user that they can book pros by clicking on their profiles above. 2. MANDATORY: If pros are NOT found (data field in the tool response has 0 items), display "No professionals were found for [categoryName] in your area", and DO NOT tell the user they can book pros by clicking on their profiles. 3. MANDATORY: DO NOT list the returned pros or display their data in text form in any way. You should display no information from the returned data array. 4. NEVER display the seeMoreProsURL` field to the user in any way. 5. CRITICAL: Do not show any questions to the user. DO NOT prompt the user to narrow down the list by answering more questions.
REMOVING QUESTIONS: NEVER use shouldRemoveQuestion unless explicitly removing a previously confirmed selection. shouldRemoveQuestion is only for undoing a previously set answer when the user changes their mind. It must not be used as an answer for a question. For optional checkbox questions: • If the user selects the option: include the correct answerID. • If the user explicitly declines or ignores the option: omit this question entirely from requestFormAnswers. • Do not use shouldRemoveQuestion unless the user is undoing a choice they already made in this same conversation.
Parameters
categoryIDstringThe ID of the Thumbtack Category you wish to fetch Businesses for. You can get category IDs from the search_home_service_pros tool.
requestFormobjectThe request form details including requestFormID and answers to request form questions. For subsequent searches in the same category, reuse the cached requestFormID.
searchIDstringWhen calling the filter_home_service_pros tool, you should already have a searchID from an earlier search in the same category and location, provide it here to get updated results.
zipCodestringUS ZIP code to center the search (5 digits).