Skip to content

The tools an Agent receives

When an Agent connects to a Workspace it receives a list of tools, and that list is what it can do there. It is built for the person whose token opened the connection: their role, whether they hold a seat, and how the Workspace is set up. A Viewer receives four tools, an Editor six, an Owner nine.

The list travels once, when the connection opens, so a change of role or a new Collection shows up in the next session, not in the one already running.

Reading tools, available to every role

These four come with any role, and reading never needs a seat.

  • get_workspace_informations is the door. It gives the name and the description of the Workspace and, in a Structured one, the list of its Collections with their identifiers, their statuses and their instructions. The Agent takes the Collection identifiers from here, so it usually calls this first.
  • list_documents lists the Documents of one Collection with their title and their summary, never the content. It can filter by status, include the archived ones, and it says when it has cut a long list.
  • search_documents searches titles, summaries and identifiers, never the content. The Collection is optional: without it, it searches the whole Workspace.
  • get_document reads one Document in full, content included. An archived Document comes back too.

Two of these say what a Document is about without opening it, which is why the summary you write matters: it is what an Agent reads before deciding what to open.

Writing tools, for Owner and Editor with a seat

  • create_document creates a Document inside a Collection.
  • update_document changes a Document, archives it and brings it back. It requires the timestamp of the version the Agent read, so two Agents working at the same time cannot overwrite each other in silence.

Whoever can write but holds no seat keeps the four reading tools and loses these two, and the refusal says so: it talks about the seat, not about the role.

Collection level tools, for the Owner

  • get_available_collection_types lists the kinds of Collection that can be opened, and says which ones the Workspace already has.
  • create_collection opens a new one, with its name and its statuses.
  • update_collection_instructions writes the instructions of a Collection, the ones every Agent receives when it connects.

In a Simplified Workspace there is one Collection and the Agent never sees that level: those three are replaced by update_workspace_instructions, which writes the same instructions without naming a container that, there, has no reason to exist.

Actions not available to an Agent

  • Delete a Document. Archiving is the only way an Agent has to take something out of the way, and an archive is not a bin.
  • Move a Document to another Collection. It is done from the web app.
  • Rename, deactivate or delete a Collection. An Agent can open one and write its instructions, the rest stays with whoever owns the Workspace.
  • Give someone a seat. Seats are assigned by whoever administers the Organization that pays for them.

Who can do what, role by role, is on the Roles page. How a client gets connected in the first place is on Connect an Agent.