Badger Maps (Standard)

Create a new account in Badger Maps. Args: name: Account name (maps to last_name in the API — use the full business or contact name here). address: Street address including city, state, and zip (e.g. "123 Main St, Chicago, IL 60601"). phone_number: Phone number (can be empty string). email: Email address (can be empty string). first_name: Optional first name if the account is a person. notes: Optional free-text notes about the account. lat: Latitude — supply with lng to skip geocoding. lng: Longitude — supply with lat to skip geocoding. custom_fields: Optional dict of custom field values keyed by their human-readable labels (e.g. {"Sales Stage": "Lead", "Priority": "High"}). Labels must match the user's configured field names exactly. account_owner_id: Badger user ID to assign this account to. Leave unset in almost all cases — the tool fetches the authenticated user's ID automatically. Only pass this when a manager is explicitly creating an account on behalf of a rep (use find_user() to get the rep's user ID). Do NOT pass an account ID, location ID, or any other ID here — it must be a Badger user ID. Returns: Created account dict with custom fields resolved to human-readable labels — same shape as get_account().

Log a new check-in (field visit) for an account. Two mutually exclusive modes — check get_user_profile() → checkin_form_fields (apptlog_fields) to know which applies: Standard mode (checkin_form_fields is empty or absent): Pass visit_type (required) and optionally comments. custom_fields is ignored. Custom field mode (checkin_form_fields is non-empty): visit_type and comments are NOT used — they are replaced entirely by custom fields. Pass custom_fields only. If checkin_form_fields[0].is_conditional_checkin is true, only include fields that are "active": root fields (isroot: true) plus any child fields referenced by the selected option's "childs" list, applied recursively. Args: account_id: The Badger account ID to log the check-in against. visit_type: Visit type (e.g. "Drop-in", "Meeting"). Standard mode only. comments: Visit notes. Standard mode only. custom_fields: Dict of custom field values keyed by field label. Custom field mode only. Required fields must be included. Example: {"Status": "In Progress", "Priority": "High"} Returns: Created check-in object.

Create a new route in Badger Maps. Waypoints are resolved automatically from account data by default. A waypoint does NOT require a Badger account — you can add an account-less "quick stop" pin with just an address/coordinates. See the two shapes below. Args: name: Route name (e.g. "Monday Chicago Route"). route_date: Date of the route in YYYY-MM-DD format. waypoints: Ordered list of stops. Each stop is one of two shapes: Account-linked stop: - account_id (required): Badger account ID — maps to customer_id. - location_id (optional): Account location ID. If omitted, fetched automatically from the account. - name, address, city, state, zipcode, lat, lng (optional): Auto-fetched from the account if omitted. Quick stop (no linked account — a plain pin on the map): - account_id: omit entirely. - address (required): Free-form address string. - lat, lng (required): Coordinates. Not auto-geocoded — you must supply them (e.g. from a prior search/geocode). - name (optional): Display name for the stop. - city, state, zipcode, suite (optional): Address fields. Common to both shapes: - layover_minutes (optional): Planned time at this stop. Default 30. - appt_time (optional): Scheduled appointment time string. - suite (optional): Suite or unit number. start_time: Route start time (e.g. "09:00 AM"). Default "09:00 AM". start_address: Optional starting address before the first stop. (Not currently applied to the route.) destination_address: Optional ending address after the last stop. (Not currently applied to the route.) optimize: If True, optimize the stop order via Badger's routing engine before saving. The route is saved with the optimized order. created_by_id: Badger User ID to assign this route to. Leave unset in almost all cases — defaults to the authenticated user. Managers use this to create a route on behalf of a subordinate rep. To get the rep's User ID by name, call get_user_profile() and look up the rep in the "rn" field's values list. Returns: Created route object — normally the same fully-populated shape as get_route() (id, name, statistics, drawing_information, and waypoints with their real waypoint IDs). The create/save API calls themselves don't return this richer shape, so this re-fetches via sidekick afterward — expect a couple extra seconds of latency. The re-fetch is best-effort: if it fails, the route was still created and the raw create/save response is returned instead (do NOT retry the create).

Permanently delete an account from Badger Maps. WARNING: This action is irreversible. The account, its locations, and all associated check-in history will be deleted. Always confirm with the user before calling this tool. Args: account_id: The Badger account ID to delete. Returns: Confirmation string.

Search for a Badger user by email address or Badger user ID. WARNING: This tool CANNOT search by name — it only accepts an exact email address or numeric user ID. If you have a rep's name but not their email or ID, do NOT call this tool. Instead call get_user_profile() and look up the rep in the 'rn' entry of custom_fields, which contains {value: <user_id>, text: <rep_name>} for every subordinate. Args: query: Exact email address or numeric Badger user ID. Returns: User object with id, username, first_name, email.

Retrieve full details for a single account, with custom field labels resolved. Args: account_id: The Badger account ID. Returns: Account dict with standard fields (name, email, phone, address, notes, crm_id) plus all populated custom fields using their human-readable labels (e.g. "Sales Stage", "Priority", "Days Since Last Visit").

Generate a pre-visit brief for an account. Fetches full account details and recent check-in history in parallel, then formats them into a concise brief suitable for reading before a field visit. Args: account_id: The Badger account ID. Returns: Formatted plain-text brief with account info, custom field values, and up to the 5 most recent check-ins.

Retrieve full account details by external (CRM) ID. Use this when you have a CRM record ID (e.g. Salesforce or HubSpot ID) and need to look up the corresponding Badger account. Args: external_id: The external / CRM ID stored on the account (customer_id field). Returns: Account dict with standard fields plus all populated custom fields using their human-readable labels — same shape as get_account().

Find accounts within a geographic area, with optional filters on recency and custom fields. The AI client should generate a rectangular bounding box around the area of interest as a list of 4–5 lat/lng vertices (close the polygon by repeating the first point). Args: vertices: Polygon boundary as a list of {"lat": float, "lng": float} dicts. Use a simple rectangle: SW corner → NW → NE → SE → SW again. Example for a box around Chicago: [{"lat":41.7,"lng":-87.9},{"lat":42.1,"lng":-87.9}, {"lat":42.1,"lng":-87.5},{"lat":41.7,"lng":-87.5}, {"lat":41.7,"lng":-87.9}] min_days_since_checkin: Only include accounts last visited at least this many days ago (e.g. 30 = "haven't visited in 30+ days"). max_days_since_checkin: Only include accounts last visited within this many days. min_days_until_followup: Only include accounts whose follow-up is at least this many days away. Use a negative number to mean "already overdue by N days". max_days_until_followup: Only include accounts whose follow-up is within this many days (or already overdue). Use 0 for "due today or overdue". custom_text_filters: Filter by custom text field values, keyed by the field's human-readable label. Values can be a single string or a list of strings (matched with OR logic). Example: {"Sales Stage": ["Cold", "Warm"], "Specialty": "Cardiology"} custom_numeric_min: Minimum values for custom numeric fields, keyed by label. Example: {"Revenue": 10000} custom_numeric_max: Maximum values for custom numeric fields, keyed by label. Example: {"Revenue": 50000} rep_user_id: Scope results to a specific rep's accounts (manager use only). fields: Optional list of field names to include in each result. Standard field names (e.g. "id", "full_name", "follow_up_date", "days_since_last_checkin", "lat", "lng", "location_id") plus any custom field labels for this user (e.g. "Priority", "Sales Stage"). "id" is always included regardless. Omit to return all fields (default behaviour). max_results: Maximum number of accounts to return. Omit to return all matches. Returns: Flat list of account objects within the area matching all filters, truncated to max_results if specified. Each object contains the data needed for prioritization and route-building — do NOT follow up with get_account or get_account_brief calls just to get address or custom field values; they are already present in these results. Fields returned (when fields is None): - id: Badger account ID - full_name: account display name - original_address: street address string (if set) - location_id: Badger location ID - lat, lng: coordinates - last_checkin_date: date of last check-in (YYYY-MM-DD, may be null) - days_since_last_checkin: integer days since last visit (may be null) - follow_up_date: scheduled follow-up date (YYYY-MM-DD, may be null) - last_modified_date: date account was last modified (YYYY-MM-DD) - account_owner_id: Badger User ID of the account owner (integer, always present) - account_owner_name: full name of the account owner (string, always present but may be blank) - any non-null custom fields, keyed by their human-readable label (e.g. "Sales YTD", "Sales Stage") — no further fetching needed

Check how many of a route's linked accounts aren't already owned by a prospective new owner — call this before reassign_route() to warn the user about the accounts side effect described there. Args: route_id: The Badger route ID. new_owner_id: Badger User ID of the prospective new route owner. rep_user_id: Optional Badger User ID of the route's current owner. Defaults to the authenticated user. Returns: The number of linked accounts not already owned by new_owner_id.