Creating API Tools

Overview

An API tool lets an agent call an HTTP endpoint, such as a CRM, a booking system, a weather service, or an internal service with a REST API. When the agent needs live data or needs to take an action, it calls the tool, and Cosmos sends the request and returns the response to the agent.

Use an API tool when the system you want to reach exposes an HTTP endpoint. If your data is in a database, use a Database tool. To use a prebuilt integration, see Custom tools.

Prerequisites

• A Cosmos account with permission to create tools. If Create New is not available on the Tools page, ask your organization admin.
• The URL, HTTP method, and any authentication details for the API you want to call.

Step-by-Step

Step 1: Open Tools

In the sidebar, under Build & Enhance, click Tools. The Tools Integration page lists every tool you can access, with search and filters.

Step 2: Choose API Tool

Click Create New. In the What type of tool would you like to create? dialog, choose API Tool. The Create New API Tool wizard opens with two steps: Tool Details and Preview.

Step 3: Fill in the API profile

Under API Profile:

Under Request Configuration:

💡 The description is the most important field. The agent reads it to decide when to call the tool, so describe the inputs it expects and the data it returns.

Step 4: Add parameters and headers

Use the Params and Header tabs to define what the request sends.

• Params — the inputs the agent fills in when it calls the tool. Click Add New for each parameter and give it a name, type, and description.
• Header — static headers sent with every request, such as Content-Type: application/json or an API key header.

You can build the schema with the Form Builder or paste a JSON Schema in the JSON Editor:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The city name to look up"
    },
    "units": {
      "type": "string",
      "description": "Temperature units: metric or imperial"
    }
  },
  "required": ["city"]
}

Authentication

Add credentials as headers, in the form the external API expects:

If your organization has connectors configured, you can also attach one under Connector Attachments with Add Connector, choosing the Service, Provider, and Capability.

Step 5: Preview and save

The Preview step shows the complete configuration and the status Ready to save draft. Review it and click Save. The tool is saved as a Draft and is not yet available to agents.

Step 6: Test the tool

On the tool's detail page, click Test. The Test Tool dialog shows Input Parameters generated from your schema. Enter sample values, run the test, and check the Response.

If the test fails, check that the server URL is reachable, required headers and credentials are set, and the inputs match what the API expects.

Step 7: Deploy the tool

Click Deploy on the detail page and confirm. The tool status changes from Draft to Deployed, and the tool appears in the API tab when you attach tools to an agent.

The tool detail page also has History (earlier versions), Edit, and Delete. Editing a deployed tool creates a new draft that you deploy again when it is ready.

Verify

1. On the Tools Integration page, confirm the tool shows as Deployed.
2. Attach the tool to an agent in the agent's Skills & tools step. See Building & Testing Agents.
3. Test the agent with a question that should trigger the tool, such as "What's the weather in Berlin?", and check Tool Calls in the session overview.

Tips & Best Practices

• Write clear descriptions. Vague descriptions lead to missed or wrong tool calls.
• Keep the input schema small. Only include parameters the agent must supply. Put fixed values in headers or the URL.
• Use meaningful names. get_weather_forecast is clearer to the agent than tool1.
• Test before deploying. Run at least one successful test with realistic inputs.
• Protect credentials. Prefer scoped, short-lived keys, and rotate them regularly.

Next Steps

• Creating Database Tools
• Creating Custom Tools
• Building & Testing Agents
• Tools API Reference