MCP Tool Reference

These tools are exposed over Bucky's MCP server. Each entry is generated from the tool registry, so it always reflects what the server actually offers. All MCP tools are read-only.

Projects

Query Projects

queryProjects

Search the current user's saved projects by name, category, phase, or budget range. Returns { success, data: { projects[], count, note? } } with project status, primary design, and service progress. Use when users ask about their projects, project status, or want to list/filter their projects. Requires authentication. Do NOT use for marketplace browsing — use queryDesigns or queryMarketItemBuilds.

Read-only: yes · Auth scope: user

Parameters:

• name (string, optional) — Project name to search for (e.g. "My Vancouver House", "Kitsilano ADU")
• category (string, optional) — Project category (e.g. "house", "duplex", "adu", "renovation")
• phaseCode (string, optional) — Phase code (e.g. "DESIGN", "PERMIT", "BUILD", "FINANCE")
• minBudget (number, optional) — Minimum project budget in CAD (e.g. 200000)
• maxBudget (number, optional) — Maximum project budget in CAD (e.g. 800000)
• limit (integer, optional) — Maximum results to return, 1-20 (default 10)
• offset (integer, optional) — Pagination offset (default 0). Use with limit to page through results.
• response_format (enum: "concise" | "detailed", optional) — Output verbosity: "concise" returns key fields only (default), "detailed" returns all available fields

Query Project Details

queryProjectDetails

Get full details for a single project including services, designs, amenities, financing sources, and team members. Returns { success, data: { ...projectFields } } with all nested relationships. Use when users ask about a specific project's details, services, financing, or team — requires a projectId from queryProjects. Requires authentication. Do NOT call without first obtaining a projectId from queryProjects results.

Read-only: yes · Auth scope: user

Parameters:

• projectId (string, required) — Project UUID — get from queryProjects results (e.g. "a1b2c3d4-e5f6-...")

Geography & parcels

Query Geo Divisions

queryGeoDivisions

Search geographic divisions (countries, provinces, regions, cities) in the Bucky database. Returns { success, data: { geo_divisions[], count, note? } } with IDs, coordinates, and admin levels. Use to resolve location names to geo_division IDs needed by other tools (permitChecklist, costEstimate, spatialSearch). Do NOT use for finding professionals in a location (use querySellers with locationQuery).

Read-only: yes · Auth scope: public

Parameters:

• name (string, optional) — Geographic area name (e.g. "Vancouver", "British Columbia", "Ontario")
• countryCode (string, optional) — ISO country code (e.g. "CA" for Canada, "US" for United States)
• partialMatch (boolean, optional) — Skip exact-match and go straight to partial matching
• limit (integer, optional) — Maximum results to return, 1-20 (default 10)
• offset (integer, optional) — Pagination offset (default 0). Use with limit to page through results.
• response_format (enum: "concise" | "detailed", optional) — Output verbosity: "concise" returns key fields only (default), "detailed" returns all available fields

Resolve Address Context

resolveAddressContext

Forward-geocodes a free-text address or location description, then returns the matching geo_division (municipality/jurisdiction), local named areas (neighbourhoods, planning districts), the specific lot if found, and applicable zoning information. Returns { success, data: { resolved_coordinates, resolved_place_name, geo_division, named_areas, lot, zone_areas } }. IMPORTANT: When zone_areas is non-empty, always present zone_code and zone_name to the user immediately — this is the zoning designation for their address. Use this whenever the user mentions a street address, intersection, neighbourhood name, or city to establish spatial context. Do NOT use for general geographic browsing (use queryGeoSearch). For regulatory bylaw text use knowledgeLookup; for live municipal dataset rows (hydrants, parcels, permits) use cityDataLookup after resolving coordinates.

Read-only: yes · Auth scope: public

Parameters:

• address (string, required) — Street address, city, or location description to geocode
• countryBias (enum: "CA" | "US", required) — Country to bias results toward. Defaults to Canada.

Find Nearby Records

findNearbyRecords

Find builds and sellers near a coordinate pair. Returns up to 5 builds and 5 sellers within 5 km, with address, size, price, and distance details. Returns { success, data: { builds[], sellers[], summary } }. Use after resolveAddressContext when the user asks "what's been built nearby?" or "who builds in this area?". Do NOT use for browsing marketplace listings (use queryMarketItemBuilds) or for filtered spatial search (use spatialSearch).

Read-only: yes · Auth scope: public

Parameters:

• lat (number, required) — Latitude (e.g. 49.2827)
• lng (number, required) — Longitude (e.g. -123.1207)

Marketplace

Query Sellers

querySellers

Search for professionals and service providers (architects, engineers, contractors, trades) by name, location, or role. Returns { success, data: { sellers[], count, note? } } with roles, verification status, and service areas. Use when users ask about finding professionals, tradespeople, or service providers for their project. Do NOT use for builders/manufacturers with design catalogs (use builderSearch).

Read-only: yes · Auth scope: public

Parameters:

• name (string, optional) — Seller or company name (e.g. "Honomobo", "Nexii Building Solutions")
• locationQuery (string, optional) — Location name (e.g. "Vancouver", "British Columbia", "Toronto")
• geoDivisionId (string, optional) — Exact geo_division UUID — get from queryGeoDivisions results
• verified (string, optional) — Filter by verification status ("true" or "false")
• category (string, optional) — Professional role or dwelling category (e.g. "architect", "contractor", "electrician", "house", "duplex")
• limit (integer, optional) — Maximum results to return, 1-20 (default 10)
• offset (integer, optional) — Pagination offset (default 0). Use with limit to page through results.
• response_format (enum: "concise" | "detailed", optional) — Output verbosity: "concise" returns key fields only (default), "detailed" returns all available fields

Search

Semantic Search

semanticSearch

Full-text and vector search across the Bucky knowledge base: construction guides, sellers, and designs. Returns { success, data: { formatted, result_count, timing } } as a pre-formatted text summary. Use for general knowledge questions about construction or when no structured query tool fits. Do NOT use when a specific zone code is mentioned (use knowledgeLookup), for live municipal dataset rows (use cityDataLookup), or when searching for specific entities like projects (use queryProjects), designs (use queryDesigns), or sellers (use querySellers).

Read-only: yes · Auth scope: public

Parameters:

• query (string, required) — Natural language question (e.g. "maximum height for RS-1 zone", "laneway house permit requirements Vancouver")
• doc_types (string[], optional) — Filter by document type (valid values: "seller", "market_item", "service", "ruleset_item", "geo_division")
• filters (object, optional) — Optional filters extracted from user query
• limit (integer, required)
• projectGeoDivisionId (string, optional) — Active project geo_division UUID for location-aware reranking — get from queryProjects or queryGeoDivisions
• response_format (enum: "concise" | "detailed", optional) — Output verbosity: "concise" returns key fields only (default), "detailed" returns all available fields