curl -X GET "https://api.danubeai.com/v1/tools/tool_abc123/describe" \
-H "danube-api-key: YOUR_API_KEY"
{
"tool_id": "tool_abc123",
"name": "Vercel - List Deployments",
"description": "List deployments for a project",
"service_id": "svc_vercel_001",
"method": "GET",
"parameters": {
"projectId": {
"name": "projectId",
"location": "query",
"description": "Project id or name",
"type": "string",
"required": true
},
"teamId": {
"name": "teamId",
"location": "query",
"description": "Team id for team-owned projects",
"type": "string",
"required": false
},
"limit": {
"name": "limit",
"location": "query",
"description": "Maximum deployments to return",
"type": "integer",
"required": false,
"default": 20,
"minimum": 1,
"maximum": 100
}
},
"required": ["projectId"],
"output": {
"200": {
"status_code": "200",
"description": "Deployments",
"content_type": "application/json",
"output_schema": {"type": "object"}
}
},
"tips": "Pass teamId for projects owned by a team.",
"deprecated": false,
"deprecation_message": null,
"readiness": "ready",
"configuration_url": null,
"defaults": {"teamId": "team_abc"},
"reliability": {
"window_days": 30,
"calls_7d": 12,
"calls_30d": 42,
"success_rate_30d": 0.952,
"p50_seconds": 0.61,
"p95_seconds": 1.4,
"last_success_at": "2026-09-11T14:02:11.412Z",
"last_failure_at": "2026-09-03T09:10:44.001Z",
"last_error_class": "upstream_4xx",
"last_error_type": "not_found",
"error_classes": {"upstream_4xx": 2},
"faults": {"upstream": 2},
"auth_failures_30d": 0,
"caller_failures_30d": 0,
"danube_failures_30d": 0,
"upstream_failures_30d": 2,
"distinct_callers_30d": 3,
"flagged": false,
"refreshed_at": "2026-09-12T08:00:00Z"
},
"usage": {
"window_days": 30,
"calls": 42,
"success_rate": 0.952,
"p50_seconds": 0.61,
"common_errors": [
{"message": "HTTP 404: project not found", "count": 2}
]
},
"examples": [
{
"parameters": {"projectId": "prj_123", "teamId": "team_abc"},
"executed_at": "2026-09-11T14:02:11.412Z"
}
]
}
Tools
Describe Tool
Schema, readiness, saved defaults, recent usage and your own working examples for one tool
GET
/
v1
/
tools
/
{tool_id}
/
describe
curl -X GET "https://api.danubeai.com/v1/tools/tool_abc123/describe" \
-H "danube-api-key: YOUR_API_KEY"
{
"tool_id": "tool_abc123",
"name": "Vercel - List Deployments",
"description": "List deployments for a project",
"service_id": "svc_vercel_001",
"method": "GET",
"parameters": {
"projectId": {
"name": "projectId",
"location": "query",
"description": "Project id or name",
"type": "string",
"required": true
},
"teamId": {
"name": "teamId",
"location": "query",
"description": "Team id for team-owned projects",
"type": "string",
"required": false
},
"limit": {
"name": "limit",
"location": "query",
"description": "Maximum deployments to return",
"type": "integer",
"required": false,
"default": 20,
"minimum": 1,
"maximum": 100
}
},
"required": ["projectId"],
"output": {
"200": {
"status_code": "200",
"description": "Deployments",
"content_type": "application/json",
"output_schema": {"type": "object"}
}
},
"tips": "Pass teamId for projects owned by a team.",
"deprecated": false,
"deprecation_message": null,
"readiness": "ready",
"configuration_url": null,
"defaults": {"teamId": "team_abc"},
"reliability": {
"window_days": 30,
"calls_7d": 12,
"calls_30d": 42,
"success_rate_30d": 0.952,
"p50_seconds": 0.61,
"p95_seconds": 1.4,
"last_success_at": "2026-09-11T14:02:11.412Z",
"last_failure_at": "2026-09-03T09:10:44.001Z",
"last_error_class": "upstream_4xx",
"last_error_type": "not_found",
"error_classes": {"upstream_4xx": 2},
"faults": {"upstream": 2},
"auth_failures_30d": 0,
"caller_failures_30d": 0,
"danube_failures_30d": 0,
"upstream_failures_30d": 2,
"distinct_callers_30d": 3,
"flagged": false,
"refreshed_at": "2026-09-12T08:00:00Z"
},
"usage": {
"window_days": 30,
"calls": 42,
"success_rate": 0.952,
"p50_seconds": 0.61,
"common_errors": [
{"message": "HTTP 404: project not found", "count": 2}
]
},
"examples": [
{
"parameters": {"projectId": "prj_123", "teamId": "team_abc"},
"executed_at": "2026-09-11T14:02:11.412Z"
}
]
}
Overview
Everything needed to call a tool well, in one read. The response combines the tool’s parameter schema (required flags, enums, bounds), its declared output, publisher tips, whether you can run it right now, the parameter defaults saved for you, its 30-day reliability, usage across all callers, and your own last successful parameter sets. Nothing is executed. Read it before calling a tool you have not used successfully before. Each section is assembled independently: when one lookup fails, that field isnull or empty and the rest is still returned.
Auth: Optional. With an API key (danube-api-key header) or a JWT, readiness, defaults and examples are computed for your account. Without auth, readiness is the anonymous view, defaults is empty and examples is empty.
Path Parameters
string
required
The tool UUID or slug. Unknown ids return 404.
Response
string
Tool UUID
string
Tool name
string
Tool description
string
Parent service UUID
string
HTTP method the tool uses upstream
object
Keyed by parameter name. Each entry has
name, location, description, type and required, plus default, enum, minimum, maximum, encode_slashes and json_schema when set. json_schema carries the upstream JSON Schema for a nested object, an array of objects or a union, so you can fill it without guessing its keys.array
Names of the required parameters
object
Declared responses keyed by status code. Each entry has
status_code, description, content_type and output_schema.string
Publisher tips, or
nullboolean
Whether the tool is deprecated
string
Why it was deprecated, or
nullstring
ready, needs_credential or unavailable for this caller. null when the lookup failed.string
Where to connect the service. Set only when
readiness is needs_credential.object
The saved parameter defaults that apply to you on this tool, already merged in precedence order. See Set Parameter Defaults. Empty without auth.
object
The same 30-day block search results carry, or
null when the tool has not been called in the window. Keys: window_days, calls_7d, calls_30d, success_rate_30d (null below 10 calls), p50_seconds, p95_seconds, last_success_at, last_failure_at, last_error_class, last_error_type, error_classes, faults, auth_failures_30d, caller_failures_30d, danube_failures_30d, upstream_failures_30d, distinct_callers_30d, flagged, refreshed_at. Only upstream failures move success_rate_30d.object
The last 30 days across all callers, from the 500 most recent executions:
window_days, calls, success_rate, p50_seconds (median over successful calls) and common_errors, up to five entries of message and count, the message cut to 120 characters. null when the lookup failed.array
Up to three of your own most recent successful calls, newest first, each with
parameters and executed_at. Stored parameters were passed through secret redaction when written. Empty without auth.Example
The Python and TypeScript SDKs do not wrap this endpoint yet.curl -X GET "https://api.danubeai.com/v1/tools/tool_abc123/describe" \
-H "danube-api-key: YOUR_API_KEY"
{
"tool_id": "tool_abc123",
"name": "Vercel - List Deployments",
"description": "List deployments for a project",
"service_id": "svc_vercel_001",
"method": "GET",
"parameters": {
"projectId": {
"name": "projectId",
"location": "query",
"description": "Project id or name",
"type": "string",
"required": true
},
"teamId": {
"name": "teamId",
"location": "query",
"description": "Team id for team-owned projects",
"type": "string",
"required": false
},
"limit": {
"name": "limit",
"location": "query",
"description": "Maximum deployments to return",
"type": "integer",
"required": false,
"default": 20,
"minimum": 1,
"maximum": 100
}
},
"required": ["projectId"],
"output": {
"200": {
"status_code": "200",
"description": "Deployments",
"content_type": "application/json",
"output_schema": {"type": "object"}
}
},
"tips": "Pass teamId for projects owned by a team.",
"deprecated": false,
"deprecation_message": null,
"readiness": "ready",
"configuration_url": null,
"defaults": {"teamId": "team_abc"},
"reliability": {
"window_days": 30,
"calls_7d": 12,
"calls_30d": 42,
"success_rate_30d": 0.952,
"p50_seconds": 0.61,
"p95_seconds": 1.4,
"last_success_at": "2026-09-11T14:02:11.412Z",
"last_failure_at": "2026-09-03T09:10:44.001Z",
"last_error_class": "upstream_4xx",
"last_error_type": "not_found",
"error_classes": {"upstream_4xx": 2},
"faults": {"upstream": 2},
"auth_failures_30d": 0,
"caller_failures_30d": 0,
"danube_failures_30d": 0,
"upstream_failures_30d": 2,
"distinct_callers_30d": 3,
"flagged": false,
"refreshed_at": "2026-09-12T08:00:00Z"
},
"usage": {
"window_days": 30,
"calls": 42,
"success_rate": 0.952,
"p50_seconds": 0.61,
"common_errors": [
{"message": "HTTP 404: project not found", "count": 2}
]
},
"examples": [
{
"parameters": {"projectId": "prj_123", "teamId": "team_abc"},
"executed_at": "2026-09-11T14:02:11.412Z"
}
]
}
MCP Tool
This endpoint is also available as thedescribe_tool MCP tool:
result = await mcp.call_tool("describe_tool", {
"tool_id": "tool_abc123"
})