### Trigger Agent Test Run

Source: https://docs.naironai.com/developers/tools-observability

Execute an agent end-to-end in a test channel to verify its functionality. The `channelId` must be a test channel (name starts with 'test-'). Use `maxWaitMs` to wait for a terminal status.

```python
hive_test_trigger(channelId="test-agent-qa", maxWaitMs=10000)
```

--------------------------------

### Get Agent Turn Status and History

Source: https://docs.naironai.com/developers/tools-observability

Retrieve the full status, output, error, and tool-call history for a specific agent turn. Use `maxWaitMs` to poll for terminal status.

```python
hive_turn_get(turnId="turn_abc", maxWaitMs=5000)
```

--------------------------------

### hive_account_connect

Source: https://docs.naironai.com/developers/tools-connected-accounts

Connects a new Composio-backed tool account for the workspace using an API key. Requires prior unlocking for gated providers.

```APIDOC
## hive_account_connect

### Description
Use this when you need to connect a new Composio-backed tool account for this workspace via an API key. `provider` is a Composio toolkit slug (lowercase, e.g. "gmail"), not a display name. If the provider is gated (exa, firecrawl, twitterapi), `hive_provider_unlock` must be called for it first — this tool rejects the connect attempt with the exact fix otherwise.

### Method
N/A (Tool function)

### Parameters
#### Request Body
- **provider** (string) - required - Composio toolkit slug to connect, e.g. "gmail", "linear", "exa".
- **apiKey** (string) - required - The provider's API key.
- **label** (string) - optional - Display label. Defaults to a generated one.
- **skipValidation** (boolean) - optional - Skip Composio's credential validation step — use only when a toolkit's validation endpoint is known to be broken for otherwise-valid keys.
- **fieldName** (string) - optional - Override the credential field name Composio expects, for toolkits whose auth-field schema didn't sync (rare).
```

--------------------------------

### Configure OpenCode MCP Server

Source: https://docs.naironai.com/developers/connecting

Configuration for OpenCode to connect to the hive-dev MCP server. This JSON snippet should be added to `opencode.jsonc`.

```json
{
  "mcp": {
    "hive-dev": {
      "type": "remote",
      "url": "https://hive-dev-mcp.naironai.com/mcp",
      "enabled": true
    }
  }
}
```

--------------------------------

### hive_routine_get

Source: https://docs.naironai.com/developers/tools-routines

Retrieves the full current configuration of a routine, including a computed next-run time. `nextRunAt` will be null if the routine is paused or archived.

```APIDOC
## hive_routine_get — read-only

### Description
Use this when you have a routine id and need its full current config plus a computed next-run time. `nextRunAt` is null whenever the routine isn't actually scheduled to fire next (paused or archived) rather than a stale timestamp.

### Arguments
#### Required
- **routineId** (string) - The routine to inspect.
```

--------------------------------

### Configure Windsurf MCP Server

Source: https://docs.naironai.com/developers/connecting

Configuration for Windsurf to connect to the hive-dev MCP server. Note the use of `serverUrl` instead of `url`. This JSON snippet should be added to `~/.codeium/windsurf/mcp_config.json`.

```json
{
  "mcpServers": {
    "hive-dev": {
      "serverUrl": "https://hive-dev-mcp.naironai.com/mcp"
    }
  }
}
```

--------------------------------

### Configure Cursor MCP Server

Source: https://docs.naironai.com/developers/connecting

Configuration for Cursor to connect to the hive-dev MCP server. This JSON snippet should be added to your `.cursor/mcp.json` file.

```json
{
  "mcpServers": {
    "hive-dev": {
      "url": "https://hive-dev-mcp.naironai.com/mcp"
    }
  }
}
```

--------------------------------

### Add Openclaw MCP Server

Source: https://docs.naironai.com/developers/connecting

Command to add the hive-dev MCP server for Openclaw, specifying the transport protocol and authentication method.

```bash
openclaw mcp add hive-dev --url https://hive-dev-mcp.naironai.com/mcp --transport streamable-http --auth oauth
```

--------------------------------

### Authenticate Openclaw MCP

Source: https://docs.naironai.com/developers/connecting

Command to log in and authenticate with the hive-dev MCP server for Openclaw after adding it.

```bash
openclaw mcp login hive-dev
```

--------------------------------

### Add Codex MCP Server

Source: https://docs.naironai.com/developers/connecting

Command to add the hive-dev MCP server for Codex. This is the first step in connecting Codex.

```bash
codex mcp add hive-dev --url https://hive-dev-mcp.naironai.com/mcp
```

--------------------------------

### hive_provider_list

Source: https://docs.naironai.com/developers/tools-connected-accounts

Lists native providers that are gate-able and checks if they are unlocked for the current workspace. Useful before connecting accounts for 'exa', 'firecrawl', or 'twitterapi'.

```APIDOC
## hive_provider_list

### Description
Use this when you need to know which native providers are gate-able and whether this workspace has already unlocked each one. Call this before `hive_account_connect` for any of `exa`, `firecrawl`, or `twitterapi` to check unlocked status first.

### Method
read-only

### Parameters
#### Query Parameters
- **limit** (integer, 1–50) - optional (default 20) - Max items per page.
- **cursor** (string) - optional - Pagination cursor.
```

