> ## Documentation Index > Fetch the complete documentation index at: https://docs.agent-corex.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve tools by natural language query > Find available tools using natural language. Tools are ranked by relevance to your query. Supports semantic search and intelligent ranking based on popularity and user history. ## OpenAPI ````yaml /api-reference/openapi.yaml post /retrieve_tools openapi: 3.0.0 info: title: Agent-CoreX API description: Dynamic tool retrieval and execution for AI agents using MCP servers version: 1.0.0 contact: name: Agent-CoreX Support email: support@agent-corex.com url: https://github.com/anthropics/agent-corex license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.agent-corex.com/v1 description: Production API - url: https://staging-api.agent-corex.com/v1 description: Staging API - url: http://localhost:3000/v1 description: Local development security: - bearerAuth: [] - apiKey: [] tags: - name: Tools description: Tool discovery and execution - name: Servers description: MCP server management - name: System description: System and health endpoints externalDocs: description: Full documentation url: https://docs.agent-corex.com paths: /retrieve_tools: post: tags: - Tools summary: Retrieve tools by natural language query description: > Find available tools using natural language. Tools are ranked by relevance to your query. Supports semantic search and intelligent ranking based on popularity and user history. operationId: retrieveTools requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RetrieveToolsRequest' examples: simple_query: summary: Simple query value: query: Create a GitHub pull request top_k: 5 complex_query: summary: Complex multi-tool query value: query: Create GitHub PR, deploy to AWS Lambda, notify Slack channel top_k: 10 filtered_query: summary: Query with filters value: query: Deploy application top_k: 5 filter: server: aws-mcp category: infrastructure responses: '200': description: Tools retrieved successfully content: application/json: schema: $ref: '#/components/schemas/RetrieveToolsResponse' examples: success: summary: Successful response value: success: true data: tools: - name: create-pull-request server: github-mcp score: 0.98 description: Create a new pull request on GitHub inputSchema: type: object properties: repository: type: string title: type: string - name: deploy-aws-lambda server: aws-mcp score: 0.95 description: Deploy function to AWS Lambda query_time_ms: 45 meta: request_id: req_123abc timestamp: '2024-01-15T10:30:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: schemas: RetrieveToolsRequest: type: object required: - query properties: query: type: string description: Natural language query to find tools maxLength: 500 example: Create a GitHub pull request and deploy to production top_k: type: integer description: Number of tools to return (max 50) default: 5 minimum: 1 maximum: 50 filter: type: object description: Optional filters for results properties: server: type: string description: Filter by MCP server name category: type: string description: Filter by tool category min_score: type: number description: Minimum relevance score (0.0 to 1.0) minimum: 0 maximum: 1 user_id: type: string description: Override current user (admin only) RetrieveToolsResponse: type: object properties: success: type: boolean example: true data: type: object properties: tools: type: array items: $ref: '#/components/schemas/Tool' query_time_ms: type: integer description: Time taken to process query in milliseconds total_tools_searched: type: integer description: Total tools in the index meta: $ref: '#/components/schemas/ResponseMeta' Tool: type: object properties: name: type: string description: Unique tool identifier server: type: string description: MCP server that provides this tool score: type: number format: float description: Relevance score (0.0 to 1.0) minimum: 0 maximum: 1 description: type: string description: Human-readable tool description category: type: string description: Tool category inputSchema: type: object description: JSON Schema for tool input parameters outputSchema: type: object description: JSON Schema for tool output tags: type: array items: type: string description: Tool tags for classification ResponseMeta: type: object properties: request_id: type: string description: Unique request identifier timestamp: type: string format: date-time description: Request timestamp ErrorResponse: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string enum: - INVALID_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - RATE_LIMITED - SERVER_ERROR message: type: string details: type: object additionalProperties: true meta: $ref: '#/components/schemas/ResponseMeta' responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: Too many requests headers: X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token obtained from dashboard apiKey: type: apiKey in: header name: Authorization description: API key in format "Bearer YOUR_API_KEY" ````