{
  "$schema": "../schemas/tool-detail.schema.json",
  "formatVersion": "roslyn-workbench-tool-reference/v1",
  "productVersion": "0.0.0-dev",
  "sourceTag": "0.0.0-dev",
  "commit": "development",
  "name": "get-operation-tree",
  "title": "Get Operation Tree",
  "area": "CorePlugin",
  "category": "Code analysis",
  "operationKind": "Query",
  "summary": "Projects a semantic IOperation tree with operation kinds, types, constant-value presence and source locations. Use this to inspect the semantic structure at a source location; use analyze-data-flow for variable-flow sets or get-control-flow-graph for branches and successors. If the selected syntax node has no operation, the first immediate child with an operation is used. Echo the current expectedSnapshot. Defaults to 200 total nodes and maxDepth 8, counting the root at depth zero. Check the result and node truncated flags; nodesLimit zero returns a null root.",
  "availability": "Built in and published in every operational mode.",
  "documentationUrl": "https://lantean-code.github.io/roslyn-workbench-mcp/dev/reference/tools/get-operation-tree.html",
  "tool": {
    "name": "get-operation-tree",
    "title": "Get Operation Tree",
    "description": "Projects a semantic IOperation tree with operation kinds, types, constant-value presence and source locations. Use this to inspect the semantic structure at a source location; use analyze-data-flow for variable-flow sets or get-control-flow-graph for branches and successors. If the selected syntax node has no operation, the first immediate child with an operation is used. Echo the current expectedSnapshot. Defaults to 200 total nodes and maxDepth 8, counting the root at depth zero. Check the result and node truncated flags; nodesLimit zero returns a null root.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "location": {
          "description": "The selected location.",
          "type": "object",
          "properties": {
            "span": {
              "type": "object",
              "properties": {
                "document": {
                  "$ref": "#/$defs/document",
                  "description": "Provide exactly one of path or documentId."
                },
                "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"
              ]
            },
            "selection": {
              "type": "object",
              "properties": {
                "document": {
                  "$ref": "#/$defs/document",
                  "description": "Provide exactly one of path or documentId."
                },
                "selectedText": {
                  "type": "string",
                  "minLength": 1
                },
                "contextBefore": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "contextAfter": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "document",
                "selectedText"
              ]
            }
          }
        },
        "maxDepth": {
          "description": "The maximum traversal depth.",
          "type": "integer",
          "minimum": 0,
          "maximum": 24,
          "default": 8
        },
        "nodesLimit": {
          "description": "The optional maximum total number of projected operation nodes.",
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 2000,
          "default": 200
        },
        "expectedSnapshot": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "workspaceId": {
              "type": "string",
              "format": "uuid"
            },
            "workspaceEpoch": {
              "type": "integer"
            },
            "snapshotId": {
              "type": "string",
              "format": "uuid"
            },
            "transactionRevision": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "workspaceId",
            "workspaceEpoch",
            "snapshotId",
            "transactionRevision"
          ],
          "description": "Echo the snapshot returned with the data or transaction state used to construct this request."
        },
        "workspace": {
          "description": "Provide workspaceId, alias, path, or any combination.",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "workspaceId": {
              "type": "string",
              "format": "uuid"
            },
            "alias": {
              "type": "string"
            },
            "path": {
              "description": "Absolute workspace path.",
              "type": "string"
            }
          }
        }
      },
      "required": [
        "location"
      ],
      "$defs": {
        "document": {
          "type": "object",
          "properties": {
            "project": {
              "description": "Disambiguates documents with matching paths or IDs.",
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "projectId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "path": {
                  "description": "Workspace-relative path.",
                  "type": "string"
                },
                "targetFramework": {
                  "type": "string"
                }
              }
            },
            "path": {
              "description": "Workspace-relative path.",
              "type": "string"
            },
            "documentId": {
              "description": "Workspace-local document ID.",
              "type": "string"
            }
          }
        }
      }
    },
    "outputSchema": {
      "type": "object",
      "oneOf": [
        {
          "type": "object",
          "required": [
            "ok",
            "data",
            "snapshot"
          ],
          "properties": {
            "ok": {
              "const": true,
              "description": "Whether the tool invocation succeeded."
            },
            "data": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "root": {
                  "description": "The projected root operation.",
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "kind": {
                      "description": "The Roslyn operation kind.",
                      "type": "string"
                    },
                    "type": {
                      "description": "The associated type display name, when available.",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "hasConstantValue": {
                      "description": "Whether the operation has a constant value.",
                      "type": "boolean"
                    },
                    "location": {
                      "description": "The exact source location of the operation.",
                      "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"
                      ]
                    },
                    "truncated": {
                      "description": "Whether child nodes were truncated.",
                      "type": "boolean"
                    },
                    "children": {
                      "description": "The projected child operations.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "description": "The Roslyn operation kind.",
                            "type": "string"
                          },
                          "type": {
                            "description": "The associated type display name, when available.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "hasConstantValue": {
                            "description": "Whether the operation has a constant value.",
                            "type": "boolean"
                          },
                          "location": {
                            "description": "The exact source location of the operation.",
                            "$ref": "#/properties/request/properties/value/properties/root/properties/location"
                          },
                          "truncated": {
                            "description": "Whether child nodes were truncated.",
                            "type": "boolean"
                          },
                          "children": {
                            "description": "The projected child operations.",
                            "$ref": "#/properties/request/properties/value/properties/root/properties/children",
                            "items": {}
                          }
                        },
                        "required": [
                          "kind"
                        ]
                      }
                    }
                  },
                  "required": [
                    "kind"
                  ]
                },
                "truncated": {
                  "description": "Whether the tree was truncated.",
                  "type": "boolean"
                }
              },
              "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."
            },
            "warnings": {
              "type": "array",
              "description": "Non-fatal warnings the agent should consider.",
              "items": {
                "$ref": "#/$defs/warningInfo"
              }
            }
          }
        },
        {
          "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."
            },
            "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": "Diagnostics that explain the failed invocation."
            },
            "warnings": {
              "type": "array",
              "description": "Non-fatal warnings the agent should consider.",
              "items": {
                "$ref": "#/$defs/warningInfo"
              }
            }
          }
        },
        {
          "type": "object",
          "required": [
            "ok",
            "error",
            "diagnostics"
          ],
          "properties": {
            "ok": {
              "const": false,
              "description": "Whether the tool invocation succeeded."
            },
            "error": {
              "type": "object",
              "required": [
                "code",
                "message",
                "correlationId"
              ],
              "properties": {
                "code": {
                  "const": "UnhandledException"
                },
                "message": {
                  "const": "Tool execution failed."
                },
                "correlationId": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "description": "Structured error details when the invocation failed."
            },
            "diagnostics": {
              "type": "object",
              "required": [
                "detailsAvailable",
                "detailsTool"
              ],
              "properties": {
                "detailsAvailable": {
                  "const": true
                },
                "detailsTool": {
                  "const": "get-error-details"
                }
              },
              "description": "Diagnostics that explain the failed invocation."
            },
            "reporting": {
              "type": "object",
              "properties": {
                "state": {
                  "type": "string",
                  "enum": [
                    "Available",
                    "AlwaysApproved",
                    "DisabledByConfiguration",
                    "ApprovalUnavailable"
                  ]
                },
                "canPrepare": {
                  "type": "boolean"
                },
                "prepareTool": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "state"
              ],
              "description": "Error-reporting workflow available for an unhandled failure."
            }
          }
        }
      ],
      "$defs": {
        "warningInfo": {
          "type": "object",
          "properties": {
            "code": {
              "description": "The stable machine-readable warning code.",
              "type": "string"
            },
            "message": {
              "description": "The human-readable warning message.",
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ]
        }
      }
    },
    "annotations": {
      "title": "Get Operation Tree",
      "destructiveHint": false,
      "idempotentHint": true,
      "openWorldHint": false,
      "readOnlyHint": true
    }
  },
  "examples": []
}