Skip to main content
These tools are free. get_usage needs the See API credit usage permission (usage:read). list_workspaces and switch_workspace need no permission, and the assistant sees them only if you’re in more than one workspace.

​
Try these prompts

Claude and GPT picked the tools shown for these prompts in Alura’s evaluation runs.

​
Good to know

  • A switch sticks. It changes the connection’s current workspace for every chat that uses it, until the next switch. Ask the assistant to switch back when you’re done. Because later saves land in another workspace, switch_workspace is marked destructive, and assistants such as Claude ask before switching.
  • The workspace pays. Calls after a switch use the new workspace’s API credits and plan.
  • Owners are told. The first time a connection switches into a workspace, that workspace’s owners get an email.
  • API keys can’t switch. A key belongs to one workspace; switch_workspace with a key answers workspace_locked.

​
Tools

​
get_usage

Get API usage. Show the workspace’s API credit usage: plan, this month’s allowance, used and remaining credits, the daily ceiling, the request rate, today’s fetch caps, credits spent by operation and by client, and the price of every operation. The plan itself is managed in Alura’s settings. Use it when the user asks about credits, limits, spending or plans, or before a large batch of paid calls.
  • Cost of get_usage: Free (0 API credits).
  • Behavior: Read-only: changes nothing. Works on Alura’s own data only.
  • Scope: usage:read (see API credit usage).
  • REST: GET /v1/usage.

​
list_workspaces

List workspaces. List the Alura workspaces this connection can act for, with the current one marked (current). Every other tool acts for the current workspace and spends its API credits. Use it before switch_workspace, or when the user asks which workspace you are working in.
  • Cost of list_workspaces: Free (0 API credits).
  • Behavior: Read-only: changes nothing. Works on Alura’s own data only.
  • Scope: none: any connection can call it.
  • REST: GET /v1/me/workspaces.

​
switch_workspace

Switch workspace. Make another of the user’s workspaces the current one for this connection. From the next call on, every tool acts for that workspace: its saved research, and its API credits pay. It applies to every conversation using this connection. Take the ID from list_workspaces. Use it when the user asks to work in, or save to, another workspace.
  • Cost of switch_workspace: Free (0 API credits).
  • Behavior: Destructive. It overwrites the connection’s current workspace, so later reads and saves go to another workspace, and the owners’ notice of a first switch cannot be taken back. Safe to repeat. Switching to the workspace that is already current changes nothing, so repeating a call has no further effect.
  • Scope: none: any connection can call it.
  • REST: POST /v1/me/workspace.
Example arguments