{
  "$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-api-surface",
  "title": "Get API Surface",
  "area": "CorePlugin",
  "category": "Code discovery and navigation",
  "operationKind": "Query",
  "summary": "Lists API declarations from source in the selected scope, with symbol references, accessibility and obsolete status. Use this to inventory accessible types and members; use search-symbols to locate declarations by name, or get-symbol-info to inspect one symbol. Omitted scope searches the loaded solution. Defaults to Public accessibility, includes obsolete symbols and returns up to 100 symbols. Check symbols.hasMore before treating the inventory as complete.",
  "availability": "Built in and published in every operational mode.",
  "documentationUrl": "https://lantean-code.github.io/roslyn-workbench-mcp/dev/reference/tools/get-api-surface.html",
  "tool": {
    "name": "get-api-surface",
    "title": "Get API Surface",
    "description": "Lists API declarations from source in the selected scope, with symbol references, accessibility and obsolete status. Use this to inventory accessible types and members; use search-symbols to locate declarations by name, or get-symbol-info to inspect one symbol. Omitted scope searches the loaded solution. Defaults to Public accessibility, includes obsolete symbols and returns up to 100 symbols. Check symbols.hasMore before treating the inventory as complete.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "scope": {
          "description": "The search scope.",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "Solution",
                "Project",
                "Document",
                "Projects"
              ],
              "default": "Solution"
            },
            "project": {
              "$ref": "#/$defs/project",
              "description": "Used only when kind is Project."
            },
            "document": {
              "description": "Used only when kind is Document.",
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "project": {
                  "$ref": "#/$defs/project",
                  "description": "Disambiguates documents with matching paths or IDs."
                },
                "path": {
                  "description": "Workspace-relative path.",
                  "type": "string"
                },
                "documentId": {
                  "description": "Workspace-local document ID.",
                  "type": "string"
                }
              }
            },
            "projects": {
              "description": "Used only when kind is Projects.",
              "type": [
                "array",
                "null"
              ],
              "items": {
                "$ref": "#/$defs/project",
                "description": "Provide projectId, name, path, targetFramework, or any combination."
              }
            }
          }
        },
        "minimumAccessibility": {
          "description": "The minimum accessibility threshold as Public, Protected, or Internal.",
          "type": "string",
          "enum": [
            "Public",
            "Protected",
            "Internal"
          ],
          "default": "Public"
        },
        "includeObsolete": {
          "description": "Whether obsolete symbols should be included.",
          "type": "boolean"
        },
        "symbolsLimit": {
          "description": "Maximum number of results to return.",
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 2147483647,
          "default": 100
        },
        "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"
            }
          }
        }
      },
      "$defs": {
        "project": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "projectId": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "path": {
              "description": "Workspace-relative path.",
              "type": "string"
            },
            "targetFramework": {
              "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": {
                "symbols": {
                  "description": "The returned exported API symbols.",
                  "type": "object",
                  "properties": {
                    "items": {
                      "description": "Items returned in this page.",
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "properties": {
                          "symbol": {
                            "description": "The exported symbol.",
                            "type": [
                              "object",
                              "null"
                            ],
                            "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.",
                                    "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": [
                              "displayName",
                              "kind"
                            ]
                          },
                          "accessibility": {
                            "description": "The declared accessibility.",
                            "type": "string"
                          },
                          "isObsolete": {
                            "description": "Whether the symbol is marked obsolete.",
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "accessibility"
                        ]
                      }
                    },
                    "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": "Get API Surface",
      "destructiveHint": false,
      "idempotentHint": true,
      "openWorldHint": false,
      "readOnlyHint": true
    }
  },
  "examples": []
}