{
  "$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": "analyze-data-flow",
  "title": "Analyze Data Flow",
  "area": "CorePlugin",
  "category": "Code analysis",
  "operationKind": "Query",
  "summary": "Returns Roslyn variable sets for declarations, reads, writes, captures and data flowing into or out of an exact expression, complete statement or contiguous sibling statements in one executable body. Use this when planning to extract or move selected code; use get-operation-tree for semantic operation structure, or analyze-control-flow for region reachability and exits. Echo the current expectedSnapshot and select exact syntax spans. Each variable category is limited independently to 50 symbols by default; check its hasMore before treating the category as complete.",
  "availability": "Built in and published in every operational mode.",
  "documentationUrl": "https://lantean-code.github.io/roslyn-workbench-mcp/dev/reference/tools/analyze-data-flow.html",
  "tool": {
    "name": "analyze-data-flow",
    "title": "Analyze Data Flow",
    "description": "Returns Roslyn variable sets for declarations, reads, writes, captures and data flowing into or out of an exact expression, complete statement or contiguous sibling statements in one executable body. Use this when planning to extract or move selected code; use get-operation-tree for semantic operation structure, or analyze-control-flow for region reachability and exits. Echo the current expectedSnapshot and select exact syntax spans. Each variable category is limited independently to 50 symbols by default; check its hasMore before treating the category as complete.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "location": {
          "description": "An exact expression, complete statement or contiguous statement range to analyze.",
          "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"
              ]
            }
          }
        },
        "symbolsPerCategoryLimit": {
          "description": "Maximum number of symbols to return in each data-flow category.",
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 2147483647,
          "default": 50
        },
        "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": {
                "region": {
                  "description": "The analyzed region.",
                  "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"
                  ]
                },
                "variablesDeclared": {
                  "description": "The variables declared within the region.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "properties": {
                          "displayName": {
                            "description": "The display name of the symbol.",
                            "type": "string"
                          },
                          "kind": {
                            "description": "The symbol kind.",
                            "type": "string"
                          },
                          "documentationCommentId": {
                            "description": "The documentation comment identifier, when available.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "location": {
                            "description": "The optional source location of the symbol.",
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "document": {
                                "description": "The resolved document.",
                                "$ref": "#/properties/request/properties/value/properties/region/properties/document"
                              },
                              "span": {
                                "description": "The resolved text span.",
                                "$ref": "#/properties/request/properties/value/properties/region/properties/span"
                              },
                              "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.",
                                "$ref": "#/properties/request/properties/value/properties/region/properties/snapshot"
                              },
                              "selector": {
                                "description": "The canonical selector that can resolve this source location again.",
                                "$ref": "#/properties/request/properties/value/properties/region/properties/selector"
                              }
                            },
                            "required": [
                              "snapshot"
                            ]
                          }
                        },
                        "required": [
                          "displayName",
                          "kind"
                        ]
                      }
                    },
                    "hasMore": {
                      "description": "Whether additional items were available beyond this page.",
                      "type": "boolean"
                    },
                    "totalCount": {
                      "description": "Complete result count, when available without additional expensive work.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                },
                "readInside": {
                  "description": "The symbols read within the region.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "$ref": "#/properties/request/properties/value/properties/variablesDeclared/properties/items",
                      "items": {}
                    },
                    "hasMore": {
                      "description": "Whether additional items were available beyond this page.",
                      "type": "boolean"
                    },
                    "totalCount": {
                      "description": "Complete result count, when available without additional expensive work.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                },
                "writtenInside": {
                  "description": "The symbols written within the region.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "$ref": "#/properties/request/properties/value/properties/variablesDeclared/properties/items",
                      "items": {}
                    },
                    "hasMore": {
                      "description": "Whether additional items were available beyond this page.",
                      "type": "boolean"
                    },
                    "totalCount": {
                      "description": "Complete result count, when available without additional expensive work.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                },
                "dataFlowsIn": {
                  "description": "The symbols flowing into the region.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "$ref": "#/properties/request/properties/value/properties/variablesDeclared/properties/items",
                      "items": {}
                    },
                    "hasMore": {
                      "description": "Whether additional items were available beyond this page.",
                      "type": "boolean"
                    },
                    "totalCount": {
                      "description": "Complete result count, when available without additional expensive work.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                },
                "dataFlowsOut": {
                  "description": "The symbols flowing out of the region.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "$ref": "#/properties/request/properties/value/properties/variablesDeclared/properties/items",
                      "items": {}
                    },
                    "hasMore": {
                      "description": "Whether additional items were available beyond this page.",
                      "type": "boolean"
                    },
                    "totalCount": {
                      "description": "Complete result count, when available without additional expensive work.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                },
                "captured": {
                  "description": "The captured symbols.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "$ref": "#/properties/request/properties/value/properties/variablesDeclared/properties/items",
                      "items": {}
                    },
                    "hasMore": {
                      "description": "Whether additional items were available beyond this page.",
                      "type": "boolean"
                    },
                    "totalCount": {
                      "description": "Complete result count, when available without additional expensive work.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              },
              "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": "Analyze Data Flow",
      "destructiveHint": false,
      "idempotentHint": true,
      "openWorldHint": false,
      "readOnlyHint": true
    }
  },
  "examples": []
}