Danube

Danube

AI 智慧體v8.1.51
作者:Danube更新於 2026-10-31共 63 個版本 · 最新版本釋出於 2026-10-31danube@clawhub_preston-thiele/danube
工具呼叫#mcp#tool-access#agent-tools#api#governance

據 AlphaMoat 統計,截至 2026-10,Danube 累計下載 6,451 次、獲 2 個星標,按累計下載量在本次參與排名的 10,914 個 AI 技能中排名第 4,423 位,在「AI 智慧體」分類(1,632 個)中排名第 595 位。

列表預設按累計下載量排序,也可按星標排序;詳情頁排名按累計下載量計算。

累計下載
6451
星標
2
全站下載量排名
#4,423
全站前 41% · 「AI 智慧體」前 37%
平台累計下載星標評論
ClawHub ↗64512-
SkillHub ↗41852—

各平台的計數口徑不同,統計時間不一致。

這個技能是做什麼的

該技能支援發現工具、檢視引數並透過 MCP 或 REST 執行操作。讀取和檢索可直接進行;寫入、傳送、刪除、消費支出及批次執行前,應展示具體工具和引數並取得明確同意。

資料釋出於 2026-10-29

可以用來做什麼

  • 適合需要透過受治理連線訪問組織工具或服務目錄的開發者和代理操作者。

什麼時候用

  • 使用受限 API 金鑰和組織策略,只傳遞任務所需的憑據與資料;執行會改變狀態或產生費用的操作前取得明確確認。

示例提示詞

以下是根據技能文件生成的示例,不代表實際執行結果。

請查詢只讀工具並檢查引數;如果後續操作會寫入、傳送、刪除或產生費用,請先列出工具和引數等待我確認。

月度資料趨勢

累計下載6451
2484461567452026-03 · 累計下載 27782026-05 · 累計下載 34072026-06 · 累計下載 35602026-07 · 累計下載 38772026-08 · 累計下載 41662026-09 · 累計下載 50202026-10 · 累計下載 645126-0326-0926-10
星標2
1232026-03 · 星標 22026-05 · 星標 22026-06 · 星標 22026-07 · 星標 22026-08 · 星標 22026-09 · 星標 22026-10 · 星標 226-0326-0926-10

2026-09 起統計方法調整:同名技能按作者分別統計,並覆蓋全部技能。圖中虛線為調整前的月份,與之後的資料不直接比較,也不計算跨越調整的增長。

月份累計下載環比星標
2026-106451—2
2026-095020—2
2026-084166+7.5%2
2026-073877+8.9%2
2026-063560+4.5%2
2026-053407—2
2026-032778—2

SKILL.md 原文

以下是作者釋出的原始檔案,按純文字顯示,本站未做修改或稽核;其中的連結不可點選,命令請核實後再執行。抓取於 2026-10-23。

164 KB · ClawHub v8.1.43
---
name: danube
description: Governed tool access for your agent — one Danube API key unlocks your organization's own tools plus a large, growing catalog of ready-made services. Search, inspect, and execute tools over native MCP or plain curl, with explicit confirmation before anything that writes, sends, spends, or deletes.
metadata:
  openclaw:
    emoji: "🌊"
    homepage: https://docs.danubeai.com/sdk/openclaw
    requires:
      env:
        - DANUBE_API_KEY
展開全部(共 450 行)
      bins:
        - curl
    primaryEnv: DANUBE_API_KEY
    envVars:
      - name: DANUBE_API_KEY
        required: true
        description: Danube API key from https://danubeai.com/dashboard/api-keys (API Keys in the dashboard sidebar; an opaque token — no fixed prefix)
    always: false
---

# Danube — Governed Tool Access for Agents

Danube makes an organization's own tools — plus a large and growing catalog of ready-made services — callable by AI agents through a single API key, with permissions, spending limits, and an audit trail handled by the platform. The catalog changes constantly and includes tools the user's organization connected privately, so **never assume what is available — search first.**

## Guardrails (read these first)

