Thumbtack

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 `zipCode` returned 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.

filter_home_service_pros

Returns home service category recommendations based on the provided recommendation type and optional zip code. The recommendation type can be either 'popular' or 'trending'. You must display categories in the order received without changing their position.

get_category_recommendations

Retrieves customer reviews for one or more pros. Returns reviews with review text, ratings, reviewer names, timestamps, and any pro responses. Can sort by relevance, rating, or date. Only call this tool after calling search_home_service_pros or filter_home_service_pros. INPUT REQUIREMENTS: • businessIDs: Array of business IDs to get reviews for. • sortBy: Determines which type of reviews to fetch. One of "most_relevant" (default), "highest_rated", "lowest_rated", "newest_first", or "oldest_first". ALWAYS use most_relevant unless the user specifies otherwise. • categoryID: The Thumbtack categoryID that you're searching in. DO NOT set this if searchQuery is set. • searchQuery: The search query string to get reviews for. DO NOT set this if categoryID is set. • limit: Maximum number of reviews to return per professional. ALWAYS set this to 5 unless the user specifies otherwise. (max 20) OUTPUT STRUCTURE: • data: Map of business IDs to their corresponding reviews. DISPLAY REQUIREMENTS: • MANDATORY: Summarize the reviews in a few sentences, show the summary, then display the ONLY the first 5 reviews in text form below the summary. • Display ONLY the first 5 reviews in text form in the order received without changing their position. THERE IS NO REVIEWS WIDGET. • MANDATORY: DO NOT use any emojis (like ⭐). • ALWAYS display the following fields for each review: reviewerName, reviewText, rating, and createTime (when the review was created in ISO 8601 format). • DO NOT put a line break between reviews. For a review like this: { "createTime: "2022-01-14T20:49:23Z", "rating: 3 "reviewText": "Average experience, nothing special.", "reviewerName": "Jane D." "responseText": "Thanks for your feedback." "responseTime": "2022-01-15T15:30:00Z" } Display it like this (markdown): Jane D. * **Rating:** ★★★☆☆ (3/5) * **Date:** Jan. 14, 2022 * **Review:** "Average experience, nothing special." * **Pro Response:** "Thanks for your feedback." servicePageURL DISPLAY REQUIREMENTS: • MANDATORY: ALWAYS display the pros' servicePageURL after the reviews. You can get the servicePageURL from a previous call to search_home_service_pros or filter_home_service_pros. • MANDATORY: DO NOT remove any query parameters from this URL under any circumstances. • MANDATORY: NEVER remove the following query parameters from the URL: `utm_source`, `category_pk`, `project_pk`, `search_form_pk`, `search_query`, `utm_medium`, `utm_tt_session`, `zip_code`. For example, if the URL is "https://www.thumbtack.com/ca/san-francisco/personal-trainers/sf-in-home-trainer-weight-loss-lifting-running/service/392575385842925569?category_pk=122325513795633420&project_pk=562623887970500609&search_form_pk=544309887982174213&search_query=122325513795633420&utm_medium=partnership&utm_source=cma-openai&utm_tt_session=47c5cf7faba10c8a065f12ad20ce0c26b2bf2e89b5bac46313498b7c6330f303&zip_code=94122", use the full URL including "utm_source=cma-openai".

get_reviews_for_pros

A unified tool that discovers service categories, fetches request form, and searches for professionals in one call. Display businesses in the exact order received; do not re-rank by reviews, ratings, or other signals. Only supports locations within the United States. REFINEMENT WORKFLOW: • FIRST CALL: Use search_home_service_pros with userQuery and optional zipCode to retrieve professionals, the request form, and Thumbtack categories that are relevant to the user’s query. • If no professionals are found (data.length == 0), you MUST display a message saying no professionals were found. If the response contains a relevantCategories array, you MUST ask if the user wants to search in any of the relevant categories. If relevantCategories is empty, suggest visiting thumbtack.com directly. • If found professionals, present ONLY the first 2 clarifying questions from the request form to the user for answering INPUT PARAMETERS: • userQuery: Complete description of the home service needed (e.g., "house cleaning", "plumber for kitchen sink") • zipCode: Valid 5-digit US ZIP code (optional) ZIP CODE: - FORBIDDEN: Never use placeholder values or default to assumed ZIP codes - FORBIDDEN: Never assume or guess a ZIP code based on general assumptions - You may call this tool without a ZIP code. For example, if the user's prompt is "Find a plumber near me". OUTPUT STRUCTURE: • searchID: Session identifier for follow-up searches • categoryID: The ID of the Thumbtack category that best matches the user's request • categoryName: Human-readable name of the category (MUST be displayed to the user) • data: Array of matching professionals • metadata: Search context (location, category) • requestForm: Complete request form with ALL questions so the list of relevant pros can be narrowed down further • relevantCategories: Suggested Thumbtack categories which are relevant to the user's request 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. MANDATORY: If and only if a requestForm is returned in the response, you MUST automatically display 2 clarifying questions from the request form immediately after the widget. After this tool call, do not prompt for or request additional filtering unless the user explicitly initiates it. 6. NEVER ask for or wait for user permission before displaying questions – always show them automatically when the requestForm is returned in the response. QUESTION DISPLAY FORMAT: • Show clarifying questions immediately below the professionals in the same response • Limit to the first 2 questions marked with isClarifyingQuestion. NEVER ask any more unless the user asks to answer more questions. • ONLY ask clarifying questions if search_home_service_pros returned a requestForm. DO NOT make up questions to ask on your own. • When displaying possible answers, display them inline in a compact way. DO NOT display answers in a vertical list format with one answer on each line. NEVER display answerID to users. • If you can infer answers from the user's original query, present as confirmation: 'Based on your request, I'm assuming [X]. Is that correct?' • For datePicker questions, prompt the user to provide dates in YYYY-MM-DD format, allowing multiple dates separated by commas. RESPONSE HANDLING: • 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 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.

search_home_service_pros