Custom HTTP and Code Tools

Clouisle groups tools into three kinds: Built-in tools (registered by the platform, no creation needed — see Built-in Tools), MCP servers (connect an external MCP Server — see MCP Servers), and Custom tools (created by teams). Custom tools belong to the current team, support the HTTP API, Code, and Database types, and can be configured, tested, and shared with other teams.

Tool Types

The Create Tool menu under Capabilities > Tools offers four entries (MCP servers have their own page):

Naming Rules

Tool names can only contain letters, digits, and underscores, and must start with a letter, for example lookup_order. Names must be unique within the team.

Creating HTTP API Tools

1. In Capabilities > Tools, select Create Tool > HTTP API.
2. Set the tool name, display name, description, and category.
3. Configure the HTTP method (default GET), URL, headers, query parameters, JSON request body, and response path.
4. Use {parameter_name} placeholders in the URL, headers, query parameters, and body.
5. The timeout defaults to 30 seconds, range 1-300 seconds.
6. After saving, select Run Test and confirm the result path and error behavior.

HTTP Tool Configuration Example: Customer Lookup

Name: CRM Lookup
Description: Look up customer information in CRM system
Category: Data
Type: Custom

Endpoint Configuration:
  URL: https://api.crm.example.com/customers
  Method: GET
  Authentication: API Key
  API Key Header: X-API-Key
  API Key: crm_...
  Query Parameters:
    customer_id: "{customer_id}"
  Timeout: 30 seconds

Input Parameters:
  - name: customer_id
    type: string
    required: true
    description: Customer ID to lookup

Response Format:
  type: json
  schema:
    customer_id: string
    name: string
    email: string
    phone: string
    status: string

HTTP Tool Configuration Example: Create Ticket (POST)

Name: Create Support Ticket
Description: Create a support ticket in the ticketing system
Category: Communication
Type: Custom

Endpoint Configuration:
  URL: https://api.tickets.example.com/tickets
  Method: POST
  Authentication: Bearer Token
  Token: Bearer tk_...
  Content-Type: application/json
  Timeout: 30 seconds

Input Parameters:
  - name: title
    type: string
    required: true
    description: Ticket title

  - name: description
    type: string
    required: true
    description: Ticket description

  - name: priority
    type: enum
    required: false
    default: medium
    options: [low, medium, high, urgent]
    description: Ticket priority

  - name: assignee
    type: string
    required: false
    description: Assignee email

Response Format:
  type: json
  schema:
    ticket_id: string
    status: string
    created_at: string

Creating Code Tools

Code tools support Python and JavaScript, executed in a restricted sandbox. Python packages must use exact package==version; JavaScript packages must use package@version. You can configure the command argv, package source address, artifacts, and resource limits.

Default resource limits:

Artifact paths must be under /workspace and can be marked optional.

Creating Database Tools

A database tool lets an Agent query an external database directly. The connection details (host, port, credentials, connection URL) stay hidden from the model — the Agent only sees the tool name and description, so the description should say what the database holds and which questions it answers.

1. Under Capabilities > Tools, select Create Tool > Database Tool.
2. Pick the database type: postgresql, mysql, redis, or mongodb.
3. Fill in the connection, using either mode:
   • Field mode: host (host), port (port), database (database), username (username), password (password), SSL.
   • Connection URL mode: fill in url directly (common for Redis / MongoDB); Redis can also set the logical database index db, and MongoDB can set the auth database auth_source.
4. Set the query timeout (timeout, default 15s, range 1-120) and the maximum returned rows (max_limit, default 100, range 1-1000).
5. Select Test connection (which calls POST /api/v1/admin/tools/database/test-connection and also passes the SSRF check), then save once it succeeds.

Actions the Agent can call

Editing and Deleting Tools

Editing Custom Tools

1. Select the custom tool
2. Select Edit
3. Modify tool details, endpoint configuration, parameters, or response format
4. Test the tool
5. Save changes

Deleting Custom Tools

1. Select the custom tool
2. Select Delete
3. Review impact: Agents and workflows using this tool
4. Confirm deletion

Testing Tools

Running Tests

1. Select the tool
2. Select the Test button
3. Enter test parameters
4. Select Run Test

Test Result Examples

Tool: Web Search
Test Parameters:
  query: "artificial intelligence"
  max_results: 5

Status: Success
Response Time: 1.2 seconds
Results:
  - title: "Artificial Intelligence - Wikipedia"
    url: "https://en.wikipedia.org/wiki/Artificial_intelligence"
    snippet: "Artificial intelligence (AI) is intelligence..."

  - title: "What is AI? | IBM"
    url: "https://www.ibm.com/topics/artificial-intelligence"
    snippet: "Artificial intelligence leverages computers..."

