Validate a tool definition

POST

https://api.v2.rasen.ai/v1/agents/:agent_id/tools/validate

POST

/v1/agents/:agent_id/tools/validate

curl -X POST https://api.v2.rasen.ai/v1/agents/agent_id/tools/validate \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "kind": "webhook",
  "definition": {
    "url": "https://api.example.com/orders/{order_id}",
    "method": "GET",
    "headers": [
      {
        "name": "Authorization",
        "value_type": "secret",
        "credential": {
          "secret_id": "sec_01j00000000000000000000000",
          "version": 2
        }
      }
    ],
    "parameters": [
      {
        "name": "order_id",
        "location": "path",
        "source": "model",
        "schema": {
          "type": "string",
          "description": "Order ID said by the caller."
        },
        "required": true
      }
    ]
  },
  "description": "Look up an order by its ID.",
  "name": "lookup_order",
  "retry_posture": "none",
  "side_effect": "none"
}'

{
  "valid": true,
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "Assign an outbound number to this agent."
    }
  ],
  "warnings": [
    {
      "field": "example",
      "code": "example",
      "message": "Assign an outbound number to this agent."
    }
  ],
  "readiness": {
    "state": "ready",
    "reasons": [
      {
        "code": "example",
        "message": "Assign an outbound number to this agent."
      }
    ]
  }
}

Schema/reference validation only. No remote webhook, discovery or tool execution; a valid result is not an end-to-end tool test. Reserved names end_call, transfer and transfer_to_number are refused with invalid_request on every write/validation; use default_tools. Inline credential material also requires secrets.manage, because it creates a secret; a {secret_id, version} reference also requires secrets.read.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Path parameters

agent_idstringRequired1-128 characters

Resource identity within the authenticated workspace.

Request

This endpoint expects an object.

webhookobjectRequired

Unattended execution only. Automatic retry of an idempotent webhook requires name and placement and an idempotent downstream contract; no automatic retry of unknown non-idempotent effects. Unknown side effect forbids automatic retry.

mcpobjectRequired

Response headers

X-Request-IdstringOptional

Safe server request correlation ID.

RateLimit-LimitintegerOptional

Requests allowed in the current window for the tightest applicable limit.

RateLimit-RemainingintegerOptional

Requests left in the current window.

RateLimit-ResetintegerOptional

Seconds until the current window resets.

Response

Validate a tool definition.

validboolean

errorslist of objects

warningslist of objects

readinessobject

A snapshot, not a reservation. Admission rechecks current readiness. Publication, model support, knowledge and phone routing are separate prerequisites. Reasons can include credential_unavailable when the live version has tools that pin a revoked credential version.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

413

Content Too Large Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error