Otto by PassBy

Compare 2-5 entities side-by-side across visits, demographics, or footprint. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: entities: Comma-separated entity names (e.g. 'Starbucks, Dunkin, Peet's') entity_type: 'brand' (only supported type currently) metric: 'visits', 'demographics', or 'location_count' start_date: Start date (YYYY-MM-DD or natural language) end_date: End date (YYYY-MM-DD or natural language) granularity: Visits granularity: 'daily', 'weekly', 'monthly', 'total' demographic_segment: Segment for demographics: 'age', 'income', 'education', etc. location: Free-text place to limit to, resolved inline (e.g. 'California', 'Times Square', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution (e.g. 'retail_area:abc,retail_area:def', 'cbsa:41860'); echoed as resolved_geometry co_located: If True, only compare in retail areas where ALL entities have locations Returns: Side-by-side comparison for the selected metric, plus resolved_geometry. Examples: Visits: entities="Starbucks, Dunkin", metric="visits" Demographics: entities="Starbucks, Dunkin", metric="demographics", demographic_segment="income" Footprint: entities="Starbucks, Dunkin", metric="location_count" Shared areas only: entities="Starbucks, Dunkin", co_located=True In a state: entities="Starbucks, Dunkin", location="California"

compare

Find locations matching criteria, as individual locations or aggregated counts. Provide at least one of: brand, category, location, in_geometry. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: brand: Brand name to filter by (e.g. 'Starbucks') category: Category filter (e.g. 'Coffee Shop', 'Clothing') location: Free-text place to search within, resolved inline (e.g. 'California', 'Times Square', '1 km from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution — 'retail_area:<id>' for one mall, 'city:6000324' for a city, or a comma-separated union; echoed as resolved_geometry include_closed: If True, include closed locations (default False) limit: Max results per page (default 20, max 100) page: Page number for paginated results (default 1) page_size: Results per page; when set, overrides limit aggregate: None=list locations, 'brand'/'category'/'state'=count by that field Returns: Matching locations or aggregated counts, plus resolved_geometry. An ambiguous `location` returns candidates instead. Examples: Brand in an area: brand="Starbucks", location="Times Square, NYC" Category in a state: category="Clothing", location="California" Brands in a mall/area: in_geometry="retail_area:...", aggregate="brand" Near a point: category="Coffee Shop", location="1 km from 123 Main St" Count per state: category="Gym", aggregate="state"

find_locations

Get the visitor demographic breakdown (e.g. income brackets, age groups) for a brand, location, retail area, or category. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: target: Brand name (e.g. 'Starbucks'), location UUID, or retail area UUID target_type: 'brand', 'location', or 'retail_area' category: Category filter (e.g. 'Coffee Shop', 'Gym') dataset: Segment type: 'age', 'income', 'education', 'tenure', 'industry' location: Free-text place to scope to, resolved inline (e.g. 'California', 'Times Square', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution (e.g. 'retail_area:abc', 'cbsa:41860'); echoed as resolved_geometry start_date: Start date (YYYY-MM-DD or natural language) end_date: End date (YYYY-MM-DD or natural language) comparison_type: 'total' for percentages, 'state'/'nation' for difference vs reference group_by: 'state', 'city', 'location', or 'brand' Returns: Demographic segments with percentages and resolved_geometry. An ambiguous `location` returns candidates instead. Examples: Brand: target="Starbucks", dataset="income" Location: target="abc-123", target_type="location", dataset="age" Category in an area: category="Gym", location="California", dataset="income" By state: target="Target", dataset="income", group_by="state"

get_demographics

Get detailed information about a brand, location, or retail area. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: target: Brand name (e.g. 'Starbucks'), location UUID, or retail area UUID target_type: 'brand', 'location', or 'retail_area' include_closed: If True, include closed locations in counts (default False) Returns: Entity metadata — location counts, categories, address, etc.

get_info

Get foot traffic visit data for brands, locations, or retail areas. TARGET: what to measure — a brand name, comma-separated brand names for multi-brand queries, a location/retail_area UUID (with target_type), and/or a category filter. WHERE (optional): scope by place with `location` (free-text: city, metro, state, neighborhood, mall, address, or '1 km from Times Square' — resolved inline) OR `in_geometry` (canonical geometry id(s) from a prior call). The resolved area is echoed as `resolved_geometry`; reuse its ids as `in_geometry` to skip re-resolving. An ambiguous `location` returns candidates instead of running the query. GROUP_BY (optional): omit for a time series; set to 'state', 'city', 'brand', 'location', 'category', or 'retail_area' for totals per group. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: target: Brand name (e.g. 'Starbucks'), comma-separated brand names, location UUID, or retail area UUID target_type: 'brand', 'location', or 'retail_area' category: Category filter (e.g. 'Coffee Shop', 'Clothing') location: Free-text place to scope to, resolved inline (e.g. 'California', 'Times Square', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution — 'retail_area:<id>' for one mall, or a comma-separated union (e.g. a district 'retail_area:abc,retail_area:def', a metro 'cbsa:41860') co_brand: Only include locations in retail areas where this brand also exists start_date: Start date (YYYY-MM-DD or natural language) end_date: End date (YYYY-MM-DD or natural language) granularity: 'daily', 'weekly', 'monthly', or 'total' comparison_type: 'total' for raw visits, 'yoy' for year-over-year group_by: 'brand', 'state', 'city', 'category', 'location', or 'retail_area' sort_by: 'visits', 'name', or 'date' sort_order: 'desc' or 'asc' limit: Max results (default 50, max 500) page: Page number for pagination (default 1) page_size: Results per page; when set, enables pagination and overrides limit format: 'csv' (default), 'summary', or 'markdown' demographics: Optional demographic segment to include (e.g. 'income', 'age') Returns: Visit data (time series or grouped) plus resolved_geometry. Examples: Brand monthly: target="Starbucks", granularity="monthly" Per-state: target="Starbucks", group_by="state" In an area: category="Coffee Shop", location="1 km from Times Square, NYC" Multi-brand: target="Starbucks, Dunkin", group_by="brand" Reuse a resolved area: in_geometry="retail_area:abc,retail_area:def"

get_visits

Resolve a free-text place (city, metro/region, neighborhood, colloquial area like 'the Bay Area', landmark, address, ZIP, or mall) to canonical geometry id(s) with its true boundary, name, centroid, and stats. Usually you do NOT need this first — find_locations, search_entities, get_visits, and get_demographics all accept a free-text `location=` and resolve it inline. Use resolve_location to disambiguate a place interactively before querying, or to get a reusable `geometry_id` to pass as `in_geometry=` across several follow-up calls. Ambiguous queries trigger an MCP elicitation pick-list resolved in-band, so a single call returns a resolved geography. Clients without elicitation support get status='ambiguous' with candidates instead. Handling the response: - status='resolved': use `geometry_ids` downstream (comma-join for composites). - status='ambiguous': present `clarifying_question` and `candidates`, then call again with the chosen candidate's `geometry_id` (and same `session_id`) or a more specific `query` (e.g. 'Springfield, MO'). - status='not_found': ask the user for a more specific description. Args: query: Place to resolve (e.g. 'the Bay Area', 'the mall in Culver City', 'Springfield', 'zip 75103') geometry_id: A geometry id from a prior candidate; resolves deterministically session_id: Opaque id echoed back to correlate a clarifying follow-up Returns: A ResolvedLocation with status, geometry_ids, name, centroid, area, place_count, and (when ambiguous) candidates + a clarifying question.

resolve_location

Resolve a fuzzy or partial NAME to a canonical brand, retail area, or category via semantic similarity — the entity analog of resolve_location. Use it before get_info / get_visits when you only have an approximate name ('coffee', 'the mall in Culver City'). Optionally pass `location` or `in_geometry` to restrict to entities present in an area. To COUNT brands or categories inside an area (not name-match), prefer find_locations(location=..., aggregate="brand"|"category"). Use this tool's 'retail_area' type to enumerate malls/centers in an area (no find_locations equivalent). Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: query: Search text (e.g. 'coffee', 'Starbucks', 'mall in Seattle') entity_type: 'brand', 'retail_area', or 'category' location: Free-text place to restrict results to, resolved inline (e.g. 'Times Square', 'California', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) to restrict results to (e.g. 'retail_area:abc,retail_area:def', 'cbsa:41860') limit: Max results (default 10, max 20) Returns: Matching entities ranked by similarity, plus resolved_geometry. Examples: Coffee brands: query="coffee", entity_type="brand" Retail areas in an area: entity_type="retail_area", location="Pentagon City, VA" Named mall: query="Seattle mall", entity_type="retail_area" Category for a term: query="gym", entity_type="category"

search_entities