- **Read freely, act with consent.** Discovery — listing services, searching tools, reading schemas, checking ratings, balances, or limits — needs no confirmation. Before any action that **writes, sends, posts, deletes, purchases, spends wallet funds, stores a credential, changes spending limits, or creates/updates/deletes a skill or workflow** — and before **any batch execution** — show the user the exact tool and parameters and get an explicit "yes".
- **Honour the confirmation handshake.** If `execute_tool` comes back with `_meta.confirmation_required: true`, that call will not run until someone consents: show the user the tool and the `parameters` from the response, get an explicit yes, then call again with the `confirm_token` (valid 5 minutes). Never call again with the token without asking. **Re-send your own original parameters, not the ones the response displayed** — those are passed through the redactor first, so a credential-shaped value comes back as `[REDACTED:…]`, while the token is signed over what you actually sent; echoing the masked form back invalidates it.
- **Two separate things raise that handshake, and only one of them is a setting on the key.** Either the account's key carries `require_confirmation`, *or* the tool itself demands consent from every caller whatever the key says — so a handshake can arrive on a key that has the setting switched off, and is not evidence that someone switched it on. The tool-side trigger covers two cases. A tool row marked `metadata.require_confirmation` always needs the token, and that is every **write** tool of the catalog's infrastructure connectors — thirteen of them, across eight of the seventeen services: `PostgreSQL - Execute Statement`, `MySQL - Execute Statement`, `ClickHouse - Execute Statement`, `Redis - Set`, `Redis - Delete`, `Redis - Expire`, `Apache Kafka - Produce Message`, `Kubernetes - Restart Rollout`, `Kubernetes - Scale Deployment`, `AWS DynamoDB - Put Item`, `AWS DynamoDB - Update Item`, `AWS DynamoDB - Delete Item` and `AWS Lambda - Invoke`. Every one of them says a confirmation is required in its own published description, so you can see it coming before you call (seven word it as "every call needs an explicit confirmation"; the rest say "with a confirmation on every call" or just "with a confirmation"). An organization's own connected-system copy of the same connector carries the flag too, and the only thing that lifts it there is an admin setting that system's policy to `writes: "allowed"` — a key carrying `require_confirmation` would still ask. The second case is narrower than it sounds: a write through a connected system's generic `<Service> - Request` tool when the service's access policy sets `http.writes: "consent"`. It is the HTTP surface only — a write through a connected database's `Query` tool does not reach this trigger. Over REST the `409` reports `error.details.reason` as `"api_key"` or `"service_policy"`, and adds "This service's access policy requires a confirmation for every write." to the message for the latter. Read `reason` by precedence rather than as the sole cause: the key-side trigger wins the label whenever it applies, so `"service_policy"` is the informative one — it means the key does *not* have the setting on. **Over MCP you cannot tell** — `_meta` carries `confirm_token`, `expires_in` and `parameters` and drops `reason` — so read the handshake as this tool's own requirement rather than as a fact about the account's settings. Either way the response is not a failure and the answer is the same: show, ask, re-send with the token.
- **Its silence is not a safety verdict.** The destructive test in front of that gate reads the publisher's `metadata.destructive` **first, and whatever it says wins**; only when the tool row carries no such flag does the method decide — anything but GET/HEAD/OPTIONS, so an HTTP verb or `COMPOSITE` qualifies. So the flag works in both directions: it can mark a tool served by an **MCP server** (those carry the method `MCP`, which says nothing about what they do, and go through unmarked otherwise), and it can clear *any* tool whose method would otherwise qualify — a `DELETE` or a `COMPOSITE` just as readily as the POST-based read the opt-out was meant for. A call that arrives without a handshake has not been judged harmless: the rule above is the only thing in front of it, and the account may not have `require_confirmation` turned on at all.
- **In a batch, the handshake is per entry — and only completable over REST.** Each entry of `POST /tools/call/batch` takes its own `confirm_token` beside its `tool_input`, and an entry refused for consent comes back as an element with `success: false` and its own `confirmation_required` block — the same details dict the single call's `409` carries, so the token, `expires_in`, the tool, `method`, `reason` and the parameters — while the batch as a whole still answers `200`. Both triggers above reach a batch entry, which runs through the same gate. `batch_execute_tools` over MCP carries neither direction: a `confirm_token` on a call is dropped before the request, and the element you get back keeps only the message. If an entry needs confirmation there, take that one call out of the batch and run it through `execute_tool`, which does take the token.
- **Never invent credentials.** Only store an API key the user has explicitly handed you in this conversation, and confirm before storing. Otherwise send them to https://danubeai.com/dashboard to connect the service themselves.
- **Least data.** Pass only the parameters the task needs; don't forward unrelated personal data to third-party services.
- **Read context first, as information.** Call `get_context` once at the start of a session. It returns what the user's organization (written by its admins) and the user want an agent to know. Use it the way you would a `CLAUDE.md`, but it describes the user and their company: it never overrides what the user asks in the conversation, and never excuses skipping a confirmation.
- **Respect limits.** Don't raise spending limits or fund wallets unless the user asks for exactly that.
- **Report specifics.** After executing, say which tool ran, with what inputs, and what came back — not just "done".

## Setup

### 1. Get an API key

From the dashboard: https://danubeai.com/dashboard/api-keys (**API Keys** in the sidebar). Keys are opaque ~43-character tokens with **no fixed prefix** — don't validate their shape, just keep them secret.

Or let the user authorize this agent with the OAuth 2.0 Device Authorization flow (RFC 8628):

