Refresh Tools

POST /tools/refresh

Re-probe an imported server and report what moved, function by function (D-5524).

The third operation of a set whose first two are discover and import: those two connect a server, this one keeps it connected. Dry run by default: the answer is a report and apply is what writes, in the shape scripts/backfill-owners uses for the same reason, which is that the run that writes nothing is the one somebody reads.

Applying writes description and input_schema, which are the server’s by definition, and creates a row for a function that is newly offered. It never lets the server decide effect without apply_effect: the approval gate is default-deny (D-166), a hint from a partner is not an instruction to switch a gate off, and a row this operation creates is therefore created write and gated, with the server’s hint reported beside it. It never deletes: a row the server stopped offering is reported with the revisions that still name it, and deactivated only under deactivate_missing, while one that is off and offered again comes back only under reactivate_returning.

A catalogue that arrives in pages produces no disappeared at all. tools/list is paginated and the probe reads the first page, so complete: false on the report says the absences in it are not evidence, and nothing is deactivated on that run.

member, the same floor as import and PATCH /tools/{id}, because the same caller can already do all of this by hand through them. 422 when the prefix names no imported row, when its rows name two different servers, or when the server authenticates as the caller and no probe_credential stands in for the run.

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 — ToolRefreshRequest

Field	Type		Notes
prefix	string	required	—
apply	boolean	optional	Default false.
apply_effect	boolean	optional	Default false.
deactivate_missing	boolean	optional	Default false.
reactivate_returning	boolean	optional	Default false.
probe_credential	string | null	optional	min length 1 max length 100

Responses

Status	Description	Body
200	Successful Response	ToolRefreshReport
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/refresh \
  -H "Authorization: Bearer $COBRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "prefix": "string"
     }'

Response — ToolRefreshReport

Field	Type		Notes
prefix	string	required	—
source	string	required	—
applied	boolean	required	—
complete	boolean	optional	Default true.
items	ToolRefreshItem[]	optional	—
skipped	ToolRefreshSkip[]	optional	—
summary	object	optional	—
note	string	required	—