Skip to main content
Glama

Switch workspace

switch_workspace
Idempotent

Re-root the workspace to another directory at runtime. Follows VENIRA_SECURITY_PROFILE: trusted/off (or VENIRA_UNRESTRICTED=1) switch anywhere existing; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = spawn only).

Instructions

Re-root the workspace to another directory at runtime. Follows VENIRA_SECURITY_PROFILE: trusted/off (or VENIRA_UNRESTRICTED=1) switch anywhere existing; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = spawn only). Use when: the client spawned the server once (e.g. Claude Desktop) and the user changed to a different project folder; switch instead of restarting the client. Avoid when: one-shot tasks in the spawn directory, or under strict/balanced without VENIRA_WORKSPACE_ROOTS (the call is refused). Output: workspace_root (the new root), allowed_roots. All subsequent path guards and caches operate on the new root.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "root": "<root>"
    },
    "name": "switch_workspace"
  }
}

Input Schema

NameRequiredDescriptionDefault
rootYesAbsolute path of the directory to make the workspace. Follows VENIRA_SECURITY_PROFILE: trusted/off switch to any existing directory; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = locked to the spawn workspace).
reasonNoOptional why (max 400 chars), audit-logged.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv4.4.0
    • changedInput schema / properties / root / description
      Previous value: -"Absolute path of the directory to make the workspace. Enabled by default; when VENIRA_WORKSPACE_ROOTS is set the target must be inside it, otherwise any existing directory may be chosen; VENIRA_DYNAMIC_WORKSPACE=0 opts out."New value: +"Absolute path of the directory to make the workspace. Follows VENIRA_SECURITY_PROFILE: trusted/off switch to any existing directory; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = locked to the spawn workspace)."
  2. Addedv4.0.0

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description adds real context beyond them: security-profile gating, the exact refusal condition under strict/balanced, and the note that all subsequent path guards and caches re-key on the new root. It does not state whether the previous root can be restored on failure, which is the one gap worth noting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the operation, then Use when / Avoid when / Output in a scannable structure with no filler. The security-profile sentence is dense but earns its place because it prevents refused calls.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation tool with no output schema, the description covers trigger conditions, refusal conditions, and return fields (workspace_root, allowed_roots). An agent has everything needed to decide and to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both root (absolute path, profile gating) and reason (audit-logged, max 400). The description largely restates the same gating rules rather than adding new semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Re-root the workspace to another directory at runtime.' This is unambiguous and clearly distinct from all listed siblings (file, git, shell, cache tools), none of which manipulate the workspace root.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Use when' (client spawned the server once, user changed project folder, switch instead of restarting) and 'Avoid when' (one-shot tasks in spawn directory; strict/balanced without VENIRA_WORKSPACE_ROOTS where the call is refused). Both the positive trigger and the exclusion condition are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.