{
  "$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-document-outline",
  "title": "Get Document Outline",
  "area": "CorePlugin",
  "category": "Code discovery and navigation",
  "operationKind": "Query",
  "summary": "Returns a semantic declaration tree for one document, with names, kinds, locations and nested children. Use this to navigate the structure of a known file; use search-symbols to discover declarations across documents, or get-symbol-info for detailed symbol metadata. Members are included by default. Defaults to 200 projected nodes below the document root and 16 hierarchy levels. Check truncated for content omitted by the node or depth limit; root may be null when syntax or semantic information is unavailable.",
  "availability": "Built in and published in every operational mode.",
  "documentationUrl": "https://lantean-code.github.io/roslyn-workbench-mcp/dev/reference/tools/get-document-outline.html",
  "tool": {
    "name": "get-document-outline",
    "title": "Get Document Outline",
    "description": "Returns a semantic declaration tree for one document, with names, kinds, locations and nested children. Use this to navigate the structure of a known file; use search-symbols to discover declarations across documents, or get-symbol-info for detailed symbol metadata. Members are included by default. Defaults to 200 projected nodes below the document root and 16 hierarchy levels. Check truncated for content omitted by the node or depth limit; root may be null when syntax or semantic information is unavailable.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "document": {
          "description": "Target 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"
            }
          }
        },
        "includeMembers": {
          "description": "Whether member nodes should be included.",
          "type": "boolean"
        },
        "maxDepth": {
          "description": "The maximum semantic hierarchy depth below the document root.",
          "type": "integer",
          "minimum": 0,
          "maximum": 24,
          "default": 16
        },
        "nodesLimit": {
          "description": "The optional maximum total number of projected outline nodes.",
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 2000,
          "default": 200
        },
        "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": [
        "document"
      ]
    },
    "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": {
                "document": {
                  "description": "The resolved document reference.",
                  "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"
                  ]
                },
                "root": {
                  "description": "The outline root node.",
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "name": {
                      "description": "The node display name.",
                      "type": "string"
                    },
                    "kind": {
                      "description": "The Roslyn symbol or declaration kind.",
                      "type": "string"
                    },
                    "accessibility": {
                      "description": "The optional accessibility.",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "modifiers": {
                      "description": "The node modifiers.",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "location": {
                      "description": "The node location, when available.",
                      "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"
                      ]
                    },
                    "children": {
                      "description": "The child outline nodes.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "description": "The node display name.",
                            "type": "string"
                          },
                          "kind": {
                            "description": "The Roslyn symbol or declaration kind.",
                            "type": "string"
                          },
                          "accessibility": {
                            "description": "The optional accessibility.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "modifiers": {
                            "description": "The node modifiers.",
                            "$ref": "#/properties/request/properties/value/properties/root/properties/modifiers",
                            "items": {}
                          },
                          "location": {
                            "description": "The node location, when available.",
                            "$ref": "#/properties/request/properties/value/properties/root/properties/location"
                          },
                          "children": {
                            "description": "The child outline nodes.",
                            "$ref": "#/properties/request/properties/value/properties/root/properties/children",
                            "items": {}
                          }
                        },
                        "required": [
                          "name",
                          "kind"
                        ]
                      }
                    }
                  },
                  "required": [
                    "name",
                    "kind"
                  ]
                },
                "truncated": {
                  "description": "Whether the hierarchy was truncated by its node or depth bound.",
                  "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 Document Outline",
      "destructiveHint": false,
      "idempotentHint": true,
      "openWorldHint": false,
      "readOnlyHint": true
    }
  },
  "examples": []
}