# Agent: Experimental

**Page:** api/agent/experimental

[Download Raw Markdown](./api/agent/experimental.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Agent: Experimental

The Experimental endpoints expose discovery and inspection utilities for the agent runtime. Use them to enumerate available tool IDs, retrieve full JSON schemas for a given provider and model, and list MCP resources exposed by connected servers. These endpoints are intended for tooling, dashboards, and runtime introspection.

---

### `GET /api/v1/workspaces/{workspaceID}/experimental/resource`

Get all available MCP resources from connected servers. Optionally filter by name.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "file_workspace_abc123": {
    "name": "file_workspace_abc123",
    "uri": "hoody://workspace/abc123/files",
    "description": "Files in the active workspace",
    "mimeType": "inode/directory",
    "client": "hoody-filesystem"
  },
  "docs_search_index": {
    "name": "docs_search_index",
    "uri": "hoody://docs/index",
    "description": "Indexed documentation for full-text search",
    "mimeType": "application/json",
    "client": "hoody-docs"
  }
}
```



#### SDK Usage

```ts
const { data } = await client.agent.experimental.listMcpResources({
  workspaceID: "ws_01HXYZ..."
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/experimental/tool`

Get a list of available tools with their JSON schema parameters for a specific provider and model combination.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `provider` | query | string | Yes | Model provider (e.g. `openai`, `anthropic`) |
| `model` | query | string | Yes | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-5`) |

#### Response



```json
[
  {
    "id": "read_file",
    "description": "Read the contents of a file at the given path.",
    "parameters": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Absolute path of the file to read"
        }
      },
      "required": ["path"]
    }
  },
  {
    "id": "web_search",
    "description": "Search the public web and return the top results.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string" },
        "max_results": { "type": "integer", "default": 5 }
      },
      "required": ["query"]
    }
  }
]
```


```json
{
  "data": null,
  "errors": [
    {
      "code": "INVALID_PROVIDER",
      "message": "Provider 'unknown-provider' is not supported"
    }
  ],
  "success": false
}
```



#### SDK Usage

```ts
const { data } = await client.agent.experimental.listToolSchemas({
  workspaceID: "ws_01HXYZ...",
  provider: "anthropic",
  model: "claude-sonnet-4-5"
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/experimental/tool/ids`

Get a list of all available tool IDs, including both built-in tools and dynamically registered tools.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
[
  "read_file",
  "write_file",
  "web_search",
  "run_command",
  "mcp:hoody-filesystem:list_dir",
  "plugin:linear:create_issue"
]
```


```json
{
  "data": null,
  "errors": [
    {
      "code": "WORKSPACE_NOT_FOUND",
      "message": "Workspace 'ws_invalid' does not exist"
    }
  ],
  "success": false
}
```



#### SDK Usage

```ts
const { data } = await client.agent.experimental.listToolIds({
  workspaceID: "ws_01HXYZ..."
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/tools`

Get a unified list of all available tools with their source and enabled status.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
[
  {
    "id": "read_file",
    "description": "Read the contents of a file at the given path.",
    "source": "builtin",
    "sourceName": "core",
    "category": "filesystem",
    "enabled": true,
    "status": "ready",
    "asyncCapable": false,
    "wakePolicy": "auto",
    "permissionKey": "fs.read"
  },
  {
    "id": "mcp_list_dir",
    "description": "List directory contents from the connected filesystem MCP server.",
    "source": "mcp",
    "sourceName": "hoody-filesystem",
    "category": "filesystem",
    "enabled": true,
    "status": "ready",
    "asyncCapable": false,
    "wakePolicy": "next_turn",
    "permissionKey": "mcp.filesystem.list_dir"
  },
  {
    "id": "plugin_linear_create_issue",
    "description": "Create a Linear issue from agent output.",
    "source": "plugin",
    "sourceName": "linear",
    "category": "productivity",
    "enabled": false,
    "status": "needs_auth",
    "asyncCapable": true,
    "wakePolicy": "manual",
    "permissionKey": null
  }
]
```



#### SDK Usage

```ts
const { data } = await client.agent.tools.list({
  workspaceID: "ws_01HXYZ..."
});
```


The `source` field distinguishes between `builtin` (shipped with the platform), `mcp` (exposed by a connected Model Context Protocol server), and `plugin` (registered dynamically by a workspace plugin). The `enabled` flag reflects the current user-level toggle; tools that are disabled are not surfaced to the model.