Tools

Functions for building workspace tools — the reusable capabilities you link to agents. There are four workspace tool types:

Type	Body	Editable interface
llm_tool (prompt)	Plain-text prompt	inwards only
template_tool	Template text	inwards only
code_tool	Python (async def handler(event: dict) -> dict:)	artifact only
browser_tool	Playwright script (JavaScript)	inwards + artifact

A tool has three JSON Schema interfaces: inwards (input), outwards (output — platform-fixed), and artifact (structured result). Which one you can edit depends on the type, as above.

Recommended flow: create the tool minimally, then tool-update to fill in the body, then tool-update-interface to define the schema, then tool-read (with toolVersionId) to verify the draft. Edits create a draft version the user deploys.

---

tool-create

Create a workspace tool. Provide type and name; body is optional (prefer creating minimal, then filling in via tool-update).

Input

Field	Type	Required	Description
type	enum	Yes	code_tool, llm_tool, template_tool, or browser_tool.
name	string	Yes	Tool name.
description	string	No	Short description.
body	string	No	Tool body: prompt/template text, or Python source for code_tool.
inwardsInterfaceModel	object | string	No	Initial inwards JSON Schema.
outwardsInterfaceModel	object | string	No	Initial outwards JSON Schema.
artifactInterfaceModel	object | string	No	Initial artifact JSON Schema.

Output

Field	Type	Description
toolId	string	Id of the new tool (tool_…).
toolType	string	Resolved tool type.
toolVersionId	string | null	Id of the created draft version.

---

tool-read

Read one workspace tool: body (systemPrompt), metadata, LLM options, and the inwards / outwards / artifact interfaces. Optionally read an exact revision with toolVersionId — useful right after create/update to verify a draft.

Input

Field	Type	Required	Description
toolRef / toolId	string	Yes	Tool id (tool_…) or resolvable name.
toolVersionId	string	No	Specific revision (toolv_…) to read instead of the default display version.

Output

Field	Type	Description
tool	object	Tool payload: body, metadata, llmOptions, and interfaces.inwards / outwards / artifact.
resolvedToolVersionId	string | null	The version that was read (when toolVersionId was supplied).

---

tool-update

Update a workspace tool's body and/or metadata. Pass only the fields to change. For code_tool, body must be valid Python (async handler shape, else rejected). If logic changed, follow with tool-update-interface.

Input

Field	Type	Required	Description
toolId	string	Yes	Tool id.
type	enum	No	code_tool / llm_tool / template_tool.
displayName	string	No	New display name.
description	string	No	New description.
body	string	No	New body (prompt/template/Python).

Output

Field	Type	Description
toolId	string	The tool id.
toolType	string	The tool type.
toolVersionId	string | null	The draft version the change was written to.

---

tool-update-interface

Update exactly one JSON Schema interface on a tool. The editable interface depends on type: llm_tool and template_tool → inwards; code_tool → artifact. outwards is platform-fixed and cannot be edited here.

Input

Field	Type	Required	Description
toolId	string	Yes	Tool id or resolvable name.
which	enum	Yes	inwards, outwards, or artifact (must match the type's editable interface).
modelJson	object | string	Yes	The JSON Schema, as an object or a JSON string.

Output

Field	Type	Description
toolId	string	The tool id.
toolType	string	The tool type.
toolVersionId	string | null	The draft version the interface was written to.