Standard Tools

Complete reference for AIDP's standard MCP tools.

Available Tools

AIDP provides 5 standard MCP tools for business discovery and information retrieval:

search_businesses - Search for businesses using natural language
get_business - Get detailed information about a specific business
get_business_hours - Check business hours and availability
get_business_services - Get services offered by a business
get_business_reviews - Get customer reviews and ratings

search_businesses

Search for businesses using natural language queries.

Parameters

{
  "query": "string (required)",
  "location": {
    "lat": "number (required)",
    "lon": "number (required)",
    "distance": "string (optional, default: '10km')"
  },
  "category": "string (optional)",
  "limit": "number (optional, default: 10, max: 50)",
  "offset": "number (optional, default: 0)"
}

Example Request

{
  "tool": "search_businesses",
  "parameters": {
    "query": "coffee shops with wifi",
    "location": {
      "lat": 45.5231,
      "lon": -122.6765,
      "distance": "5km"
    },
    "limit": 10
  }
}

Example Response

{
  "success": true,
  "data": {
    "query": "coffee shops with wifi",
    "response": "I found several great coffee shops with wifi in your area...",
    "businesses": [
      {
        "id": "biz_abc123",
        "name": "Artisan Coffee Roasters",
        "category": "restaurants",
        "description": "Family-owned coffee roastery...",
        "distance": 450,
        "address": {
          "street": "123 Main St",
          "city": "Portland",
          "state": "OR",
          "zip": "97201"
        },
        "coordinates": {
          "lat": 45.5235,
          "lon": -122.677
        },
        "phone": "+1-503-555-0123",
        "website": "https://artisancoffee.com",
        "isOpenNow": true,
        "averageRating": 4.8,
        "aiExclusiveContent": {
          "insiderTips": ["Ask for the seasonal pour-over"],
          "localSecrets": ["Best time to visit: Tuesday mornings"]
        }
      }
    ],
    "total": 42,
    "pagination": {
      "offset": 0,
      "limit": 10,
      "hasMore": true
    }
  }
}

Use Cases

Discovery: "Find coffee shops near me"
Specific Needs: "Restaurants with outdoor seating"
Contextual: "Where can I get breakfast at 6am"

get_business

Get detailed information about a specific business.

Parameters

{
  "businessId": "string (required)",
  "includeReviews": "boolean (optional, default: false)",
  "includeAnalytics": "boolean (optional, default: false)"
}

Example Request

{
  "tool": "get_business",
  "parameters": {
    "businessId": "biz_abc123",
    "includeReviews": true
  }
}

Example Response

{
  "success": true,
  "data": {
    "id": "biz_abc123",
    "name": "Artisan Coffee Roasters",
    "category": "restaurants",
    "description": "Family-owned coffee roastery specializing in single-origin beans...",
    "address": {
      "street": "123 Main St",
      "city": "Portland",
      "state": "OR",
      "zip": "97201",
      "country": "USA"
    },
    "coordinates": {
      "lat": 45.5235,
      "lon": -122.677
    },
    "contact": {
      "phone": "+1-503-555-0123",
      "email": "hello@artisancoffee.com",
      "website": "https://artisancoffee.com"
    },
    "hours": {
      "monday": { "open": "07:00", "close": "18:00" },
      "tuesday": { "open": "07:00", "close": "18:00" },
      "wednesday": { "open": "07:00", "close": "18:00" },
      "thursday": { "open": "07:00", "close": "18:00" },
      "friday": { "open": "07:00", "close": "20:00" },
      "saturday": { "open": "08:00", "close": "20:00" },
      "sunday": { "open": "08:00", "close": "17:00" }
    },
    "services": [
      {
        "name": "Espresso Drinks",
        "description": "Handcrafted espresso beverages",
        "pricing": { "min": 4.0, "max": 6.5 }
      }
    ],
    "amenities": ["wifi", "outdoor_seating", "parking"],
    "averageRating": 4.8,
    "totalReviews": 342,
    "priceLevel": "$$",
    "aiExclusiveContent": {
      "insiderTips": ["Ask for the seasonal pour-over", "Try the house-made pastries"],
      "localSecrets": ["Best time to visit: Tuesday mornings", "Owner is a certified Q-grader"],
      "behindTheScenes": ["We roast in-house twice weekly", "Beans sourced directly from farmers"]
    },
    "reviews": [
      {
        "rating": 5,
        "text": "Best coffee in Portland!",
        "date": "2024-12-01"
      }
    ]
  }
}

