MCP tools
Instead of one tool per API call, every endpoint offers five tools, so the AI searches for the right operation rather than reading hundreds of them. Only operations the signed-in user’s role may use are searched or callable.
overview
Section titled “overview”What the API is for, its main tool groups and your role. The AI calls this first. Read-only (readOnlyHint: true, destructiveHint: false, openWorldHint: false, like search_tools and ask_docs). No inputs.
search_tools
Section titled “search_tools”Finds the 3 to 5 operations that best match what you asked for, with their input schemas and call_with: the tool that runs each one (call_read_operation or call_write_operation). Only operations your role may use are searched. Read-only.
| Input | Type | |
|---|---|---|
query |
string, required | What you want to do, in plain words |
limit |
integer | 3-5, default 5 |
call_read_operation
Section titled “call_read_operation”Runs one read-only operation: a GET or HEAD, or one the product marked read-only in its tool settings. Nothing changes on the API. Paginated operations take a page or cursor and return next-page info.
Annotations: readOnlyHint: true, destructiveHint: false, openWorldHint: true.
| Input | Type | |
|---|---|---|
operation_id |
string, required | An id returned by search_tools whose call_with is call_read_operation |
arguments |
object | Arguments matching the operation’s schema |
page |
integer | Paginated operations: page number or offset from next_page |
cursor |
string | Paginated operations: cursor from next_cursor |
call_write_operation
Section titled “call_write_operation”Runs one operation that changes data (create, update, delete, send). Operations that need confirmation first return a confirm_token: the AI must ask you, and runs the operation only if you agree, calling again with the same arguments plus that token.
Annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: true.
| Input | Type | |
|---|---|---|
operation_id |
string, required | An id returned by search_tools whose call_with is call_write_operation |
arguments |
object | Arguments matching the operation’s schema |
confirm_token |
string | From the previous confirmation response; send only after the user explicitly agreed |
Calling the wrong one
Section titled “Calling the wrong one”Each tool refuses an operation of the other kind before anything reaches the API, with an error that names the right tool ("wrong_tool": true, "use_tool": "call_write_operation"). Call that tool with the same arguments. Every successful operation call costs 1 point, whichever tool ran it.
call_tool (deprecated)
Section titled “call_tool (deprecated)”Older clients and CLIs used one call_tool for everything. It still works and runs any operation, with the same confirmations, but it no longer appears in tools/list. Move to the two tools above; call_tool will be removed later.
ask_docs
Section titled “ask_docs”Answers questions about how the API works (fields, limits, auth, errors, pagination, concepts) with numbered verbatim passages from the product’s docs, each cited to its source. Read-only.
| Input | Type | |
|---|---|---|
question |
string, required | The question, in plain words |
limit |
integer | 1-8 passages, default 5 |
Named tools
Section titled “Named tools”A product may also publish a few named tools for common tasks, each backed by one operation. They appear only if your role may use that operation, and carry the same read-only or destructive annotations as the operation’s class.