> ## Documentation Index
> Fetch the complete documentation index at: https://docs.danubeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Describe Tool

> Schema, readiness, saved defaults, recent usage and your own working examples for one tool

## 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 is `null` 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

<ParamField path="tool_id" type="string" required>
  The tool UUID or slug. Unknown ids return 404.
</ParamField>

## Response

<ResponseField name="tool_id" type="string">
  Tool UUID
</ResponseField>

<ResponseField name="name" type="string">
  Tool name
</ResponseField>

<ResponseField name="description" type="string">
  Tool description
</ResponseField>

<ResponseField name="service_id" type="string">
  Parent service UUID
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method the tool uses upstream
</ResponseField>

<ResponseField name="parameters" type="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.
</ResponseField>

<ResponseField name="required" type="array">
  Names of the required parameters
</ResponseField>

<ResponseField name="output" type="object">
  Declared responses keyed by status code. Each entry has `status_code`, `description`, `content_type` and `output_schema`.
</ResponseField>

<ResponseField name="tips" type="string">
  Publisher tips, or `null`
</ResponseField>

<ResponseField name="deprecated" type="boolean">
  Whether the tool is deprecated
</ResponseField>

<ResponseField name="deprecation_message" type="string">
  Why it was deprecated, or `null`
</ResponseField>

<ResponseField name="readiness" type="string">
  `ready`, `needs_credential` or `unavailable` for this caller. `null` when the lookup failed.
</ResponseField>

<ResponseField name="configuration_url" type="string">
  Where to connect the service. Set only when `readiness` is `needs_credential`.
</ResponseField>

<ResponseField name="defaults" type="object">
  The saved parameter defaults that apply to you on this tool, already merged in precedence order. See [Set Parameter Defaults](/api-reference/endpoint/set_parameter_defaults). Empty without auth.
</ResponseField>

<ResponseField name="reliability" type="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`.
</ResponseField>

<ResponseField name="usage" type="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.
</ResponseField>

<ResponseField name="examples" type="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.
</ResponseField>

## Example

The Python and TypeScript SDKs do not wrap this endpoint yet.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.danubeai.com/v1/tools/tool_abc123/describe" \
    -H "danube-api-key: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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"
      }
    ]
  }
  ```
</ResponseExample>

## MCP Tool

This endpoint is also available as the `describe_tool` MCP tool:

```python theme={null}
result = await mcp.call_tool("describe_tool", {
    "tool_id": "tool_abc123"
})
```