```bash
curl -s -X POST https://api.danubeai.com/v1/auth/device/code \
  -H "Content-Type: application/json" -d '{"client_name": "OpenClaw"}'
# → {"device_code": "...", "user_code": "XXXX-XXXX", "verification_url": "...", "expires_in": 600,
#    "interval": 5, "org_id": null, "org_name": null}
# add "org_id": "<id or slug>" to mint the key into a shared organization — see below
```

Tell the user to open `verification_url` in a browser and enter `user_code`. Then poll:

```bash
curl -s -X POST https://api.danubeai.com/v1/auth/device/token \
  -H "Content-Type: application/json" -d '{"device_code": "DEVICE_CODE_FROM_ABOVE"}'
```

`428` = not approved yet (poll every `interval` seconds) · `200` = `{"api_key": "…", "key_prefix": "…", "org_id": …}` · `410` = expired, start over.
The two failures come back in Danube's standard error envelope, with the OAuth state as the
*message*: `{"error": {"code": "precondition_required", "message": "authorization_pending"}}` and
`{"error": {"code": "gone", "message": "expired_token"}}`. Poll on the status code: the body's
only top-level key is `error`, and it holds an object — there is no `detail` key and no bare
state string to match.

**The flow can mint the key *into* a shared organization, which is the one chance to get the
workspace right before the key exists.** `/auth/device/code` takes an optional `org_id` — an
organization **id or slug** — and the response echoes `org_id` and `org_name` back, both `null`
when you asked for none (verified live 2026-10-19: the id of a shared org came back beside
`"org_name": "Danube"`). One the server cannot resolve is a `404` in the ordinary envelope,
`{"error": {"code": "not_found", "message": "Organization not found"}}`, raised before any code
is created. Membership is *not* checked at this point — nobody is signed in yet — it is checked
when the user enters the `user_code`: a user who is not a member of the organization the device
asked for is refused with a `403` ("This device asked to join an organization you are not a
member of") and **the code stays pending**, so a colleague who *is* a member can still authorize
that same code. From your side an organization nobody present belongs to therefore looks like
`428` until the code expires, rather than an error. A *personal* organization is accepted here
too — it is not rejected, it simply gives you the default described next — so passing one buys
nothing.

What it buys is the thing the *Tools the user's organization registered* section below is about:
the minted key is stamped with that organization, and an org-owned key acts for it **with no
`danube-org-id` header at all**. Ask for it only when the user named a shared organization to
work in, and don't pass their personal one thinking it is the neutral choice — you don't need to.
With no `org_id` the key is stamped with the user's personal organization, and that is *not* the
narrowing the header version of it would be: only a **shared** org switches the request's
context, so a personal-org key keeps the ordinary personal behaviour and still spans every
organization the user belongs to.

**Respect `interval`, and know that a fourth status can appear.** The code is good for
`expires_in` seconds (600, i.e. ten minutes) and the two endpoints carry rate limits of their
own: 10 requests/minute on `/auth/device/code` and 30/minute on `/auth/device/token`. These
calls are unauthenticated, so there is no key to count them against — the bucket is keyed by
the client address *as the server sees it*, which behind a hosted deployment's edge may be far
more widely shared than your own machine or egress. Treat the 30/minute as a limit you could
meet even when nothing is wrong. At the advertised `interval` of 5 seconds you poll 12 times a
minute, which is the rate the flow is designed around; poll tighter and you are spending someone
else's headroom as well as your own.

The resulting `429` is **not** one of the three statuses above, so don't read it as a failed
authorization — it says nothing about whether the user has approved. Back off by `Retry-After`
(see *The two `429`s* below) and carry on polling **the same `device_code`**: a rate-limited
poll never reaches the handler, and an ordinary pending one changes nothing, so the code stays
valid for the rest of its ten minutes. Starting a fresh flow instead spends one of the
10/minute on the other endpoint and makes the user enter a new `user_code`.

### 2. Make the key available to OpenClaw

Set `DANUBE_API_KEY` in the environment, or in `openclaw.json`:

```json5
{ skills: { entries: { danube: { apiKey: "YOUR_DANUBE_API_KEY" } } } }
```

### 3a. Connect natively over MCP (recommended)

OpenClaw has a built-in MCP client. Register Danube's server once and its tools become ordinary OpenClaw tools (`search_tools`, `execute_tool`, …):

```bash
openclaw mcp set danube '{"url":"https://mcp.danubeai.com/mcp","transport":"streamable-http","headers":{"danube-api-key":"YOUR_DANUBE_API_KEY"}}'
openclaw mcp doctor danube --probe
```

Use the real key value in `headers` (not `${DANUBE_API_KEY}`). The server also speaks MCP OAuth: use `"auth":"oauth"` instead of `headers`, then `openclaw mcp login danube`.

**Signing in now means a Danube account, not a pasted key — and the refresh token has a trap
worth knowing before you automate around it.** Until 2026-10-04 `/oauth/authorize` asked the user
to paste an API key and handed it straight back as a one-year token. It now validates the request
and redirects the browser to Danube's own consent page, where the user signs in and approves the
client (verified live 2026-10-05: a well-formed authorize request answers `302` to
`https://danubeai.com/oauth/consent?request=…`). What that changes for you:

- **PKCE is mandatory** — `code_challenge_method=S256`, no exceptions; without it the endpoint
  answers `400 invalid_request` before anything else. Registration is open, so an unknown
  `client_id` is still accepted. The metadata at
  `https://mcp.danubeai.com/.well-known/oauth-authorization-server` is authoritative for the four
  endpoints and advertises `authorization_code` and `refresh_token`.
- **The `scope` you ask for is a label, and the consent screen never shows it.** The metadata
  advertises five (`tools:read`, `tools:execute`, `services:read`, `skills:read`,
  `context:read`), but nothing validates the parameter against them: live on 2026-10-07 an
  authorize request carrying `scope=not_a_real_scope admin:everything` answered the same `302`
  to the consent page as one carrying no `scope` at all — there is no `invalid_scope` path. The
  consent screen shows the client's self-asserted name, the redirect host and the workspace
  picker, and no list of permissions, so what the user approves is *who* and *which workspace*,
  never *what*. Past consent the string is dropped rather than narrowed: the approval does not
  carry it to the grant, every connection is created with the full default set, and the token
  response echoes that set back however little you asked for. Nothing enforces it downstream
  either — the access token resolves to the connection's hidden key, which is injected as an
  ordinary `danube-api-key` carrying no permissions — so all 33 MCP tools stay callable. Like
  `?tools=` below, read it as a declaration, not a permission boundary: asking for less is not a
  way to narrow a connection. What does narrow one is a key you issue yourself with
  `allowed_services` / `allowed_tools` set on it, used in place of an OAuth connection; an
  organization can also deny tools for anything acting in its workspace, which reaches a
  connection approved for that organization.
- **The user picks a workspace on the consent screen, and the two choices are not symmetrical.**
  Approving for a **shared organization** binds the connection to it: the grant's hidden key
  carries that org, every backend call is made for it without the client sending anything, and
  the organization's internal tools, shared credentials, parameter defaults, skills and context
  layer are what the connection sees. Approving for **"Personal"** does *not* do the mirror
  image — it does **not** narrow the connection to personal-only. The personal org is
  deliberately never forwarded as the acting workspace (it would select the Personal workspace
  and hide every shared org), so such a connection behaves like an ordinary personal API key
  with no workspace header: it still spans every organization the user belongs to. So read
  "Personal" at consent as "don't pin this to one organization", not as "keep this out of my
  organizations". A user who wants the second thing cannot get it by narrowing this connection:
  the key behind a connected app is created with no permissions, is never shown, and the
  Connected apps page only lists and revokes. The way to hand an agent a restricted credential
  is still a pasted API key with `allowed_services` / `allowed_tools` set on it in the
  dashboard, used instead of an OAuth connection.
- **Tokens are short-lived and rotate.** The access token (`dmcp_at_…`) lasts one hour; the
  refresh token (`dmcp_rt_…`) is spent on every use and replaced, with a 90-day idle expiry.
  **Re-presenting a refresh token you have already exchanged revokes the whole connection** —
  the user has to approve the client again. There is a 30-second grace for the genuine race (a
  rotation whose response you lost, two refreshes in flight at once), which answers
  `invalid_grant` "Refresh token was already used" and leaves the grant alive; past that window
  the same replay is read as theft and the connection is revoked. So store only the newest pair
  and never retry a refresh with a token you kept "just in case". Both outcomes are
  `invalid_grant`, so the error alone will not tell you which one you just caused.
- **Read the `401` before deciding what to do**, because three different things answer `401` and
  only one of them is fixed by refreshing. A `WWW-Authenticate` carrying `error="invalid_token"`
  is the access token expired or revoked — refresh it. Without that marker the message is the
  tell: "API key required…" means no credential reached the server at all, and "Invalid API key"
  means one did and was rejected (a revoked or mistyped key). Neither of those two is a token
  problem, so refreshing or re-running sign-in will not clear them.
- **Revoking** is `POST /oauth/revoke` (RFC 7009), or the user's **Connected apps** page at
  https://danubeai.com/dashboard/connected-apps; removing someone from an organization revokes
  their connections too. A revoked token can keep working for up to a minute — the server caches
  an introspection for 60 seconds — so don't read one more successful call as the revoke having
  failed.
- **Pasted keys were not deprecated by any of this.** A bearer token without the `dmcp_at_`
  prefix is still treated as an API key, so the `headers` form above and every connection made
  before 2026-10-04 keep working unchanged.

**The key header has an alias on this server, and carrying it over to `curl` fails quietly.** The
MCP server reads the key from either `danube-api-key: <key>` or `Authorization: Bearer <key>`, and
the `401` it sends when neither is present names both. The REST API accepts only the first, and
what the second does there depends on the route (both verified live 2026-10-03): a route that
*requires* a key refuses it — `/v1/tools/search` answered
`401 {"error":{"code":"unauthorized","message":"API key required"}}`, a message that reads as "you
sent no key" when the key was simply in the header REST reserves for a dashboard JWT — while a
route whose auth is *optional* ignores it without saying so: `/v1/services?limit=3` answered `200`
with byte-for-byte the response the same call returns carrying no credentials at all, so whatever
the key would have unlocked is silently missing. Keep `curl` on `danube-api-key`. Hand-probing the
MCP endpoint has two more traps worth knowing before you read a failure as a bad key — POST is the
only verb that does anything, and an unauthenticated request never reaches routing — both in
`{baseDir}/references/troubleshooting.md`.

To keep the tool list small, append `?tools=core` to the URL, or a comma list such as
`?tools=core,workflows`; without it all 33 tools are described to the model. The six groups are
`core` (11 — `get_context`, discovery, execution, credentials, and `report_tool`), `workflows` (6),
`wallet` (6), `skills` (5), `feedback` (4 — `submit_rating`, `get_my_rating`, `get_tool_ratings`,
`get_recommendations`) and `context` (1 — `update_context`). `core` is added to whatever you ask
for, so search, execute and `get_context` can't be filtered out by accident (`?tools=wallet` lists 17). Unrecognised names are dropped silently: a
typo alongside a valid group just gives you fewer tools than you asked for (`?tools=core,workfows`
lists the same 11 as `?tools=core`), and if *none* of the names is a real group the parameter is
ignored altogether and you get the full 33. Either way it fails quietly, never with an error.
**Capitalisation and stray spaces are not among the ways to get it wrong**, though, so don't let
that silence make you over-careful with the spelling: each name is lower-cased and stripped
before it is matched, so `?tools=CORE` is `?tools=core` and `?tools=%20Core%20,%20Workflows%20`
is `?tools=core,workflows`. All of this verified live on 2026-10-23 against
`https://mcp.danubeai.com/mcp`, counting the `tools/list` reply: no parameter 33, `?tools=core`
11, `?tools=CORE` 11, that spaced and capitalised pair 17, and `?tools=workfows` on its own 33.

**The filter narrows `tools/list` and nothing else.** `tools/call` is deliberately not filtered, so
a connection opened with `?tools=core` can still run a tool from a group it never listed, as long
as it knows the name — live on 2026-09-23, `get_tool_ratings` and `get_spending_limits` both
returned normally over a `?tools=core` connection whose `tools/list` held ten tools (eleven since `get_context` joined `core`). That is
convenient (no reconnecting to rate a tool you just ran) and worth not misreading in the other
direction: the parameter is a context-size setting, not a permission boundary. Nothing on the
connection restricts which of the 33 tools may be called. A key's own `allowed_services` /
`allowed_tools` permissions, set in the dashboard, are a different control and don't close that
gap either — they scope which *marketplace* services and tools the key may search and execute, not
which of Danube's own MCP tools it may use.

**Every one of the 33 tools carries MCP annotations, and they describe the Danube verb rather
than the tool it carries.** Each entry of `tools/list` comes with the standard
`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint` quartet, so an OpenClaw
client that gates on them has something to read before it calls. Read them as a statement about
the Danube tool you are calling, not about the marketplace tool it runs — which is the whole
trap, because the two most consequential tools are the ones whose hint can't know:
`execute_tool` and `batch_execute_tools` are both stamped `destructiveHint: true` with
`openWorldHint: true` **always**, whether the call behind them sends an email or lists your
Gmail labels. So a client prompting on `destructiveHint` prompts on every catalogue call
including pure reads, and a `destructiveHint: true` there is not evidence the tool being run
writes anything. The marketplace tool's own flag is a different field entirely — the
publisher's `metadata.destructive`, which drives the platform's `confirm_token` gate described
above.

The `readOnlyHint: true` direction is the dependable one: the 16 tools carrying it are exactly
the discovery and inspection calls this skill says need no confirmation — `list_services`,
`search_tools`, `get_service_tools`, `describe_tool`, `fetch_result`, `get_context`,
`get_wallet_balance`, `get_spending_limits`, `get_agent_info`, `list_workflows`,
`get_workflow_execution`, `search_skills`, `get_skill`, `get_my_rating`, `get_tool_ratings` and
`get_recommendations`. **Nine** tools carry
`destructiveHint: true` (`execute_tool`, `batch_execute_tools`, `store_credential`,
`execute_workflow`, `fund_agent_wallet`, `update_skill`, `delete_skill`, `update_workflow`,
`delete_workflow`), and four carry `openWorldHint: true` (`execute_tool`,
`batch_execute_tools`, `execute_workflow`, `fund_agent_wallet`).

**Don't read the hints as this skill's consent list, though — eight tools that change something
are not flagged destructive.** `update_spending_limits`, `create_skill`, `create_workflow`,
`update_context`, `register_agent`, `set_parameter_defaults`, `submit_rating` and `report_tool`
all come through with `readOnlyHint: false` **and** `destructiveHint: false`, and three of them
— changing spending limits, creating a skill, creating a workflow — are things the guardrails
at the top of this file tell you to confirm. The hints are a coarse client-side signal; the
ask-first rule above is the one that decides.

### 3b. Or use plain `curl` — no MCP needed

Every capability below is also a REST call against `https://api.danubeai.com/v1` with the header `danube-api-key: $DANUBE_API_KEY`. Copy-paste recipes: `{baseDir}/references/rest-api.md`.

## Working with tools

Every task follows **Explore → Inspect → (Confirm) → Execute → Report.**

| Goal | MCP tool | REST |
|---|---|---|
| See what services exist | `list_services(query, limit, detail?)` — a `limit` over **25** silently drops to the compact form | `GET /services` |
| Find a tool for a task | `search_tools(query, service_id?, limit?, detail?)` | `GET /tools/search?query=…` |
| All tools of one service | `get_service_tools(service_id, limit?, detail?)` — `limit` defaults to **50** | `GET /services/{id}/tools` (no limit; returns every tool) |
| Full schema of one tool | `describe_tool(tool_id)` (the listings above summarise) | `GET /tools/{tool_id}/describe` (prefer it to the bare `GET /tools/{tool_id}` — see below) |
| Run a tool | `execute_tool(tool_id, parameters, fields?)` | `POST /tools/call/{tool_id}` with `{"tool_input": {…}}` — the wrapper is optional for the parameters and required for `fields` / `confirm_token` / `timeout_seconds`, see below |
| Run up to 10 at once | `batch_execute_tools(calls)` | `POST /tools/call/batch` |
| Inspect one tool before first use | `describe_tool(tool_id)` | `GET /tools/{tool_id}/describe` |
| Read a stored result back | `fetch_result(execution_id, path?, max_response_chars?)` | `GET /tools/executions/{execution_id}/result?path=…&max_chars=…` |
| Remember a per-service default | `set_parameter_defaults(service_id, defaults, tool_id?)` | `PUT /services/{service_id}/parameter-defaults` |

**`execute_tool` resolves a name by *searching*, so an identifier that names nothing runs the
nearest tool instead.** Over MCP the call takes `tool_name` as an alternative to `tool_id` — and a
`tool_id` that is not a valid UUID is not refused either, it is quietly re-read as a name. Both
land in the same place: the string goes through a five-result `search_tools`, an exact `name` match
wins, and **when nothing matches exactly the first result is executed**. The `match` signal
described under *Discovery tips* is not consulted on this path.

An identifier that really exists is safe, and for the reason given under *when you already know a
tool's exact name* below: the search pins a tool whose name or slug **is** the query to the top,
ignoring case and punctuation, ahead of every readiness and reliability re-ordering. So a
correctly spelled name or slug runs the tool you named — verified live on 2026-10-09, where the
slugs `hacker-news-get-top-stories-with-content` and `hacker-news-search-by-date` each ran their
own tool. What is not safe is an identifier you guessed, half-remembered or mistyped. Live the same
day, `tool_name: "Hacker News - Get Front Page Story Titles"` — a name no tool carries — ran
`Hacker News - Get New Stories With Content` and returned the *newest* stories as an ordinary
success, with nothing in `result` saying a different tool had run. And the nearest neighbour need
not be anything like what you asked for: a search for `"zzqq blorptacular frobnicate wibblesnorf"`
came back with three `match: "weak"` tools led by `DigitalOcean Droplets - Image Create` — which
is what a name that garbled would have resolved to. The call itself would then have failed as a
`bad_request` or stopped at the confirmation gate, since that tool is a write with three required
parameters, but where it resolved to is the point.

So pass the UUID whenever you have one, and when you pass a name you did not just read off a
search result, check `_meta.tool_id` and `_meta.tool_name` — which name the tool that actually
ran — before you believe the payload. One nuance if you call the same name twice: only an exact
`name` hit is remembered (five minutes, per key and acting organization), so a best guess is
re-searched every time and can land somewhere else as the catalogue shifts.

**No execution path other than that one resolves a name.** Over REST, and for each entry of
`batch_execute_tools`, the identifier goes to the backend, which matches a UUID on `id` and
anything else on `slug` **exactly** — so a slug is a precise lookup there, and a tool's display
name is simply a miss. Live on 2026-10-09 one batch carried both spellings of the same tool:
`"hacker-news-get-top-stories-with-content"` answered `success: true`, while
`"Hacker News - Get Top Stories With Content"`, the row's real name, answered `success: false`
with `error: "Tool not found"`. A batch entry's parameters belong in `tool_input`; **over MCP**
`parameters` and `params` are accepted as aliases for it, as `params` is for `execute_tool`'s
`parameters`, but REST reads neither on a batch entry — send `tool_input` there or the tool runs
on empty input.

**On a *single* REST call the `tool_input` wrapper is optional for the parameters and required
for `fields`, `confirm_token` and `timeout_seconds` — the second half is the one worth
remembering.**
`POST /v1/tools/call/{tool_id}` reads the whole body as the tool's input when the body carries
no `tool_input` key (`body.get("tool_input", body)`, `routers/tools.py`), so `{"limit": 2}` and
`{"tool_input": {"limit": 2}}` run the same call — both verified live 2026-10-22 on
`Hacker News - Get Top Stories With Content`, each answering with two stories and
`request_params: {"limit": 2}`. What the bare shape loses is the controls that ride *beside*
`tool_input`: `fields`, `confirm_token` and `timeout_seconds` are each read only when the body
has a `tool_input` key, so without the wrapper they are taken for tool parameters and dropped as
undeclared, with no error saying so. Live the same day, `{"limit": 2, "fields":
["[].title"]}` came back `200` with `projection: null`, the full story objects, and `fields`
echoed back inside `request_params`, while `{"tool_input": {"limit": 2}, "fields":
["[].title"]}` returned the two titles alone with `projection: {"fields": […], "missing": []}`.
(`max_response_chars` is the exception — it is read in either shape.) The one that bites is
`confirm_token`, since a token sent without the wrapper never reaches the consent check and the
call answers `409` again, which reads as a token that does not work. It is worse than one wasted
round trip: the token is signed over a hash of the tool input (`hash_args(tool_input)`,
`services/consent.py`), and bare the token is *part* of that input, so every retry hashes
differently and is answered with a fresh token — a loop rather than a refusal. So always send
`tool_input`: it is the only shape every recipe in this file holds for.

**And don't carry MCP's `parameters` over to REST — it is read as a parameter of that name.**
That alias is MCP's — and even over REST a *batch* entry does not take it either, per the
paragraph above — so on this route the wrapper becomes an undeclared parameter and your values
never arrive. On a tool whose
parameters are all optional that is a silent wrong answer: live 2026-10-22,
`{"parameters": {"limit": 2}}` on that same tool answered `200` with **ten** stories and
`request_params: {"parameters": {"limit": 2}, "limit": 10}` — the wrapper kept as a parameter
the row does not declare (so dropped before the upstream request) and the schema's own default
filling in the `limit` that never got there. On a tool with a required parameter it fails
instead, and the message names what you did send rather than what you meant:
`error_type: "missing_parameters"`, "Missing required parameters: q. Provided parameters:
parameters." (live, `HealthData.gov - Autocomplete Dataset Names`). Read either one as the body
shape, never as a value you forgot.

**`GET /v1/tools/{tool_id}` works again — `/describe` is still what to read before executing,
and the collection route beside it is still unusable.** Until 2026-09-24 the per-tool route
answered `422`,
demanding a query parameter `r` that had no valid value, because its auth dependency was written
as `Depends(lambda r: …)` and FastAPI read that lambda's unannotated `r` as a required *query*
parameter. That is fixed: both routes now depend on the real dependency, and the per-tool route
returns the tool row normally — verified live on 2026-09-24, `200` with the full object both
plain and with a leftover `?r=1`. If you are talking to a backend deployed before that date you
may still meet the `422`; there is nothing to report or retry either way, just use `/describe`.

**This file dates a handful of behaviours that way, so here is the one check that tells you which
side of a date you are on — and what it can't tell you.** `GET https://api.danubeai.com/health`
needs no key and reports `started_at`, the boot time of the REST backend process. Since a process
can't be running code that didn't exist when it booted, `uptime_seconds` is a floor on the age of
the code answering you, with no ceiling: a restart reboots the image it already had, so a recent
`started_at` proves nothing. The one direction that reads: a `started_at` *earlier* than the date
on one of these notes makes the pre-fix behaviour the likely one — likely, not certain, since
those dates are when a fix was verified rather than when it shipped. **It dates the REST backend
only.** `api.danubeai.com` and `mcp.danubeai.com` are separate deployments, and the MCP server
publishes no build or boot time at all, so the notes below marked as MCP-layer changes can't be
dated from outside. Neither version number the MCP server does report helps —
`{baseDir}/references/troubleshooting.md` explains what those two numbers actually are.

**Still read `GET /v1/tools/{tool_id}/describe` before a first call — but the two are not
nested, so know what each one drops.** `/describe` is what adds the things you actually need
before executing: `required`, the tool's recent `usage`, your own `examples`, saved `defaults`,
and *populated* `readiness`, `configuration_url` and `reliability`. The bare route declares
those last three and returns them `null` — it runs no enrichment — so it cannot answer "can I
call this now". What the bare route carries and `/describe` leaves out is the plumbing:
`base_url`, `path`, `slug`, `tags`, `version`, `metadata`, `security_schemes` and
**`sunset_date`**. That last one matters, because this file tells you to read `deprecated`
together with `sunset_date` and `/describe` has only the first two of that trio. Both take a
slug as readily as a UUID (verified live: `…/tools/gmail-send-email` and
`…/tools/gmail-send-email/describe` both `200`). One caution on the bare row: its pricing
fields are unenriched defaults, so `is_paid` reads `false` and `price_per_call_cents` `null`
even on a priced tool — read a price off a search result, never off this route.

**`GET /v1/tools` (the whole collection) is the one route in this file not to call even once.**
It takes no pagination parameters at all and returns every tool row the caller may see — the
catalogue held 12,583 rows on 2026-09-24 and 12,740 on 2026-10-23 — and you cannot get an answer
out of it: probed four times on the earlier date it answered `500` (after 9–12 s) or, once the
edge's ~31 s ceiling was reached, `504`. The `500` is not a mystery and it is not about your
call: the route is declared `-> List[Tool]` while the query behind it selects five columns
(`id, name, description, tags, service_id`), so every row fails response validation on four
required fields it does not carry (`base_url`, `path`, `method`, `version`). That is a bug in
Danube's own route — deterministic, not retryable, and not something a parameter changes.
**What makes it worth avoiding rather than merely useless is that the cost can land on everyone
else.** Live on 2026-10-23 one such call answered `504` after 31.3 s and the whole API was
unreachable for about three minutes: the next request, an ordinary `GET /v1/stats/public`, came
back as the hosting platform's `no_healthy_upstream` page, three `GET /health` calls in a row
answered `504`, and the `/health` that finally answered reported a process seconds old where one
23 hours old had been answering a few minutes earlier. No deploy explains that restart and
nothing was filed as an error — but whether the call caused it was not established, and it is
not a thing to reproduce in order to find out. Use `GET /v1/tools/search?query=…` for discovery,
or `GET /v1/services/{id}/tools` for one service's full list.

**Without a key those two routes answer `401`, not the body** — the collection and per-tool
routes are mounted with a key dependency, and a dependency that rejects you raises before
anything else runs (verified live 2026-09-24). Read a `401` there as being about your key.
`/describe` is *not* on that router and needs no key at all — it answered `200` unauthenticated
on 2026-09-24. Over MCP none of that key-and-`404` business applies, but only `describe_tool` carries the
full schema: since 2026-09-25 `search_tools` and `get_service_tools` answer with a compact
summary unless you ask for more (see *A listing is a summary now* below).

**You never have to call either of them to learn how big the catalogue is.** `GET
https://api.danubeai.com/v1/stats/public` needs no key, is rate-limited at 30/minute, and
answers in one cheap call: `{"services": 517, "tools": 12740, "workflows": 0,
"total_executions": 18856}` at 12:16 UTC on 2026-10-23 — the live figure behind the stale count
above. `services` has not moved since 2026-10-10, and in the four days from the previous reading
taken here (12,737 tools and 18,278 executions at 12:25 UTC on 2026-10-19) `tools` gained three
while the fourth number gained ~580, so expect the execution counter to differ from whatever is
written down. Don't read any such average as a rate, either — it arrives in bursts: two
readings eighteen minutes apart on 2026-10-14 differed by 13, and two about ninety seconds apart
on 2026-10-19 differed by 5. Read its first two numbers as different populations rather than a ratio: `services` counts the
**public** catalogue only, while `tools` counts every tool row that exists, the ones belonging
to private and organization-internal services included. The `workflows` beside them is the
public-workflow count, which is why it reads `0` rather than meaning the account has none.
**The body is cached for five minutes**, so it is not a freshness check: a service published or
a tool registered moments ago will not move these numbers yet, and calling again inside the
window returns the identical body rather than a new reading. `GET /health` carries the same
whole-catalogue population as `index.lexical_rows`, read off the running process's search index
rather than the database; the `index.tools` beside it counts the rows that carry an embedding
the index could use, so it is never the larger of the two and a gap is rows it had none for,
usually ones still waiting to be embedded, not a fault. The two therefore read **equal** once
every row carries a usable embedding, as they did on 2026-10-17 (12,736 each, on a process up
23 hours): no 

原文較長,這裡只顯示前 39 KB,完整內容請到來源頁面檢視。

「AI 智慧體」分類下的熱門技能

資料月份:2026-10 · 下載/星標數聚合自公開技能註冊庫(ClawHub、SkillHub),按月更新。口徑說明見資料方法。