Coding agents are good at reading and writing code. But most real tasks require context that lives outside the repo—internal APIs, documentation systems, project trackers, databases, deployment pipelines.

You can now pass custom HTTP tools to CodeCloud agents. Define an endpoint, describe what it does, and the agent calls it when relevant. Up to 50 tools per run.

How it works

Add a tools array to your API request. Each tool has a name, description, parameters, and an HTTP endpoint. The agent sees these as native tools and can call them during execution.

curl -X POST https://codecloud.dev/api/v1/agents \
  -H "Authorization: Bearer cc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your-org/your-repo",
    "prompt": "Find open bugs tagged backend and fix them",
    "tools": [
      {
        "name": "search_issues",
        "description": "Search for issues in the project tracker",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Search query"
            },
            "status": {
              "type": "string",
              "enum": ["open", "closed", "in_progress"],
              "description": "Filter by issue status"
            },
            "labels": {
              "type": "string",
              "description": "Comma-separated label filter"
            }
          },
          "required": ["query"]
        },
        "endpoint": {
          "url": "https://internal.yourcompany.com/api/issues/search",
          "method": "GET",
          "headers": {
            "Authorization": "Bearer your-internal-token"
          }
        }
      }
    ]
  }'

The agent decides when to use each tool based on the description you provide. Good descriptions matter—tell the agent what the tool returns and when to use it.

Tool definition

Each tool has four parts:

name – Alphanumeric with underscores or hyphens, up to 64 characters
description – What the tool does. The agent reads this to decide when to call it
parameters – JSON Schema-style object defining the inputs. Supports strings, numbers, booleans, enums, and arrays
endpoint – The URL, HTTP method (GET, POST, PUT, PATCH, DELETE), and optional headers

For GET and DELETE requests, parameters are sent as query strings. For POST, PUT, and PATCH, they're sent as a JSON body.

Authentication

Tools often need authentication. Pass tokens, API keys, or any custom headers in the endpoint's headers field. These are included in every request the agent makes to that tool.

"endpoint": {
  "url": "https://api.yourcompany.com/docs/search",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer eyJhbGciOi...",
    "X-Org-Id": "org_abc123"
  }
}

This works with any auth scheme—Bearer tokens, API keys, basic auth, custom headers. The headers are injected into every call to that specific tool.

Give the agent context on your organization

This is where tools get interesting. The agent already understands your code by reading the repo. Tools let you give it context on everything else.

Some ideas:

Internal documentation – Connect your wiki or docs API so the agent can look up architecture decisions, coding standards, or team conventions
Issue trackers – Let the agent search Linear, Jira, or your custom tracker for related tickets, past bugs, or context on what was tried before
Deployment status – Give the agent access to your deployment API so it can check what's in production, what's staged, and what recently changed
Feature flags – Let the agent query your feature flag system to understand which flags exist and how they're configured
Databases – Expose a read-only query endpoint so the agent can inspect schema, check data patterns, or verify migrations
Monitoring – Connect error tracking (Sentry, Datadog) so the agent can see recent errors and stack traces when debugging

The more context the agent has about your organization, the better its code will be. A tool that returns your team's API design guidelines will produce different (better) code than an agent working from just the repo.

Blank workspace mode

You can also run agents with tools but without a repo. Set blank_workspace: true and the agent starts in an empty environment with only your tools available. This is useful for non-code workflows: querying APIs, generating reports, data transformations, or anything that doesn't need a codebase.

{
  "blank_workspace": true,
  "prompt": "Get all open P0 bugs from the last week and summarize them",
  "tools": [
    {
      "name": "get_bugs",
      "description": "Fetch bugs from the issue tracker. Returns title, priority, assignee, and created date.",
      "parameters": {
        "type": "object",
        "properties": {
          "priority": {
            "type": "string",
            "enum": ["P0", "P1", "P2", "P3"],
            "description": "Bug priority level"
          },
          "since": {
            "type": "string",
            "description": "ISO date string, return bugs created after this date"
          }
        },
        "required": ["priority"]
      },
      "endpoint": {
        "url": "https://internal.yourcompany.com/api/bugs",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer your-token"
        }
      }
    }
  ]
}

Updating tools on follow-up messages

When you resume an agent run with a follow-up message, you can pass a new set of tools. The new tools override the previous set. This is useful when the agent needs different capabilities for different phases of a task.

POST /api/v1/agents/run/{id}/resume
{
  "prompt": "Now deploy the changes",
  "tools": [
    {
      "name": "trigger_deploy",
      "description": "Trigger a deployment to the staging environment",
      "parameters": {
        "type": "object",
        "properties": {
          "branch": {
            "type": "string",
            "description": "Branch to deploy"
          }
        },
        "required": ["branch"]
      },
      "endpoint": {
        "url": "https://deploy.yourcompany.com/api/deploy",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer deploy-token"
        }
      }
    }
  ]
}

Large responses

If a tool returns a large response (over 2,000 characters), the agent saves it to a temporary file and receives a summary of the structure—top-level keys, array lengths, and first-item fields. The agent then uses targeted reads to extract what it needs. This keeps the context window clean and prevents large payloads from drowning out the task.

Limits

Maximum 50 tools per run
Tool names: alphanumeric, underscores, hyphens, 1-64 characters
Description: up to 1,000 characters
Supported parameter types: string, number, boolean, enum, array
Supported HTTP methods: GET, POST, PUT, PATCH, DELETE

Tools turn the agent from a code-only assistant into something that understands your organization. Start with one or two tools—your docs API, your issue tracker—and see how much better the output gets when the agent has real context.

For full API details, see the documentation. Questions or feedback? Reach out at support@codecloud.dev.