Skip to main content

​
Retrieve Tools Endpoint

POST /v1/retrieve_tools Find available tools using natural language query.

​
Request Body

{
  "query": "Deploy to production and notify the team",
  "top_k": 5,
  "filter": {
    "server": "aws-mcp",
    "category": "infrastructure",
    "min_score": 0.85
  }
}

​
Parameters

ParameterTypeRequiredDefaultDescription
querystringYes-Natural language query (max 500 chars)
top_kintegerNo5Number of tools to return (1-50)
filterobjectNo-Filter results
filter.serverstringNo-Filter by MCP server name
filter.categorystringNo-Filter by tool category
filter.min_scorenumberNo0.0Minimum relevance score

​
Response

{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "deploy-aws-ecs",
        "server": "aws-mcp",
        "score": 0.98,
        "description": "Deploy to AWS ECS cluster",
        "category": "infrastructure",
        "tags": ["aws", "deployment", "ecs"]
      }
    ],
    "query_time_ms": 45,
    "total_tools_searched": 156
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Examples

​
Simple Query

curl -X POST "https://api.agent-corex.com/v1/retrieve_tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Send a Slack message"
  }'

​
With Filters

curl -X POST "https://api.agent-corex.com/v1/retrieve_tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Deploy",
    "top_k": 10,
    "filter": {
      "server": "aws-mcp",
      "min_score": 0.80
    }
  }'

​
Using SDK

const tools = await agent.retrieveTools({
  query: "Deploy to production",
  topK: 5
});

console.log(tools);

​
Error Responses

​
Bad Request (400)

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Query is required",
    "details": {
      "parameter": "query"
    }
  }
}

​
Unauthorized (401)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

​
Rate Limited (429)

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retry_after": 60
  }
}

​
Performance Tips

  1. Be specific - “Deploy to AWS Lambda” returns better results than “deploy”
  2. Use filters - Reduce search space with server/category filters
  3. Set appropriate top_k - Usually 3-5 is sufficient
  4. Cache results - Same queries within 1 hour use cache

​
Next Steps

Execute Tool Endpoint

Run tools with the execution API.

Get Tool Endpoint

Get details about specific tools.

API Overview

Complete API reference.
See Dynamic Retrieval for details on how tools are ranked. 🚀