Skip to main content
The platform_tools field on the Assistants API attaches platform (prebuilt) tools by name in the same request that creates or updates an assistant — no per-tool assign calls, no id discovery. It is accepted on POST /v3/assistants and PATCH /v3/assistants/{id}. Successful POST /v3/assistants responses and GET /v3/assistants/{id} return it.

​
Declarative semantics

platform_tools is a declarative list scoped to the platform catalog:
  • Omitted — attachments are not touched at all.
  • Provided — the assistant’s platform-tool attachments are made to match the list exactly: names in the list are attached, catalog tools missing from the list are detached.
  • [] — explicitly detaches every platform tool.
Custom tools are never touched by this field, in either direction. They keep their own lifecycle via POST /v3/tools/{id}/assign and DELETE /v3/tools/{id}/assign, and the full attachment view (platform and custom) remains GET /v3/assistants/{id}/tools. Input order is irrelevant and duplicates are ignored; reads return names sorted alphabetically. Names resolve strictly inside the platform catalog — a custom tool that happens to reuse a catalog name can never be matched by this field.

​
The catalog

call_user, end_call, and press_key are not attachable through this field. call_user remains visible in the tools list and attachable via POST /v3/tools/{id}/assign; call-control tools are managed by the platform. Validation reports every offending name in a single 400 response, distinguishing unknown names from deliberately excluded ones.

​
Booking calendar scope

get_availability and book_appointment use the assistant’s assigned booking calendar. The current calendar picker has one active assignment per assistant. Attaching these tools does not automatically select among several calendars or authorize access to other client accounts. Standard booking does not require a BuildShip account or a separately hosted custom endpoint. See Calendar Booking and Multi-Calendar Routing for native setup, agency client accounts, and the custom workflow needed when one assistant must choose among several calendars.

​
Example

A subsequent GET /v3/assistants/{id} returns:

​
Notes

  • Tool changes made through this field propagate to the voice runtime via the assistant’s automatic re-publish, same as every other assistant edit.
  • Custom-tool assignment via the assign endpoint reaches live voice calls on the assistant’s next publish — a pre-existing behavior documented here for completeness.