{
  "$schema": "../schemas/tool-detail.schema.json",
  "formatVersion": "roslyn-workbench-tool-reference/v1",
  "productVersion": "0.1.0-beta.294",
  "sourceTag": "0.1.0-beta.294",
  "commit": "4c70250e5e02c4109ceff810651918d34513225b",
  "name": "workspace-open",
  "title": "Workspace Open",
  "area": "Server",
  "category": "Workspaces",
  "operationKind": "Mutation",
  "summary": "Loads an additional writable workspace. Open only a fully trusted workspace: loading evaluates MSBuild project logic, evaluated source inputs including external linked or package-provided documents become queryable, and later diagnostic or Code Action operations can load and execute project analyzers with the Host's permissions. Documents outside workspaceRoot remain read-only. If instance status reports that the workspace is or may be in use elsewhere, use it only for necessary queries, expect results to become stale, and coordinate mutation ownership before starting a transaction.",
  "availability": "Built in and published by default.",
  "documentationUrl": "https://lantean-code.github.io/roslyn-workbench-mcp/0.1.0-beta.294/reference/tools/workspace-open.html",
  "tool": {
    "name": "workspace-open",
    "title": "Workspace Open",
    "description": "Loads an additional writable workspace. Open only a fully trusted workspace: loading evaluates MSBuild project logic, evaluated source inputs including external linked or package-provided documents become queryable, and later diagnostic or Code Action operations can load and execute project analyzers with the Host's permissions. Documents outside workspaceRoot remain read-only. If instance status reports that the workspace is or may be in use elsewhere, use it only for necessary queries, expect results to become stale, and coordinate mutation ownership before starting a transaction.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "alias": {
          "description": "The optional caller-friendly alias for the workspace.",
          "type": [
            "string",
            "null"
          ]
        },
        "path": {
          "description": "The absolute solution or project path to load.",
          "type": "string"
        },
        "msBuildProperties": {
          "description": "The optional allowlisted MSBuild global properties used to evaluate this workspace.",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "artifactsPath": {
              "description": "Existing absolute directory used for MSBuild intermediate and output artifacts.",
              "type": [
                "string",
                "null"
              ]
            },
            "configuration": {
              "description": "MSBuild Configuration global property, such as Debug or Release.",
              "type": [
                "string",
                "null"
              ]
            },
            "platform": {
              "description": "MSBuild Platform global property, such as AnyCPU or x64.",
              "type": [
                "string",
                "null"
              ]
            },
            "runtimeIdentifier": {
              "description": "MSBuild RuntimeIdentifier global property used to evaluate the workspace.",
              "type": [
                "string",
                "null"
              ]
            },
            "targetFramework": {
              "description": "MSBuild TargetFramework global property used to select a target-specific project evaluation.",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "additionalProperties": false
        },
        "workspaceRoot": {
          "description": "The optional absolute repository or workspace root used for coordination and transaction boundaries.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "path"
      ]
    },
    "outputSchema": {
      "type": "object",
      "oneOf": [
        {
          "type": "object",
          "required": [
            "ok",
            "data"
          ],
          "properties": {
            "ok": {
              "const": true,
              "description": "Whether the tool invocation succeeded."
            },
            "data": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "workspace": {
                  "description": "The loaded workspace identity.",
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "workspaceId": {
                      "description": "The stable server-generated workspace identifier.",
                      "type": "string",
                      "format": "uuid"
                    },
                    "alias": {
                      "description": "The optional caller-friendly alias.",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "workspaceEpoch": {
                      "description": "The workspace epoch for the loaded baseline.",
                      "type": "integer"
                    },
                    "loadedPath": {
                      "description": "The absolute path of the loaded workspace.",
                      "type": "string"
                    },
                    "workspaceRoot": {
                      "description": "The absolute repository or workspace root used for coordination and transaction boundaries.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "loadedPath",
                    "workspaceRoot"
                  ]
                },
                "projectCount": {
                  "description": "The loaded project count.",
                  "type": "integer"
                },
                "documentCount": {
                  "description": "The loaded document count.",
                  "type": "integer"
                },
                "loadDiagnostics": {
                  "description": "Workspace load and advisory status diagnostics.",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "description": "The diagnostic identifier.",
                        "type": "string"
                      },
                      "severity": {
                        "description": "The diagnostic severity.",
                        "type": "string",
                        "enum": [
                          "Hidden",
                          "Info",
                          "Warning",
                          "Error"
                        ]
                      },
                      "message": {
                        "description": "The diagnostic message.",
                        "type": "string"
                      },
                      "location": {
                        "description": "The optional source location of the diagnostic.",
                        "type": [
                          "object",
                          "null"
                        ],
                        "properties": {
                          "document": {
                            "description": "The resolved document.",
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "documentId": {
                                "description": "The document identifier.",
                                "type": "string"
                              },
                              "path": {
                                "description": "The normalized document path.",
                                "type": "string"
                              },
                              "projectId": {
                                "description": "The owning project identifier.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "documentId",
                              "path",
                              "projectId"
                            ]
                          },
                          "span": {
                            "description": "The resolved text span.",
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "start": {
                                "description": "Zero-based UTF-16 offset.",
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 2147483647
                              },
                              "length": {
                                "description": "UTF-16 code-unit length.",
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 2147483647
                              }
                            }
                          },
                          "line": {
                            "description": "The one-based line number.",
                            "type": "integer"
                          },
                          "column": {
                            "description": "The one-based column number.",
                            "type": "integer"
                          },
                          "snapshot": {
                            "description": "The exact immutable workspace snapshot associated with this location.",
                            "type": "object",
                            "properties": {
                              "workspaceId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "workspaceEpoch": {
                                "type": "integer"
                              },
                              "snapshotId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "transactionRevision": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "workspaceId",
                              "workspaceEpoch",
                              "snapshotId",
                              "transactionRevision"
                            ]
                          },
                          "selector": {
                            "description": "The canonical selector that can resolve this source location again.",
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "span": {
                                "type": "object",
                                "properties": {
                                  "document": {
                                    "description": "Provide exactly one of path or documentId.",
                                    "type": "object",
                                    "properties": {
                                      "project": {
                                        "description": "Disambiguates documents with matching paths or IDs.",
                                        "type": [
                                          "object",
                                          "null"
                                        ],
                                        "properties": {
                                          "projectId": {
                                            "type": [
                                              "string",
                                              "null"
                                            ]
                                          },
                                          "name": {
                                            "type": [
                                              "string",
                                              "null"
                                            ]
                                          },
                                          "path": {
                                            "description": "Workspace-relative path.",
                                            "type": [
                                              "string",
                                              "null"
                                            ]
                                          },
                                          "targetFramework": {
                                            "type": [
                                              "string",
                                              "null"
                                            ]
                                          }
                                        }
                                      },
                                      "path": {
                                        "description": "Workspace-relative path.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "documentId": {
                                        "description": "Workspace-local document ID.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      }
                                    }
                                  },
                                  "range": {
                                    "description": "Zero-based UTF-16 range.",
                                    "type": "object",
                                    "properties": {
                                      "start": {
                                        "description": "Zero-based UTF-16 offset.",
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 2147483647
                                      },
                                      "length": {
                                        "description": "UTF-16 code-unit length.",
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 2147483647
                                      }
                                    }
                                  }
                                },
                                "required": [
                                  "document",
                                  "range"
                                ]
                              }
                            },
                            "required": [
                              "span"
                            ]
                          }
                        },
                        "required": [
                          "snapshot"
                        ]
                      }
                    },
                    "required": [
                      "id",
                      "message"
                    ]
                  }
                }
              },
              "description": "Tool-specific result payload."
            },
            "snapshot": {
              "type": "object",
              "properties": {
                "workspaceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "workspaceEpoch": {
                  "type": "integer"
                },
                "snapshotId": {
                  "type": "string",
                  "format": "uuid"
                },
                "transactionRevision": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              },
              "required": [
                "workspaceId",
                "workspaceEpoch",
                "snapshotId",
                "transactionRevision"
              ],
              "description": "Exact immutable workspace snapshot associated with the result, when available."
            }
          }
        },
        {
          "type": "object",
          "required": [
            "ok",
            "error"
          ],
          "properties": {
            "ok": {
              "const": false,
              "description": "Whether the tool invocation succeeded."
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "description": "Stable machine-readable error code.",
                  "type": "string"
                },
                "message": {
                  "description": "Human-readable explanation of the failure.",
                  "type": "string"
                },
                "correlationId": {
                  "description": "Correlation identifier for matching the failure to server-side diagnostics, when available.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "code",
                "message"
              ],
              "description": "Structured error details when the invocation failed."
            },
            "continuation": {
              "oneOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "tool",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "CallTool",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    },
                    "tool": {
                      "type": "string",
                      "description": "Tool to call before continuing the original request.",
                      "minLength": 1
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "tools",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "ChooseTool",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    },
                    "tools": {
                      "type": "array",
                      "description": "Allowed tool choices from which the agent must select one.",
                      "minItems": 1,
                      "uniqueItems": true,
                      "items": {
                        "type": "string",
                        "description": "Name of a tool the agent may choose.",
                        "minLength": 1
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "RetryRequest",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "ReviseRequest",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "ResolveExternally",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    }
                  }
                }
              ],
              "description": "Action the agent should take before retrying or continuing."
            }
          }
        }
      ]
    },
    "annotations": {
      "title": "Workspace Open",
      "destructiveHint": false,
      "idempotentHint": false,
      "openWorldHint": false,
      "readOnlyHint": false
    }
  },
  "examples": [
    {
      "workflowId": "workspace-setup",
      "workflowTitle": "Open and select a workspace",
      "step": 2,
      "id": "open-solution",
      "title": "Open a solution",
      "purpose": "Load a trusted solution once and assign an alias that later calls can use.",
      "expectedOutcome": "The workspace opens and subsequent calls can select it by the sample alias.",
      "representativeResponse": null,
      "request": {
        "path": "/workspace/Sample.slnx",
        "alias": "sample"
      }
    }
  ]
}