Use Cases

Detailed Info: Get complete business profile
Decision Making: Compare multiple businesses
Recommendations: Provide comprehensive information

get_business_hours

Check if a business is currently open and get hours information.

Parameters

{
  "businessId": "string (required)",
  "datetime": "string (optional, ISO 8601 format)"
}

Example Request

{
  "tool": "get_business_hours",
  "parameters": {
    "businessId": "biz_abc123"
  }
}

Example Response

{
  "success": true,
  "data": {
    "businessId": "biz_abc123",
    "businessName": "Artisan Coffee Roasters",
    "isOpenNow": true,
    "currentHours": {
      "open": "07:00",
      "close": "18:00"
    },
    "nextChange": {
      "status": "closes",
      "time": "2024-12-12T18:00:00Z"
    },
    "weeklyHours": {
      "monday": { "open": "07:00", "close": "18:00" },
      "tuesday": { "open": "07:00", "close": "18:00" },
      "wednesday": { "open": "07:00", "close": "18:00" },
      "thursday": { "open": "07:00", "close": "18:00" },
      "friday": { "open": "07:00", "close": "20:00" },
      "saturday": { "open": "08:00", "close": "20:00" },
      "sunday": { "open": "08:00", "close": "17:00" }
    },
    "specialHours": [
      {
        "date": "2024-12-25",
        "status": "closed",
        "reason": "Christmas Day"
      }
    ],
    "timezone": "America/Los_Angeles"
  }
}

Use Cases

Availability Check: "Is this business open now?"
Planning: "What time does it close?"
Special Hours: Check holiday hours

get_business_services

Get services and offerings from a business.

Parameters

{
  "businessId": "string (required)",
  "category": "string (optional)"
}

Example Request

{
  "tool": "get_business_services",
  "parameters": {
    "businessId": "biz_abc123"
  }
}

Example Response

{
  "success": true,
  "data": {
    "businessId": "biz_abc123",
    "businessName": "Artisan Coffee Roasters",
    "services": [
      {
        "id": "svc_001",
        "name": "Espresso Drinks",
        "category": "beverages",
        "description": "Handcrafted espresso beverages using single-origin beans",
        "pricing": {
          "type": "range",
          "min": 4.0,
          "max": 6.5,
          "currency": "USD"
        },
        "availability": "always",
        "popular": true
      },
      {
        "id": "svc_002",
        "name": "Pour Over Coffee",
        "category": "beverages",
        "description": "Single-origin pour over coffee, brewed to order",
        "pricing": {
          "type": "fixed",
          "amount": 5.0,
          "currency": "USD"
        },
        "availability": "always",
        "popular": true
      },
      {
        "id": "svc_003",
        "name": "Coffee Tasting",
        "category": "experiences",
        "description": "Guided tasting of 4 single-origin coffees",
        "pricing": {
          "type": "fixed",
          "amount": 25.0,
          "currency": "USD"
        },
        "availability": "by_appointment",
        "duration": "45 minutes"
      }
    ],
    "categories": ["beverages", "food", "experiences"],
    "total": 12
  }
}

Use Cases

Service Discovery: "What services do they offer?"
Pricing: "How much does it cost?"
Availability: "Can I book this service?"

get_business_reviews

Get customer reviews and ratings for a business.

Parameters

{
  "businessId": "string (required)",
  "limit": "number (optional, default: 10, max: 50)",
  "offset": "number (optional, default: 0)",
  "minRating": "number (optional, 1-5)",
  "sortBy": "string (optional, 'recent' | 'rating' | 'helpful')"
}

Example Request

{
  "tool": "get_business_reviews",
  "parameters": {
    "businessId": "biz_abc123",
    "limit": 5,
    "sortBy": "recent"
  }
}

Example Response