--------------------------------

### Add Gemini MCP Server

Source: https://docs.naironai.com/developers/connecting

Use this command to add the hive-dev MCP server to Gemini. It specifies the transport protocol as HTTP.

```bash
gemini mcp add --transport http hive-dev https://hive-dev-mcp.naironai.com/mcp
```

--------------------------------

### hive_tool_list

Source: https://docs.naironai.com/developers/tools-grants

Discovers tools that are currently grantable to an agent, cross-referenced with the workspace's connected accounts. Returns grantable toolkits and specific connected accounts.

```APIDOC
## hive_tool_list

### Description
Discovers tools that are currently grantable to an agent, cross-referenced with the workspace's connected accounts. Returns grantable toolkits and specific connected accounts.

### Method
read-only

### Parameters
#### Query Parameters
- **limit** (integer, 1–50) - optional (default 20) - Max items per page.
- **cursor** (string) - optional - Pagination cursor.

### Response
#### Success Response
- **entries** (array) - A list of grantable tool entries.
  - **grantId** (string) - The ID to use for granting (e.g., "gmail" or "account:<id>").
  - **type** (string) - The type of entry ('toolkit' or 'account').

#### Response Example
```json
{
  "entries": [
    {
      "grantId": "gmail",
      "type": "toolkit"
    },
    {
      "grantId": "account:12345",
      "type": "account"
    }
  ]
}
```
```

--------------------------------

### Add Claude MCP Connector

Source: https://docs.naironai.com/developers/connecting

Use this command to add the hive-dev MCP server as a connector in Claude. Ensure you specify the correct scope and transport.

```bash
claude mcp add --scope user --transport http hive-dev https://hive-dev-mcp.naironai.com/mcp
```

--------------------------------

### hive_runtime_list

Source: https://docs.naironai.com/developers/tools-runtime

Lists available runtime environments in the caller's workspace. This is typically used before binding an agent to a runtime to find a valid environment ID.

```APIDOC
## hive_runtime_list

### Description
Lists available runtime environments in the caller's workspace. This is typically used before binding an agent to a runtime to find a valid environment ID.

### Method
read-only

### Parameters
#### Query Parameters
- **limit** (integer, 20–50) - Optional (default 25) - Max environments per page.
- **cursor** (string) - Optional - Pagination cursor.
```

--------------------------------

### Authenticate Codex MCP

Source: https://docs.naironai.com/developers/connecting

Command to log in and authenticate with the hive-dev MCP server for Codex after adding it.

```bash
codex mcp login hive-dev
```

--------------------------------

### hive_workspace_get

Source: https://docs.naironai.com/developers/tools-workspace

Retrieves the profile of the current workspace, including its name, slug, organization, website/region, and unlocked integration providers. This tool is always scoped to the user's credential's workspace and requires no arguments.

```APIDOC
## hive_workspace_get

### Description
Reads the workspace profile and its company context. Useful for understanding the environment before performing other actions.

### Arguments
None. This function always returns the workspace associated with the user's credential.

### Response Example
```json
{
  "name": "Example Corp",
  "slug": "example-corp",
  "organization": "Example Organization",
  "website": "https://example.com",
  "region": "US-East",
  "unlocked_integrations": [
    "integration_a",
    "integration_b"
  ]
}
```
```

--------------------------------

### hive_agent_get

Source: https://docs.naironai.com/developers/tools-agents

Retrieves an agent's full configuration, including persona, role, purpose, status, responsibilities, and a readiness summary.

```APIDOC
## hive_agent_get

### Description
Use this when you need one agent's full configuration plus whether it's actually usable yet.

### Parameters
#### Query Parameters
- **agentId** (string) - Required - From a prior hive_agent_create response or a hive_agent_list entry.
```

--------------------------------

### hive_runtime_bind

Source: https://docs.naironai.com/developers/tools-runtime

Binds an agent to a specific runtime environment, setting the sandbox for its next execution turns. Both the agent and runtime environment must exist in the caller's workspace.

```APIDOC
## hive_runtime_bind

### Description
Binds an agent to a specific runtime environment, setting the sandbox for its next execution turns. Both the agent and runtime environment must exist in the caller's workspace.

### Method
Updates the agent's default runtime and its runtime-binding record together.

### Parameters
#### Request Body
- **agent_id** (string) - Required - The agent to bind, from an agent-listing tool.
- **runtime_environment_id** (string) - Required - The runtime environment to bind to, from `hive_runtime_list`.
```

--------------------------------

### hive_channel_create

Source: https://docs.naironai.com/developers/tools-channels

Creates a new Hive channel. This is the only way to create a channel from hive-dev. The channel's kind determines what can post into it.

