Agent Internal Tools API

These endpoints cover the static catalog (GET …/tools/catalog), permission listing (GET …/tools), and permission upsert (PUT …/tools) for tools owned by internal providers such as operations.

v2 (current): Permission state (which tools are enabled) is served by GET /ai/agents/:agentId/tools. Use PUT /ai/agents/:agentId/tools with the { tools: [{toolName, permissionStatus, providerKey}] } body to configure permissions. The legacy { enabledTools: string[] } body shape is rejected with 400.

All paths are under the /ai prefix.

Note: Connection-based tools (Gmail, Sheets, Calendar, Telegram, SMTP) are not managed here. They use a dedicated per-connection-instance grant system. See Agent Connection Tools API.

Authentication

These endpoints require:

• A valid Authorization: Bearer <jwt> token
• A valid x-org-id header (or the orgId embedded in the JWT)
• A CASL policy that allows read/update on the ai.agent subject

The JWT's agencyId claim must match the agent's owning agencyId. Mismatches return 403 Forbidden.

---

GET /ai/agents/:agentId/tools/catalog

Returns the static tool catalog for the operations provider.

Note: The enabledTools field has been removed from this response. Permission state (which tools are enabled per agent) is now served exclusively by GET /ai/agents/:agentId/tools.

Path Parameters

Parameter	Type	Description
agentId	UUID v7	The AI agent's identifier

Response — 200 OK

{
  "providerKey": "operations",
  "tools": [
    { "name": "list_tasks",     "description": "List tasks by status within the organization." },
    { "name": "create_task",    "description": "Create a new task." },
    { "name": "update_task",    "description": "Update an existing task." },
    { "name": "list_projects",  "description": "List projects within the organization." },
    { "name": "create_project", "description": "Create a new project." },
    { "name": "update_project", "description": "Update an existing project." },
    { "name": "list_events",    "description": "List calendar events." },
    { "name": "create_event",   "description": "Create a new calendar event." },
    { "name": "update_event",   "description": "Update an existing calendar event." }
  ]
}

Response fields:

• providerKey — the tool provider identifier ("operations" for internal tools)
• tools — the full static catalog of 9 tool descriptors. The inputSchema (Zod object) is intentionally excluded — it is not JSON-serializable and is only needed at inference time.

Errors

Status	Code	When
401	—	Missing or invalid JWT
403	—	Caller's agencyId does not match agent's agencyId

Example

curl -X GET \
  "https://api.daramex.app/ai/agents/01927f3e-0000-7000-8000-000000000001/tools/catalog" \
  -H "Authorization: Bearer <jwt>" \
  -H "x-org-id: 01927f3e-0000-7000-8000-000000000002"

---

GET /ai/agents/:agentId/tools

Returns every persisted (toolName, permissionStatus, providerKey) row for this agent (typically including operations tools once configured).

Path Parameters

Parameter	Type	Description
agentId	UUID v7	The AI agent's identifier

Response — 200 OK

{
  "tools": [
    {
      "toolName": "create_task",
      "permissionStatus": "always_allow",
      "providerKey": "operations"
    }
  ]
}

Field	Type	Description
permissionStatus	string	One of always_allow, needs_approval, blocked

Errors

Status	When
401	Missing or invalid JWT
403	Caller's agencyId does not match agent's agencyId

Example

curl -X GET \
  "https://api.daramex.app/ai/agents/01927f3e-0000-7000-8000-000000000001/tools" \
  -H "Authorization: Bearer <jwt>" \
  -H "x-org-id: 01927f3e-0000-7000-8000-000000000002"

---

PUT /ai/agents/:agentId/tools

Replaces the tool permission configuration for the agent. Send the complete desired tools array (same as other upsert-style endpoints in this module). The legacy { "enabledTools": string[] } body is rejected with 400.

Path Parameters

Parameter	Type	Description
agentId	UUID v7	The AI agent's identifier

Request Body

{
  "tools": [
    {
      "toolName": "create_task",
      "permissionStatus": "always_allow",
      "providerKey": "operations"
    },
    {
      "toolName": "list_tasks",
      "permissionStatus": "needs_approval",
      "providerKey": "operations"
    }
  ]
}

Field	Type	Constraints	Description
tools	array	max 128 items	Each item identifies a tool and its permission level
toolName	string	min length 1	Tool name from the catalog (e.g. create_task)
permissionStatus	string	enum	always_allow, needs_approval, or blocked
providerKey	string	min length 1	operations for internal tools

Response — 200 OK

{
  "agentId": "01927f3e-0000-7000-8000-000000000001",
  "toolCount": 2
}

Errors

Status	When
400	Invalid body (including legacy enabledTools shape)
401	Missing or invalid JWT
403	Caller's agencyId does not match agent's agencyId

Example

curl -X PUT \
  "https://api.daramex.app/ai/agents/01927f3e-0000-7000-8000-000000000001/tools" \
  -H "Authorization: Bearer <jwt>" \
  -H "x-org-id: 01927f3e-0000-7000-8000-000000000002" \
  -H "Content-Type: application/json" \
  -d '{"tools":[{"toolName":"create_task","permissionStatus":"always_allow","providerKey":"operations"}]}'

For approve-always user overrides and MCP-specific routes, see Agent Tool Overrides & Permissions API (linked from the module sidebar).