Platform API error

unknown_tool

unknown_tool is the 404 from POST /api/platform/v1/tools/:name when the tool name is not in the registry or is not offered to platform clients.

Updated November 6, 2026

HTTP status: 404
Code: unknown_tool
API: Platform API v1

Returned when

POST /api/platform/v1/tools/:name with a name that is not in the registry, or a tool that is not offered to platform clients.

What to do

GET /api/platform/v1/tools lists every tool and its input schema. Tool names are lowercase with underscores, prefixed by the website (senatus_, wuuuh_, helpbless_ …).

Example answer

HTTP/1.1 404
content-type: application/json

{
  "error": {
    "code": "unknown_tool",
    "message": "There is no tool named <name>."
  }
}

Related errors

world_tools_unavailable World tools act on one member's own data and are not open to platform keys yet.
invalid_arguments The tool's arguments do not match its input schema.

What it means

unknown_tool is an error code returned with HTTP status 404. It means there is no tool by the name you sent, or the tool exists in the registry but is not offered to platform clients.

Every error response uses the same shape: an error object with code, message and hint. The code is the stable part; match on it. The message may read There is no tool named <name>. or That tool is not available to platform clients.

A 404 here is not about a missing route or a malformed request body. The endpoint POST /api/platform/v1/tools/:name exists. The tool name in the path is what failed to resolve.

Why you are seeing it

Most often the name is misspelled, cased wrong, or missing its website prefix. Tool names are lowercase with underscores and prefixed by the website, for example senatus_, wuuuh_ or helpbless_. Sending Senatus_Search, senatus-search or plain search will not match.

The other case is a tool that is not offered to platform clients. A name can be valid in the registry and still be absent from the platform surface. The message tells the two apart: no tool named <name>, or not available to platform clients.

How to fix it

Call GET /api/platform/v1/tools. It lists every tool and its input schema. Find the exact name there, copy it character for character, and send it to POST /api/platform/v1/tools/:name. Check the prefix against the website you are integrating.

If the name is not in that list, the tool is not offered to platform clients, so choose a listed tool that does the job. Do not retry a 404 with the same name; the result will not change.

If the name is listed but the call still fails, compare your request body with the input schema for that tool. Argument problems come back as invalid_arguments. The related code world_tools_unavailable covers a different failure, so branch on the code rather than assuming every failure is a naming problem.

Handling it in code

Branch on error.code, never on error.message. The codes are stable and the messages are not. On unknown_tool, send the integration to discovery rather than into a retry loop: fetch the tool list, resolve the name, then call the tool endpoint again.

Log the requested name, the hint field from the error body, and enough context to see where the name came from. Surface the hint to the developer running the integration instead of retrying silently. Because the failure is deterministic, backoff and repeated attempts only add load.

If your code builds tool names from configuration or user input, validate them against GET /api/platform/v1/tools at startup and reject unknown names before the first call. Keep the resolved list cached and refresh it when a call returns unknown_tool, since that is the signal your local copy is stale or wrong.

Questions

What HTTP status does unknown_tool return?

404. The response body carries an error object with code, message and hint, and the code value is unknown_tool.

How do I list the tool names the platform accepts?

Send GET /api/platform/v1/tools. The response lists every tool and its input schema, including the exact lowercase, underscore-separated, website-prefixed names.

Should I retry after an unknown_tool error?

No. The name does not resolve, so repeating the same request returns the same 404. Fetch GET /api/platform/v1/tools, correct the name or pick a listed tool, then call POST /api/platform/v1/tools/:name again.

Keys, plans and usage live in the console: rotate keys, add webhook endpoints, see the last 30 days.

Open the console Plans

Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.