```APIDOC
## hive_channel_create

### Description
Use this when you need a new Hive channel to post into or to point a routine at — there is no other way to create one from hive-dev today.

### Method
POST (assumed)

### Endpoint
/channels

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - Lowercase letters, digits, hyphens only, unique in the workspace, e.g. "product-launch". Max 21 chars.
- **kind** (enum: topic / rolling) - Optional (default "topic") - "topic" channels are the only kind a routine can post into. "rolling" channels are for casual human chat only.
- **topic** (string, max 200 chars) - Optional - 0-200 char description — topic-kind channels only. Rejected together with `kind: "rolling"`.
- **initialMemberIds** (array of string, max 50) - Optional - Member ids to add at creation, in addition to you. Every id must already belong to this workspace.
- **teamId** (string) - Optional - Team id to group this channel under in the sidebar. Omit to leave it ungrouped.

### Request Example
```json
{
  "name": "product-launch",
  "kind": "topic",
  "topic": "Discussions about the upcoming product launch",
  "initialMemberIds": ["user-123", "user-456"],
  "teamId": "team-abc"
}
```

### Response
#### Success Response (200)
- **channelId** (string) - The ID of the newly created channel.
- **name** (string) - The name of the channel.
- **kind** (string) - The kind of the channel (topic or rolling).
- **topic** (string) - The topic of the channel (if provided).
- **initialMemberIds** (array of string) - The IDs of the initial members.
- **teamId** (string) - The team ID the channel belongs to (if provided).

#### Response Example
```json
{
  "channelId": "chan-xyz789",
  "name": "product-launch",
  "kind": "topic",
  "topic": "Discussions about the upcoming product launch",
  "initialMemberIds": ["user-123", "user-456"],
  "teamId": "team-abc"
}
```
```

--------------------------------

### hive_skill_get

Source: https://docs.naironai.com/developers/tools-skills

Retrieves the full content of a skill, including its description, body, referenced tool IDs, and archived state, given its unique skill ID.

```APIDOC
## hive_skill_get

### Description
Use this when you have a skill id and need its full content — description, body, toolIds, and archived state.

### Method
`hive_skill_get`

### Parameters
#### Arguments
- **skillId** (string) - required - From `hive_skill_create`'s or `hive_skill_list`'s response.
```

--------------------------------

### hive_skill_create

Source: https://docs.naironai.com/developers/tools-skills

Authors a new reusable skill in the workspace. This operation does not attach the skill to any agent; use `hive_skill_attach` for that purpose. The skill name must be unique within the workspace.

```APIDOC
## hive_skill_create

### Description
Use this when you need to author a new reusable skill (instructions + tool references) in the workspace. This does not attach it to any agent — call `hive_skill_attach` afterward for that.
`name` must be unique within the workspace — reusing an existing name is rejected, not overwritten (call `hive_skill_list` first if unsure). `toolIds` is informational only — it does not itself grant tool access; use Tool Grants for that.

### Method
`hive_skill_create`

### Parameters
#### Arguments
- **name** (string, max 200 chars) - required - Short, unique-in-workspace name, e.g. "qualify-lead".
- **description** (string, max 2000 chars) - required - 1-2 sentences on what this skill does.
- **body** (string) - required - The skill's full instructions text.
- **toolIds** (array of string) - optional - Tool identifiers this skill references — informational only.
```

--------------------------------

### hive_account_list

Source: https://docs.naironai.com/developers/tools-connected-accounts

Lists all connected accounts for the current workspace. Useful for checking existing connections before granting tools to agents or disconnecting accounts.

```APIDOC
## hive_account_list

### Description
Use this when you need to see every connected account for this workspace — check this before granting a tool to an agent or before disconnecting something.

### Method
read-only

### Parameters
#### Query Parameters
- **limit** (integer, 1–50) - optional (default 20) - Max items per page.
- **cursor** (string) - optional - Pagination cursor.
```

--------------------------------

### hive_skill_list

Source: https://docs.naironai.com/developers/tools-skills

Lists all skills authored in the current workspace, including archived skills. This is useful for checking if a skill name is already in use before creating a new one or for finding a `skillId` to use with other skill management tools.

```APIDOC
## hive_skill_list

### Description
Use this when you need to see all skills authored in this workspace — e.g. before creating one (to check a name isn't taken), or to find a `skillId` for the other tools in this group. Includes archived skills — check each entry's `archived` field before attaching one to an agent.

### Method
`hive_skill_list`

### Parameters
#### Arguments
- **limit** (integer, 20–50) - optional (default 20) - Max skills per page.
- **cursor** (string) - optional - Pagination cursor. Omit for the first page.
```

--------------------------------

### hive_channel_list

Source: https://docs.naironai.com/developers/tools-channels

Lists all channels in the workspace, optionally filtering by kind or searching by name. Useful for finding a channel's ID.

```APIDOC
## hive_channel_list — read-only

### Description
Use this when you need to see every channel in this workspace (with its kind — topic vs. rolling) or to find a channel's id from its name.

### Method
GET (assumed)

### Endpoint
/channels

### Parameters
#### Path Parameters
None

#### Query Parameters
- **limit** (integer) - Optional (default 25) - Max channels per page. Between 1 and 50.
- **cursor** (string) - Optional - Pagination cursor.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **channels** (array of objects) - A list of channels.
  - **channelId** (string) - The ID of the channel.
  - **name** (string) - The name of the channel.
  - **kind** (string) - The kind of the channel (topic or rolling).
- **nextCursor** (string) - The cursor for the next page of results, if any.

#### Response Example
```json
{
  "channels": [
    {
      "channelId": "chan-xyz789",
      "name": "product-launch",
      "kind": "topic"
    },
    {
      "channelId": "chan-abc123",
      "name": "general-chat",
      "kind": "rolling"
    }
  ],
  "nextCursor": "some-pagination-token"
}
```
```

