Skip to main content

​
Creating Tools

All tools share these common fields:
FieldRequiredDescription
keyYesUnique identifier used to reference the tool (alphanumeric, hyphens, underscores)
descriptionYesUsed by agents to decide when and how to call the tool. Be explicit.
pathYesProject path where the tool is stored, e.g. "Default"
typeYesTool type: function, json_schema, http, mcp, or code
display_nameNoHuman-readable name shown in the Studio

​
Function Tool

A Function Tool defines a callable function using a JSON Schema parameter definition. The model decides when to call it and fills in the parameters. 
curl -X POST https://api.orq.ai/v2/tools \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "get_weather",
    "display_name": "Get Weather",
    "description": "Returns the current weather for a given city",
    "path": "Default",
    "type": "function",
    "function": {
      "name": "get_weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city name, e.g. Amsterdam"
          },
          "unit": {
            "type": "string",
            "description": "Temperature unit: celsius or fahrenheit"
          }
        },
        "required": ["location"]
      }
    }
  }'

​
JSON Schema Tool

A JSON Schema Tool enforces structured output from the model using a full JSON Schema definition. Unlike Function Tools, the schema is defined at the top level with a name and description. 
curl -X POST https://api.orq.ai/v2/tools \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "extract_contact",
    "display_name": "Extract Contact",
    "description": "Extracts contact information from unstructured text",
    "path": "Default",
    "type": "json_schema",
    "json_schema": {
      "name": "extract_contact",
      "description": "Extracts name, email, and phone from text",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" }
        },
        "required": ["name"]
      }
    }
  }'

​
HTTP Tool

An HTTP Tool makes a real HTTP request to an external API at runtime. Use {{variable}} syntax in any field to inject dynamic values. 
curl -X POST https://api.orq.ai/v2/tools \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "search_products",
    "display_name": "Search Products",
    "description": "Searches the product catalog by keyword",
    "path": "Default",
    "type": "http",
    "http": {
      "blueprint": {
        "url": "https://api.example.com/products/search",
        "method": "GET",
        "headers": {
          "Accept": "application/json"
        },
        "arguments": {
          "query": {
            "type": "string",
            "description": "Search keyword",
            "send_to_model": true
          }
        }
      }
    }
  }'

​
MCP Tool

An MCP Tool connects to an external Model Context Protocol server. Orq.ai fetches the available capabilities from the server automatically. The server URL must be reachable at creation time. For private MCP servers, use the headers field to pass authentication tokens. Header values are stored securely when encrypted is set to true. 
curl -X POST https://api.orq.ai/v2/tools \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "orq_docs_mcp",
    "display_name": "Orq Docs MCP",
    "description": "Search Orq.ai documentation and get integration guidance",
    "path": "Default",
    "type": "mcp",
    "mcp": {
      "server_url": "https://docs.orq.ai/mcp",
      "connection_type": "http",
      "headers": {
        "Authorization": { "value": "Bearer $MY_TOKEN", "encrypted": true }
      }
    }
  }'

​
Python Tool

A Python Tool runs Python code at runtime. Define the logic directly in the code field and declare expected parameters using a JSON Schema. 
curl -X POST https://api.orq.ai/v2/tools \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "calculate_discount",
    "display_name": "Calculate Discount",
    "description": "Calculates the discounted price given a price and a discount percentage",
    "path": "Default",
    "type": "code",
    "code_tool": {
      "language": "python",
      "code": "price = float(params.get(\"price\", 0))\ndiscount = float(params.get(\"discount\", 0))\nresult = price * (1 - discount / 100)",
      "parameters": {
        "type": "object",
        "properties": {
          "price": { "type": "number", "description": "Original price" },
          "discount": { "type": "number", "description": "Discount percentage (0-100)" }
        },
        "required": ["price", "discount"]
      }
    }
  }'

​
Using Tools

Once created, tools can be used in Agents and Deployments.
All tool types are supported. Reference a tool by key in the settings.tools array. Your agent’s instructions must explicitly describe each tool and when to use it.
Learn more about using tools in Agents.
Only Function Tools are supported. Import a previously created tool from the Tools tab in the deployment configuration.
Learn more about using tools in Deployments.