Metadata:
  total_results: 5
  search_time: 0.8s
  api_calls: 1

Tool: CRM Lookup
Test Parameters:
  customer_id: "12345"

Status: Success
Response Time: 0.5 seconds
Response:
  {
    "customer_id": "12345",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-0123",
    "status": "active"
  }

Validation: Passed
  ✓ Response format matches schema
  ✓ All required fields present
  ✓ Data types correct

Credentials and Sharing

Credentials are stored server-side and injected at call time. Custom tools can be shared with other teams with Read-only or Read & Execute permission.

The tool API response's share_permission (null when not shared) and shared_with_count fields reflect the sharing state and the number of receiving teams.

Tool Status Management

Tools have two statuses: enabled and disabled:

Failure Handling

HTTP Tool Test Failures

Check the following:

• URL is correct
• TLS certificate is valid
• Authentication credentials are not expired
• Request body JSON format is correct
• Response path matches the actual response structure

Code Tool Test Failures

Check the following:

• Packages use pinned versions (package==version)
• Standard output does not exceed 256KB cap
• Disk usage does not exceed 1024MB cap
• Execution does not exceed timeout (default 30 seconds)
• Artifact paths are under /workspace

Best Practices

Tool Configuration

✅ Do:

• Test tools before enabling
• Rotate credentials regularly
• Document tool purposes
• Keep tools updated
• Use error handling

❌ Don't:

• Enable untested tools
• Use static credentials forever
• Skip documentation
• Ignore errors

Security

✅ Do:

• Use secure authentication
• Rotate API keys regularly
• Restrict tool access
• Enable audit logging
• Monitor for abuse
• Use HTTPS only
• Validate responses

❌ Don't:

• Use weak authentication
• Use static API keys forever
• Allow unrestricted access
• Disable audit logs
• Ignore suspicious activity
• Allow HTTP connections
• Trust responses blindly

Performance

✅ Do:

• Set appropriate timeouts
• Use caching where possible
• Monitor response times
• Optimize tool calls
• Handle errors gracefully

❌ Don't:

• Use very long timeouts
• Skip caching
• Ignore performance metrics
• Make unnecessary calls
• Ignore errors

API Endpoints

The Tools API supports full CRUD operations, primarily for user-side tool management. See Tools API for details.

Admin Endpoints

Admin endpoints live under /api/v1/admin/tools and require admin:capability:* permissions:

# List tools (admin)
tools = api.get("/api/v1/admin/tools", params={"page": 1, "page_size": 20})

# Get filter options
filters = api.get("/api/v1/admin/tools/filters")

# Test a tool (builtin, custom, or MCP)
result = api.post("/api/v1/admin/tools/test", json={
    "tool_name": "web_search",
    "arguments": {"query": "artificial intelligence", "max_results": 5}
})

# Execute code directly
code_result = api.post("/api/v1/admin/tools/execute-code", json={
    "language": "python",
    "code": "return params['a'] + params['b']",
    "params": {"a": 1, "b": 2}
})

Permissions

All endpoints require an authenticated JWT user session:

Custom Tool Naming Conventions & Chat Status Visibility

When an Agent calls tools during reasoning, the top Chain of Thought header automatically surfaces the action without requiring users to expand the collapsible panel. Follow these naming conventions to ensure intuitive status display:

1. Recommended Verb Prefixes

2. Display Name Tips

• Provide a friendly Display Name: If configured (e.g. Fetch Stock Quotes or Send Slack Notification), the CoT header directly uses this name for status rendering.
• Automatic Identifier Beautification: Raw identifiers like fetch_user_orders or syncCrmAccount are automatically converted to clean phrases (e.g. Querying Fetch User Orders...).
• Parallel Call Aggregation: When multiple tools execute simultaneously, the header aggregates them into Calling {N} tools in parallel... to preserve clean UI presentation.

Troubleshooting

Tool Call Failed

1. Check tool configuration: Verify credentials, endpoint URL, test connectivity
2. Check audit logs: Review audit log entries for the tool's team
3. Common errors:
   • Authentication failed: Invalid credentials
   • Timeout: Increase timeout or check endpoint
   • Invalid parameters: Check parameter format
4. Test tool: Use the test panel to review results

Slow Response

1. Use the tool test panel to measure response time
2. Optimize: increase timeout, reduce data transfer, optimize endpoint
3. Check external service status for outages

Related Documentation

• Built-in Tools — Enable time, math, web, file, and media system capabilities
• MCP Services — Connect MCP Servers via stdio, SSE, or HTTP
• Skills & Packages — Import reusable Skill packages and manage resources
• Tools API — Complete API endpoint reference