--------------------------------

### hive_grant_create

Source: https://docs.naironai.com/developers/tools-grants

Grants an agent access to one or more tools. This operation unions new grants with the agent's existing grants.

```APIDOC
## hive_grant_create

### Description
Grants an agent access to one or more tools. This operation unions new grants with the agent's existing grants. All specified toolIds must correspond to tools with already connected accounts.

### Method
create

### Parameters
#### Request Body
- **agentId** (string) - required - The agent to grant tools to.
- **toolIds** (array of string, min 1) - required - Grant IDs from `hive_tool_list`'s `grantId` field (e.g., "gmail" or "account:<id>").

### Request Example
```json
{
  "agentId": "agent-abc",
  "toolIds": ["gmail", "account:12345"]
}
```

### Response
#### Success Response (200)
- **granted_tool_ids** (array of string) - The list of tool IDs successfully granted.
- **not_found** (array of string) - The list of tool IDs that were not found or could not be granted.

#### Response Example
```json
{
  "granted_tool_ids": ["gmail"],
  "not_found": ["account:67890"]
}
```
```

--------------------------------

### hive_routine_create

Source: https://docs.naironai.com/developers/tools-routines

Creates a new scheduled, recurring piece of agent work. If a routine with the same agentId and title already exists, it will be updated in place. Newly created routines are active immediately.

```APIDOC
## hive_routine_create

### Description
Use this when you need a new scheduled, recurring piece of agent work. `agentId` and `channelId` must already exist in this workspace. `channelId` **must** be a "topic"-kind channel — a "rolling" channel is rejected outright (see Channels).
**Idempotent by (agentId, title):** calling this again with the same pair updates that routine in place (`created: false`) instead of erroring or duplicating — this is also the only way to reactivate a previously paused/archived routine from this tool surface.
A newly created routine is active immediately — call `hive_routine_run` right after creating it to prove it actually works before its first real scheduled fire.

### Arguments
#### Required
- **agentId** (string) - The agent this routine runs as.
- **channelId** (string) - The channel it posts into. Must be topic-kind.
- **title** (string, 2–80 chars) - Short title. Together with `agentId`, this is the idempotency key.
- **prompt** (string, 10–6000 chars) - The instruction given to the agent each time this routine fires.
- **schedule** (object) - See the shared schedule shape below.

#### Optional
- **notifyMemberIds** (array of string, max 50) - Members to @mention when the routine posts its result.

### Shared Schedule Object
Field | Type | Required | Description
---|---|---|---
`kind` | enum: hourly / daily / weekdays / weekly | required | "hourly" fires every hour (ignores timeOfDay/dayOfWeek). "daily" fires every day at `timeOfDay`. "weekdays" fires Mon–Fri at `timeOfDay`. "weekly" fires once a week on `dayOfWeek` at `timeOfDay`.
`timeOfDay` | string, "HH" | optional (default "09") | Local time. Used by every kind except hourly.
`dayOfWeek` | number, 0–6 | optional (default 1 = Monday) | Only used when kind is "weekly".
`timezone` | string (IANA name) | required | e.g. "America/New_York" or "UTC". An unrecognized name silently falls back to UTC.
```

--------------------------------

### hive_agent_create

Source: https://docs.naironai.com/developers/tools-agents

Creates a new AI employee (agent) in the workspace. This operation is idempotent based on the agent's role.

```APIDOC
## hive_agent_create

### Description
Use this to add a new AI employee to the workspace. The operation is idempotent; calling it with a role that already exists returns the existing agent without duplication.

### Parameters
- **reportsTo** (string) - Optional - The agent ID representing the reporting line for this agent. Used for escalation routing and tool approval workflows.
- **responsibilities** (array) - Optional - A list of responsibilities, each containing a `description` and a `status` (live, in_progress, testing, planned, or blocked).
```

--------------------------------

### List Agent Turns

Source: https://docs.naironai.com/developers/tools-observability

Find agent turns by ID, check recent activity, or triage failures. Can be filtered by agent ID or status. Omit `agentId` for workspace-wide listing.

```python
hive_turn_list(agentId="agent_xyz", status="failed", limit=10)
```

```python
hive_turn_list(limit=50, cursor="cursor_123")
```

--------------------------------

### hive_grant_list

Source: https://docs.naironai.com/developers/tools-grants

Reads the list of tools an agent currently has access to. If the agent is unrestricted, it indicates `restricted: false` with an empty `tool_ids` list.

