Recipes / Build a Custom Tool

Build a Custom Tool in 5 Minutes

In this recipe, we'll create a custom MCP tool that returns low-stock parts. Then we'll test it in the live preview and see it in the MCP schema that AI assistants will use.

Step 1: Open the Custom Tool Builder

Navigate to AI Platform > Custom Tools in your organization's console.

Click Create Custom Tool (or use the REST API: POST /api/mcp/custom-tools/).

Step 2: Configure the Data Source

Fill in the basic info:

• Tool Name: list_low_stock_items
• Description: "Return parts items with stock below a threshold"
• Category: Inventory (optional, for UI grouping)
• Active: Toggle ON

Step 3: Select Your Data Source

Under Data Source, select the model to query:

• Choose spare_parts.Item from the dropdown

The form will immediately fetch all available fields for the Item model (name, sku, location, quantity, etc.).

Step 4: Add Filters

Under Filters, define conditions:

1. Click Add Filter
2. Select field: quantity
3. Select operator: Less Than (<)
4. Enter value: {{min_quantity}} — a parameter placeholder

Click Add another filter if you want. For example:

• Field: is_active, Operator: Equals, Value: true

Step 5: Set Output Fields

Under Output Fields, select which fields to return:

• name
• sku
• location
• quantity
• last_updated

Uncheck fields you don't need.

Step 6: Define Input Parameters

Under Input Parameters, click Add Parameter:

• Name: min_quantity
• Type: integer
• Description: "Threshold for low stock"
• Required: Yes
• Default Value: 5 (optional)

This parameter will appear in the MCP schema so callers know they can pass it.

Step 7: Aggregation (Optional)

If you want to count results instead of returning full records, toggle Aggregation ON and choose Count. Leave it off for this recipe.

Step 8: Result Limit & Order

• Limit Results: 100 — cap results to 100 rows
• Order By: quantity (ascending) or name (alphabetical)

Step 9: Live Preview

Before saving, test your tool. Click the Live Preview panel on the right and enter test parameters:

• min_quantity: 10

Click Preview. You'll see sample results:

{
  "results": [
    {
      "name": "Bearing XYZ",
      "sku": "BRG-001",
      "location": "Shelf A3",
      "quantity": 5,
      "last_updated": "2026-05-21T10:00:00Z"
    }
  ],
  "count": 12,
  "execution_time_ms": 45
}

If the results look good, save. If not, adjust your filters and preview again.

Step 10: Save

Click Save Custom Tool. The tool is now live and accessible via:

1. MCP: tools/list includes custom_list_low_stock_items with JSON Schema
2. REST: GET /api/mcp/custom-tools/ returns your tool
3. UI: AI Platform > Custom Tools table shows it
4. Audit trail: Every execution is logged

Step 11: See the MCP Schema

In the MCP Schema Preview panel, you'll see:

{
  "name": "custom_list_low_stock_items",
  "description": "Return parts items with stock below a threshold",
  "inputSchema": {
    "type": "object",
    "properties": {
      "min_quantity": {
        "type": "integer",
        "description": "Threshold for low stock"
      }
    },
    "required": ["min_quantity"]
  }
}

This is exactly what an AI assistant sees. It knows to pass min_quantity as a parameter.

Using Your Tool via REST

Test your tool programmatically:

curl -X POST https://gtm.cognethics.com/api/mcp/custom-tools/list_low_stock_items/test/ \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Organization-Context: YOUR_ORG_ID" \
  -d '{
    "min_quantity": 10
  }'

Response:

{
  "results": [
    {
      "name": "Bearing XYZ",
      "sku": "BRG-001",
      "location": "Shelf A3",
      "quantity": 5
    }
  ],
  "count": 12,
  "execution_time_ms": 42
}

Export & Duplicate

In the Custom Tools list:

• Export: Click the tool row > Export Config to download as JSON (useful for version control or sharing)
• Duplicate: Click Duplicate to clone the tool with a new name (handy for variants)
• Import: Click Import Config to bulk-create tools from a JSON file

Advanced: Filters with Multiple Conditions

Filters are AND'd together by default:

(quantity < min_quantity) AND (is_active = true) AND (category IN ['fasteners', 'bearings'])

Each filter row adds another AND condition. If you need OR logic, build separate tools.

Advanced: Aggregations

You can group and aggregate:

SELECT location, COUNT(*) as count, SUM(quantity) as total_qty
WHERE quantity < min_quantity
GROUP BY location
LIMIT 100

Configure this in Aggregation: Group by location, then set aggregation_field to COUNT(*).

Troubleshooting

Next Steps

• Assign your tool to a Tool Group so only certain roles can use it
• Create an MCP Server Profile for your role to expose this tool to AI assistants
• View execution history in the tool detail page (audit trail of every run)
• Read the Extensibility overview for tool groups, profiles, and federation