Building Blocks

create_code_tool

Create a code tool from Python source_code: exactly one public function (the entrypoint) plus any _-prefixed helpers. A parse error is returned as an error. tags attaches tag names to the new tool.

How the tool is described to the model — write a normal docstring. Everything the model sees comes out of the entrypoint’s docstring (the module docstring is used when the function has none):

• its first paragraph becomes the tool description, and the paragraphs after it are kept as the tool’s usage notes;

• an Args: section describes the parameters — write one line per parameter or the model is left guessing what to pass;

• parameter types come from the annotations, never from prose.

  def run(upload_url: str, mime: str, source_file: bytes) -> dict: """PUT a file’s bytes to a presigned upload URL.

    Args:
        upload_url: The presigned uploadUrl from `create_upload_url`.
        mime: Content-Type to send — the mimeType `create_upload_url`
            returned.
        source_file: file_id of the file whose bytes to PUT.
    """

Alternatively, keep the description on the parameter itself with typing.Annotated: def run(upload_url: Annotated[str, "The presigned uploadUrl"]). An Annotated description wins over Args:.

A YAML manifest: block inside the docstring is a legacy form. It is still read as a last-resort fallback for parameters nothing else describes, but it is deprecated — do not write new ones.

File parameters: Annotate a parameter as bytes to accept file_id UUID strings. The platform downloads the file content from S3 before invoking the tool, so the function receives raw bytes. Example: def run(data: bytes) -> dict: — callers pass {"data": "<file_id>"}.

Parameter	Type	Required	Description
env_vars	string[]	no
name	string	yes
org	string	no
source_code	string	yes
tags	string[]	no

create_prompt

Create a prompt template. text may contain {{variable}} placeholders and is optional when fields alone defines a pure extraction schema.

fields is an optional list of field defs, each {name, field_type, …}; valid field_type: text, date, datetime, yes_no, whole_number, money, choice, object (choice needs a choices list). Any field can also set is_list: true to extract multiple values of that type instead of one. object fields nest a sub-schema under fields (a list of field defs, same shape, recursively) to extract a structured record; combine field_type: "object" with is_list: true to extract a list of records. When fields is set, the prompt runs as structured extraction instead of free-text generation — run_prompt/test_prompt return typed data, and text (if given) becomes the extraction instructions. post_processing_instructions (optional) runs a second refinement call over the extracted data.

reasoning_effort sets the LLM reasoning level (e.g. "low", "medium", "high"). tags attaches tag names to the new template.

Parameter	Type	Required	Description
description	string	no
fields	object[]	no
model	string	no
name	string	yes
org	string	no
post_processing_instructions	string	no
reasoning_effort	string	no
tags	string[]	no
text	string	no

create_skill

Create a skill (a bundle of instructions + a tool subset + reference material). Created immediately active. description is a one-line summary kept in-context for agents that mount it. tags attaches tag names to the new skill.

Every entry in tool_slugs must resolve in this org — call list_org_tools (or list_code_tools) for the valid slugs.

Parameter	Type	Required	Description
description	string	no
instructions	string	yes
name	string	yes
org	string	no
reference_material	string	no
tags	string[]	no
tool_slugs	string[]	no

get_code_tool

Get a code tool (by id or exact name), including its source code.

Parameter	Type	Required	Description
org	string	no
tool	string	yes

get_knowledge_base

Get a knowledge base (by id or slug), including its embedding model.

Parameter	Type	Required	Description
knowledge_base	string	yes
org	string	no

get_prompt

Get a prompt template (by id or slug), including its active text.

Parameter	Type	Required	Description
org	string	no
prompt	string	yes

get_skill

Get a skill (by id or slug), including its active instructions and tools.

Parameter	Type	Required	Description
org	string	no
skill	string	yes

list_code_tools

List the org’s code tools (custom Python tools).

Parameter	Type	Required	Description
org	string	no

list_knowledge_bases

List the org’s knowledge bases, with source/chunk counts.

Parameter	Type	Required	Description
org	string	no

list_prompts

List the org’s prompt templates.

Paged: the response carries total, has_more and next_offset — pass next_offset back as offset to walk the rest.

Parameter	Type	Required	Description
limit	integer	no	Max rows to return (1–200).
offset	integer	no	Rows to skip — pass the previous response’s next_offset.
org	string	no

list_skills

List the org’s skills.

Paged: the response carries total, has_more and next_offset — pass next_offset back as offset to walk the rest.

Parameter	Type	Required	Description
limit	integer	no	Max rows to return (1–200).
offset	integer	no	Rows to skip — pass the previous response’s next_offset.
org	string	no

search_knowledge_base

Search the org’s knowledge bases for relevant content chunks.

This is the same retrieval the in-chat search_knowledge agent tool uses: it matches both meaning and exact wording, so a single distinctive term works as well as a full question. Pass knowledge_base (an id or slug from list_knowledge_bases) to restrict the search to one base; omit it to search all of them.

Parameter	Type	Required	Description
knowledge_base	string	no
limit	integer	no	Max hits (1–25).
org	string	no
query	string	yes

update_code_tool

Update a code tool (by id or exact name). Only the fields you pass are changed. tags replaces the tool’s current tag set (pass an empty list to clear all tags).

A new source_code re-derives everything the model sees the same way create_code_tool does: the entrypoint’s docstring (module docstring as a fallback) — first paragraph as the tool description, an Args: section for the parameters — and the annotations for the parameter types. A parameter can instead carry its own description via Annotated[str, "..."], which wins over Args:. A YAML manifest: block in the docstring is a deprecated legacy form; when you touch a tool that has one, move its parameter prose into an Args: section.

File parameters: Annotate a parameter as bytes to accept file_id UUID strings. The platform downloads the file content from S3 before invoking the tool, so the function receives raw bytes. Example: def run(data: bytes) -> dict: — callers pass {"data": "<file_id>"}.

Parameter	Type	Required	Description
env_vars	string[]	no
is_enabled	boolean	no
name	string	no
org	string	no
source_code	string	no
tags	string[]	no
tool	string	yes

update_prompt

Update a prompt template (by id or slug). Passing text, fields, or post_processing_instructions creates a new revision (versioned together). Only the fields you pass are changed. fields (see create_prompt for the shape) turns the prompt into — or updates — structured extraction; valid field_type: text, date, datetime, yes_no, whole_number, money, choice, object. Any field can set is_list: true to extract multiple values; object fields nest a sub-schema under fields for a structured record, and object + is_list: true extracts a list of records. reasoning_effort sets the LLM reasoning level. tags replaces the template’s current tag set (pass an empty list to clear all tags).

Parameter	Type	Required	Description
description	string	no
fields	object[]	no
model	string	no
name	string	no
org	string	no
post_processing_instructions	string	no
prompt	string	yes
reasoning_effort	string	no
tags	string[]	no
text	string	no

update_skill

Update a skill (by id or slug) and deploy the change so it takes effect (skills are live immediately, like on create). Only the fields you pass are changed. tags replaces the skill’s current tag set (pass an empty list to clear all tags).

Every entry in tool_slugs must resolve in this org — call list_org_tools (or list_code_tools) for the valid slugs.

Parameter	Type	Required	Description
description	string	no
instructions	string	no
name	string	no
org	string	no
reference_material	string	no
skill	string	yes
tags	string[]	no
tool_slugs	string[]	no