```APIDOC
## hive_grant_list

### Description
Reads the list of tools an agent currently has access to. If the agent is unrestricted, it indicates `restricted: false` with an empty `tool_ids` list.

### Method
read-only

### Parameters
#### Query Parameters
- **agentId** (string) - required - The agent to check.
- **limit** (integer, 1–50) - optional (default 20) - Max items per page (only relevant when the agent has an explicit, restricted grant list).
- **cursor** (string) - optional - Pagination cursor.

### Response
#### Success Response
- **restricted** (boolean) - Indicates if the agent has a restricted tool list.
- **tool_ids** (array of string) - A list of grant IDs the agent has access to.

#### Response Example
```json
{
  "restricted": false,
  "tool_ids": []
}
```
```

--------------------------------

### hive_routine_run

Source: https://docs.naironai.com/developers/tools-routines

Executes a routine immediately, bypassing its schedule. This triggers the actual dispatch pipeline. Paused routines can be run manually. If a run is in progress, it returns the existing run unless `allowConcurrent` is true.

```APIDOC
## hive_routine_run

### Description
Use this when you need to fire a routine once, right now, without waiting for its schedule. This triggers the same real dispatch pipeline the schedule itself uses — it is not a dry run.

### Method
Not applicable (SDK/Internal function call)

### Parameters
#### Arguments
- **routineId** (string) - required - The routine to run now.
- **allowConcurrent** (boolean) - optional (default false) - If true, starts a new run even if one's already in progress.

### Returns
Returns `turnId` alongside agent/channel info. Use `hive_turn_get(turnId)` for status/output, or `hive_message_list(channelId)` to read the actual reply.
```

--------------------------------

### hive_member_list

Source: https://docs.naironai.com/developers/tools-workspace

Lists all human members within the current workspace. This tool is useful for tasks like scheduling or understanding reporting structures. It supports pagination.

