Discover Tools

POST /tools/discover

Probe a tool-protocol server and report what it offers (annex 09 §2.2).

Nothing is persisted: this is the read half of connecting a server, and the rows are written by POST /tools/import. The probe passes the same SSRF validator a run does and resolves the same credentials in the caller’s scope, because an endpoint that contacts an arbitrary address without either is a port scanner behind a login.

422 naming config.endpoint when the server could not be reached, carrying whatever the socket or the server said about it. The kind degrades to a stub mid-run, which is correct there and refused here: a stub is a message for the model, not a tool to import.

Role floor

Requires member or above. The floor is a minimum, not a grant: scope filtering still applies on top of it, and a resource in another tenant answers 404 rather than 403.

Request body — ToolDiscoverRequest

Field	Type		Notes
config	object	required	—
secrets_required	string[]	optional	—

Responses

Status	Description	Body
200	Successful Response	ToolDiscovery
422	Validation Error	HTTPValidationError

Only the success paths are declared

Any operation may also answer any status in the error catalogue, and every failure body is the platform envelope — including the 422 this document types as HTTPValidationError.

Example

The body shows the fields the schema always carries. Which combination is legal is a service rule the schema cannot express, so read the description above before copying this.

curl -X POST https://your-deployment.example.com/tools/discover \
  -H "Authorization: Bearer $COBRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "config": {}
     }'

Response — ToolDiscovery

Field	Type		Notes
source	string	required	—
tools	DiscoveredToolView[]	optional	—