How tools work

Names

A tool is named for the REST call it makes: the HTTP method first, then the path with the leading /api dropped, lowercased, a {param} segment written by_<param>, and separators as _.

REST call	Tool
`GET /api/audit-logs/{id}`	`get_audit_logs_by_id`
`DELETE /api/orgs/{id}`	`delete_orgs_by_id`
`GET /webhooks/health`	`get_webhooks_health`

The method leads, so a read and a write on one path never share a name. A name depends only on the method and path, so it does not change when the spec is reordered.

Arguments

Path and query parameters are top-level arguments, named as in the REST reference. Numbers and booleans are converted, so a client may send them as strings.
A request body travels in one argument, body, a JSON object. The tool's description spells out its fields. The API validates it and answers with what was wrong if a field is.
There are no header arguments. The person's token is attached to the call for you.

Results

A call returns one text item holding the API's JSON response, pretty-printed.
A response with no body returns one line: METHOD /path succeeded.
A failure returns isError: true with the API's message as text — a 403 when the signed-in person holds no grant for the call, a 400 naming the field that was wrong.

Descriptions

Each tool's description begins with the REST call it makes, then the endpoint's own documentation. A tool that changes data ends with a note that the person confirms it first. Open What the model is shown at the foot of any tool page to see the description and input schema verbatim.

Annotations

Clients use annotations to decide which tools to ask about.

Tool	`readOnlyHint`	`destructiveHint`	`idempotentHint`	`openWorldHint`
Read (`GET`)	`true`	—	—	`false`
Change (`POST`, `PATCH`)	`false`	`true`	`false`	`false`
Change (`PUT`, `DELETE`)	`false`	`true`	`true`	`false`

They are hints. The confirmation behind every change is enforced by the server, not left to how a client reads them.