```APIDOC
## hive_member_list

### Description
Reads the roster of human members in the current workspace. Useful for looking up member details like timezones or reporting lines.

### Arguments
#### Query Parameters
- **limit** (integer, 1–100) - Optional (default 30) - Max members to return in this page.
- **cursor** (string) - Optional - Pagination cursor from a previous call's `next_cursor`. Omit to start from the first page.

### Response Example
```json
{
  "members": [
    {
      "id": "member_123",
      "name": "Alice Smith",
      "email": "alice.smith@example.com",
      "timezone": "America/New_York"
    },
    {
      "id": "member_456",
      "name": "Bob Johnson",
      "email": "bob.johnson@example.com",
      "timezone": "Europe/London"
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_abcde12345"
}
```
```

--------------------------------

### hive_provider_unlock

Source: https://docs.naironai.com/developers/tools-connected-accounts

Unlocks gated providers ('exa', 'firecrawl', 'twitterapi') before they can be connected. Essential for gated providers; attempting to connect without unlocking first will fail.

```APIDOC
## hive_provider_unlock

### Description
Use this when a consultant needs to unlock a gated provider (`exa`, `firecrawl`, or `twitterapi`) before connecting it — calling `hive_account_connect` for one of these providers **before** calling this tool will fail, naming this tool as the fix.

### Method
N/A (Tool function)

### Parameters
#### Request Body
- **providerIds** (array of enum: exa / firecrawl / twitterapi) - required, min 1 - One or more gated provider ids to unlock.
```

--------------------------------

### hive_routine_list

Source: https://docs.naironai.com/developers/tools-routines

Retrieves a list of all routines in the workspace, including active, paused, and archived routines. Can be used to find a routine ID by its title.

```APIDOC
## hive_routine_list — read-only

### Description
Use this when you need to see every routine in this workspace — active, paused, and archived alike — or to find a routineId by title.

### Arguments
#### Optional
- **limit** (integer, 20–50) - Max routines per page. (default 20)
- **cursor** (string) - Pagination cursor.
```

--------------------------------

### hive_turn_list

Source: https://docs.naironai.com/developers/tools-observability

Lists agent turns, useful for finding `turnId`, checking recent activity, or triaging failures. Can be filtered by `agentId`, `status`, and paginated.

```APIDOC
## hive_turn_list

### Description
Use this when you need to find a `turnId`, check an agent's recent activity, or triage failures across the workspace. `agentId` is optional — omit it to list turns workspace-wide across all agents. Most-recent-first.

### Method
read-only

### Parameters
#### Query Parameters
- **agentId** (string) - optional - Restrict to one agent's turns. Omit for workspace-wide.
- **status** (enum: queued / blocked / running / completed / failed / cancelled) - optional - Restrict to turns in exactly this status.
- **limit** (integer, 1–50) - optional (default 25) - Max turns per page.
- **cursor** (string) - optional - Pagination cursor.
```

--------------------------------

### hive_agent_list

Source: https://docs.naironai.com/developers/tools-agents

Retrieves a list of all agents in the workspace, including lightweight status and skill information.

```APIDOC
## hive_agent_list

### Description
Use this when you need to see all agents in the workspace.

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max agents per page (20–50, default 20).
- **cursor** (string) - Optional - Pagination cursor from a previous call's next_cursor.
```

--------------------------------

### hive_turn_get

Source: https://docs.naironai.com/developers/tools-observability

Retrieves the full status, final output, error, and tool-call history for a specific agent turn. It can poll for a terminal status if `maxWaitMs` is provided.

```APIDOC
## hive_turn_get

### Description
Use this when you need the full status, final output, error, and tool-call history for one agent turn (a single chat run) you already have the id for. By default returns the current status immediately. Pass `maxWaitMs` > 0 to poll internally until the turn reaches a terminal status.

### Method
read-only

### Parameters
#### Query Parameters
- **turnId** (string) - required - From `hive_turn_list`.
- **maxWaitMs** (integer, 0–20000) - optional - How long to poll for a terminal status before returning. 0 (default) returns immediately. Hard cap 20000ms.
```

--------------------------------

### hive_audit_list

Source: https://docs.naironai.com/developers/tools-observability

Provides the audit trail for the calling credential, including connection and tool-call entries. Useful for auditing and debugging.

```APIDOC
## hive_audit_list

### Description
Use this when you want **your own** hive-dev credential's audit trail — both connection entries (one per time this credential was presented) and tool-call entries (one per individual tool invocation made over that connection). Each entry's `source` field ("connection" or "tool_call") tells you which kind it is. Tool-call entries additionally carry `argsSummary`, `resultSummary`, `durationMs`, and — for a few write tools — `diffSummary` (exactly what changed). Useful for confirming your key is being accepted, diagnosing "invalid credential" failures, or auditing exactly what a prior tool call did. No workspace/credential argument exists — it always returns only the calling credential's own history, never another credential's.

### Method
read-only

### Parameters
#### Query Parameters
- **limit** (integer, 1–50) - optional (default 25) - Max entries per page.
- **cursor** (string) - optional - Pagination cursor.
```

--------------------------------

### hive_channel_get

Source: https://docs.naironai.com/developers/tools-channels

Retrieves the current details of a specific channel, including its kind, name, topic, and member visibility, using its channel ID.

```APIDOC
## hive_channel_get — read-only

### Description
Use this when you have a channel id and need its current details — kind, name, topic, and member visibility.

### Method
GET (assumed)

### Endpoint
/channels/{channelId}

### Parameters
#### Path Parameters
- **channelId** (string) - Required - From `hive_channel_create` or `hive_channel_list`.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **channelId** (string) - The ID of the channel.
- **name** (string) - The name of the channel.
- **kind** (string) - The kind of the channel (topic or rolling).
- **topic** (string) - The topic of the channel.
- **memberVisibility** (string) - The visibility settings for channel members.

#### Response Example
```json
{
  "channelId": "chan-xyz789",
  "name": "product-launch",
  "kind": "topic",
  "topic": "Discussions about the upcoming product launch",
  "memberVisibility": "public"
}
```
```

--------------------------------

### hive_routine_update

Source: https://docs.naironai.com/developers/tools-routines

Updates an existing routine's schedule, prompt, or notification list. Can also be used to change the routine's status between active and paused. Cannot be used to rename a routine or reassign its agent/channel.

```APIDOC
## hive_routine_update

### Description
Use this when you need to reschedule a routine, edit its prompt or notify list, or flip its status between active and paused. **Not** for renaming a routine or reassigning its agent/channel — use `hive_routine_create` with a new title for that.
The routine must not be archived — archived is a terminal state for this surface; archived routines reject every edit here, including status. The only way back from archived is `hive_routine_create` with the exact same agentId + title.
Every field is optional and independently omittable. Passing `schedule` replaces the whole object — include every field you want kept. `status` accepts "active" or "paused" only (not "archived" — use `hive_routine_delete`).

### Arguments
#### Required
- **routineId** (string) - The routine to update.

#### Optional
- **prompt** (string, 10–6000 chars) - New instruction.
- **schedule** (object) - New schedule — replaces the whole object.
- **notifyMemberIds** (array of string, max 50) - New full notify list — replaces the existing one.
- **status** (enum: active / paused) - Set directly. "active" reactivates (recomputes nextRunAt); "paused" stops without archiving.
```

--------------------------------

### Trigger Agent in Test Channel

Source: https://docs.naironai.com/developers/tools-observability

This operation allows you to trigger a specific agent within a designated test channel. You can provide a message and configure the maximum wait time for a response.

```APIDOC
## POST /trigger

### Description
Triggers an agent in a specified test channel with a given message and optional wait time.

### Method
POST

### Endpoint
/trigger

### Parameters
#### Request Body
- **agentId** (string) - Required - The agent to trigger — must already exist.
- **channelId** (string) - Required - A designated test channel — name must start with "test-" or be exactly "test".
- **message** (string, max 4000 chars) - Required - The ask, exactly as a human would type it. If it doesn't already contain "@", the agent's @mention is prepended automatically.
- **maxWaitMs** (integer, 0–20000) - Optional - 0 (default) returns immediately with the initial status. > 0 waits inline (hard-capped at 20000ms); on timeout the turn is forced to "failed" and the execution slot is released.

### Request Example
{
  "agentId": "agent-123",
  "channelId": "test-channel-abc",
  "message": "What is the weather today?",
  "maxWaitMs": 5000
}

### Response
#### Success Response (200)
- **status** (string) - The status of the triggered agent turn.
- **turnId** (string) - The ID of the turn.

#### Response Example
{
  "status": "processing",
  "turnId": "turn-xyz789"
}
```

--------------------------------

### Read Actual Message Content

Source: https://docs.naironai.com/developers/tools-observability

Access the actual message content of a channel or topic to verify agent replies. Provide exactly one of `channelId` or `topicId`.

```python
hive_message_list(channelId="channel_def")
```

```python
hive_message_list(topicId="topic_ghi", limit=10)
```

--------------------------------

### hive_message_list

Source: https://docs.naironai.com/developers/tools-observability

Retrieves the actual message content of a channel or topic. Requires either `channelId` or `topicId` to be provided.

```APIDOC
## hive_message_list

### Description
Use this when you need the actual message **content** of a channel or topic — e.g. to judge whether an agent's reply was actually correct, not just that its turn completed. `hive_turn_get` only tells you a turn finished; this tool reads what was really said. Provide **exactly one** of `channelId` or `topicId` — providing both, or neither, is rejected.

### Method
read-only

### Parameters
#### Query Parameters
- **channelId** (string) - one of these two required - A channel id. Provide this OR `topicId`, not both.
- **topicId** (string) - one of these two required - A topic id. Provide this OR `channelId`, not both.
- **limit** (integer, 1–50) - optional (default 25) - Max messages per page.
- **cursor** (string) - optional - Pagination cursor.
```

--------------------------------

### hive_account_get

Source: https://docs.naironai.com/developers/tools-connected-accounts

Retrieves the full details for a specific connected account ID, including provider, status, scopes, and connection time.

```APIDOC
## hive_account_get

### Description
Use this when you need the full detail (provider, status, scopes, connected-at) for one already-known connected account id. Call `hive_account_list` first if you don't already have the accountId.

### Method
read-only

### Parameters
#### Query Parameters
- **accountId** (string) - required - From `hive_account_list` or `hive_account_connect`'s `account_id`.
```

--------------------------------

### hive_test_trigger

Source: https://docs.naironai.com/developers/tools-observability

Triggers an end-to-end agent run in a safe, throwaway test channel. Can wait inline for a terminal status using `maxWaitMs`.

```APIDOC
## hive_test_trigger

### Description
Use this when you need to actually run an agent end-to-end in a safe, throwaway **test** channel and see whether it works — the same trigger→turn mechanics production chat uses, minus the risk of posting into a real working channel. `channelId` **must** be a channel whose name starts with "test-" (or is exactly "test"). Pass `maxWaitMs` > 0 to wait inline for a terminal status instead of polling yourself.

### Method
(Implied write operation, specific method not detailed)

### Parameters
#### Query Parameters
- **channelId** (string) - required - Must be a channel whose name starts with "test-" or is exactly "test".
- **maxWaitMs** (integer) - optional - Wait inline for a terminal status instead of polling yourself. A timeout in that wait always resolves to an explicit "failed" status.
```

--------------------------------

### Audit Hive-Dev Credentials

Source: https://docs.naironai.com/developers/tools-observability

View the audit trail for your hive-dev credential, including connection and tool-call entries. This tool always returns only the calling credential's history.

```python
hive_audit_list(limit=50)
```

--------------------------------

### hive_skill_update

Source: https://docs.naironai.com/developers/tools-skills

Edits an existing skill's description, body, or referenced tool IDs. This is a partial patch, meaning only the fields provided will be updated. It does not affect agent attachments or un-archive a skill.

```APIDOC
## hive_skill_update

### Description
Use this when you need to edit an existing skill's description, body, or toolIds. Partial patch — omit any field you don't want to change. Does not touch which agents this skill is attached to, and does not un-archive an archived skill — each is a separate concern (see `hive_skill_attach`/`_detach` and `hive_skill_delete` below).

### Method
`hive_skill_update`

### Parameters
#### Arguments
- **skillId** (string) - required - The skill to update.
- **description** (string, max 2000 chars) - optional - New description.
- **body** (string) - optional - New full instructions text.
- **toolIds** (array of string) - optional - New list — replaces the old one entirely.
```

--------------------------------

### hive_skill_delete

Source: https://docs.naironai.com/developers/tools-skills

Archives a skill, marking it as inactive. This is a soft delete; the skill record and its content are preserved and can still be referenced by agents. It does not detach the skill from any agents (use `hive_skill_detach` for that).

```APIDOC
## hive_skill_delete

### Description
Use this when you need to retire a skill from active use. This is a soft delete : it sets `archived` to true — the skill row, its content, and any agent still referencing it in their skillIds are all preserved. It never permanently deletes anything and does not detach the skill from any agent that already has it (call `hive_skill_detach` separately for that).

### Method
`hive_skill_delete`

### Parameters
#### Arguments
- **skillId** (string) - required - The skill to archive.
```

--------------------------------

### hive_skill_attach

Source: https://docs.naironai.com/developers/tools-skills

Attaches an authored skill to a specific agent, enabling the agent to use the skill. This is the only operation that modifies an agent's skill list. If the skill is already attached to the agent, it returns `alreadyAttached: true` and makes no changes.

```APIDOC
## hive_skill_attach

### Description
Use this when you need to attach an already-authored skill to an agent so that agent can actually use it — this is the only tool that changes an agent's skillIds; `hive_skill_create` does not do this by itself.
Safe to call again with the same pair: if already attached, returns `alreadyAttached: true` and makes no change — never duplicates.

### Method
`hive_skill_attach`

### Parameters
#### Arguments
- **skillId** (string) - required - The skill to attach.
- **agentId** (string) - required - The agent to attach it to.
```

--------------------------------

### hive_routine_delete

Source: https://docs.naironai.com/developers/tools-routines

Removes a routine from scheduled rotation. This is a soft delete, preserving the routine's configuration and run history. Can archive or pause a routine.

```APIDOC
## hive_routine_delete — destructive

### Description
Use this when you need to take a routine out of scheduled rotation. This is **always a soft action** — the row, its config, and full run history are all preserved; nothing is ever hard-deleted.
Choose `action: "archive"` (default) for the permanent, "this routine is done" case. Choose `action: "pause"` for a temporary stop. Getting back from "paused" is direct via `hive_routine_update` with `status: "active"`. Getting back from "archived" (terminal) only works via `hive_routine_create`'s idempotent upsert.

### Arguments
#### Optional
- **action** (enum: archive / pause) - Defaults to "archive". "archive" is a permanent state. "pause" can be reverted with `hive_routine_update`.
```

--------------------------------

### hive_agent_update

Source: https://docs.naironai.com/developers/tools-agents

Updates an existing agent's persona, role, purpose, responsibilities, reportsTo, or avatar using a partial patch.

```APIDOC
## hive_agent_update

### Description
Use this when you need to edit an existing agent's persona, role, purpose, responsibilities, reportsTo, or avatar.

### Parameters
#### Request Body
- **agentId** (string) - Required - The agent to update.
- **role** (string) - Optional - New role identifier.
- **purpose** (string) - Optional - New purpose text.
- **persona** (object) - Optional - New persona object.
- **responsibilities** (array) - Optional - Complete replacement for the ordered responsibilities array.
- **avatarUrl** (string) - Optional - Direct https image link.
- **reportsTo** (string) - Optional - New reporting-line reference.
```

--------------------------------

### hive_grant_revoke

Source: https://docs.naironai.com/developers/tools-grants

Removes one or more tools from an agent's grants. This operation requires the agent to have an existing, explicit grant list.

```APIDOC
## hive_grant_revoke

### Description
Removes one or more tools from an agent's grants. This operation requires the agent to have an existing, explicit grant list. Requested IDs that were never granted are ignored.

### Method
destructive

### Parameters
#### Request Body
- **agentId** (string) - required - The agent to revoke tools from.
- **toolIds** (array of string, min 1) - required - Exact grant IDs to remove.

### Request Example
```json
{
  "agentId": "agent-abc",
  "toolIds": ["gmail"]
}
```

### Response
#### Success Response (200)
- **revoked_tool_ids** (array of string) - The list of tool IDs successfully revoked.
- **not_found** (array of string) - The list of tool IDs that were not found or not granted.

#### Response Example
```json
{
  "revoked_tool_ids": ["gmail"],
  "not_found": ["calendar"]
}
```
```

--------------------------------

### hive_account_disconnect

Source: https://docs.naironai.com/developers/tools-connected-accounts

Permanently disconnects a connected account. This action revokes the account with the provider and deletes the record; it is irreversible.

```APIDOC
## hive_account_disconnect

### Description
Use this when you need to permanently disconnect a connected account. This revokes it with the provider, then deletes the row — reconnecting afterward is cheap, but this itself is **not reversible** ; it is not a soft delete.

### Method
destructive

### Parameters
#### Request Body
- **accountId** (string) - required - The account to disconnect.
```

--------------------------------

### hive_agent_delete

Source: https://docs.naironai.com/developers/tools-agents

Performs a soft delete on an agent, setting its status to inactive while preserving its data.

```APIDOC
## hive_agent_delete

### Description
Use this when you need to remove an agent from active use. This is a soft delete.

### Parameters
#### Request Body
- **agentId** (string) - Required - The agent to deactivate.
```

--------------------------------

### hive_skill_detach

Source: https://docs.naironai.com/developers/tools-skills

Removes a skill from an agent's list of associated skills. This operation does not affect the skill itself, which remains available for attachment to other agents. If the skill is not currently attached to the agent, it returns `wasAttached: false` and makes no changes.

```APIDOC
## hive_skill_detach

### Description
Use this when you need to remove a skill from one agent's skillIds — e.g. undoing a `hive_skill_attach` mistake, or reassigning who uses a skill. The skill record itself is untouched — it still exists and can be attached to this or any other agent later.
Safe to call again: if not currently attached, returns `wasAttached: false` and makes no change.

### Method
`hive_skill_detach`

### Parameters
#### Arguments
- **skillId** (string) - required - The skill to detach.
- **agentId** (string) - required - The agent to detach it from.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.