{
  "success": true,
  "data": {
    "businessId": "biz_abc123",
    "businessName": "Artisan Coffee Roasters",
    "averageRating": 4.8,
    "totalReviews": 342,
    "ratingDistribution": {
      "5": 280,
      "4": 45,
      "3": 12,
      "2": 3,
      "1": 2
    },
    "reviews": [
      {
        "id": "rev_001",
        "rating": 5,
        "title": "Best coffee in Portland!",
        "text": "Amazing single-origin pour overs. The baristas really know their craft.",
        "author": "Sarah M.",
        "date": "2024-12-01",
        "helpful": 12,
        "verified": true
      },
      {
        "id": "rev_002",
        "rating": 5,
        "title": "Hidden gem",
        "text": "Great atmosphere and even better coffee. The seasonal drinks are creative.",
        "author": "Mike R.",
        "date": "2024-11-28",
        "helpful": 8,
        "verified": true
      }
    ],
    "pagination": {
      "offset": 0,
      "limit": 5,
      "hasMore": true
    }
  }
}

Use Cases

Social Proof: Show customer feedback
Decision Making: Help users choose businesses
Quality Assessment: Understand business reputation

Error Handling

All tools return consistent error responses:

{
  "success": false,
  "error": {
    "code": "BUSINESS_NOT_FOUND",
    "message": "Business with ID 'biz_invalid' not found",
    "details": {
      "businessId": "biz_invalid"
    }
  }
}

Common Error Codes

INVALID_PARAMETERS - Missing or invalid parameters
BUSINESS_NOT_FOUND - Business ID doesn't exist
RATE_LIMIT_EXCEEDED - Too many requests
AUTHENTICATION_ERROR - Invalid API key
SERVICE_UNAVAILABLE - Temporary service issue

Best Practices

1. Cache Results

Cache business data to reduce API calls:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedBusiness(businessId) {
  const cached = cache.get(businessId);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await callTool('get_business', { businessId });
  cache.set(businessId, { data, timestamp: Date.now() });
  return data;
}

2. Handle Pagination

For large result sets, use pagination:

async function getAllBusinesses(query) {
  const allBusinesses = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const result = await callTool('search_businesses', {
      query,
      limit,
      offset,
    });

    allBusinesses.push(...result.data.businesses);

    if (!result.data.pagination.hasMore) break;
    offset += limit;
  }

  return allBusinesses;
}

3. Provide Context

Include user context for better results:

const result = await callTool('search_businesses', {
  query: userQuery,
  location: userLocation,
  context: {
    timeOfDay: new Date().getHours(),
    dayOfWeek: new Date().getDay(),
  },
});

Next Steps

Support

📧 Email: tools@aidp.dev
💬 GitHub Discussions: github.com/aidp/platform/discussions
📚 Tool Catalog: docs.aidp.dev/mcp/tools

PreviousSetting Up MCP Server NextCustom Tools

Last updated 3 months ago

hashtagAvailable Tools

hashtagsearch_businesses

hashtagParameters

hashtagExample Request

hashtagExample Response

hashtagUse Cases

hashtagget_business

hashtagParameters

hashtagExample Request

hashtagExample Response

hashtagUse Cases

hashtagget_business_hours

hashtagParameters

hashtagExample Request

hashtagExample Response

hashtagUse Cases

hashtagget_business_services

hashtagParameters

hashtagExample Request

hashtagExample Response

hashtagUse Cases

hashtagget_business_reviews

hashtagParameters

hashtagExample Request

hashtagExample Response

hashtagUse Cases

hashtagError Handling

hashtagCommon Error Codes

hashtagBest Practices

hashtag1. Cache Results

hashtag2. Handle Pagination

hashtag3. Provide Context

hashtagNext Steps

hashtagSupport

Available Tools

search_businesses

Parameters

Example Request

Example Response

Use Cases

get_business

Parameters

Example Request

Example Response

Use Cases

get_business_hours

Parameters

Example Request

Example Response

Use Cases

get_business_services

Parameters

Example Request

Example Response

Use Cases

get_business_reviews

Parameters

Example Request

Example Response

Use Cases

Error Handling

Common Error Codes

Best Practices

1. Cache Results

2. Handle Pagination

3. Provide Context

Next Steps

Support