# Standard Tools

Complete reference for AIDP's standard MCP tools.

## Available Tools

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

1. **search\_businesses** - Search for businesses using natural language
2. **get\_business** - Get detailed information about a specific business
3. **get\_business\_hours** - Check business hours and availability
4. **get\_business\_services** - Get services offered by a business
5. **get\_business\_reviews** - Get customer reviews and ratings

***

## search\_businesses

Search for businesses using natural language queries.

### Parameters

```json
{
  "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

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

### Example Response

```json
{
  "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

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

### Example Request

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

### Example Response

```json
{
  "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

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

### Example Request

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

### Example Response

```json
{
  "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

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

### Example Request

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

### Example Response

```json
{
  "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

```json
{
  "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

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

### Example Response

```json
{
  "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:

```json
{
  "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:

```javascript
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:

```javascript
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:

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

***

## Next Steps

* [Create Custom Tools →](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/custom-tools)
* [Testing Your Tools →](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/testing)
* [MCP Integration Guide →](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration)

***

## Support

* 📧 Email: <tools@aidp.dev>
* 💬 GitHub Discussions: [github.com/aidp/platform/discussions](https://github.com/aidp/platform/discussions)
* 📚 Tool Catalog: [docs.aidp.dev/mcp/tools](https://docs.aidp.dev/mcp/tools)