Agent: Experimental | Hoody Documentation

Skip to content

Download Page (.md)

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

200

{
  "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

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

200
400

[
  {
    "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"]
    }
  }
]

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

SDK Usage

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

200
400

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

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

SDK Usage

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

200

[
  {
    "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

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