> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool sets

> Pre-built tool sets for building Guild agents.

Import any tool set and spread it into your agent's `tools` object. Each tool set is a plain object whose keys are tool names — you can spread multiple sets together, or use `pick` / `omit` to narrow them.

```typescript theme={null}
import {
  guildTools,
  userInterfaceTools,
  pick,
  omit,
} from "@guildai/agents-sdk";
import { gitHubTools } from "@guildai-services/guildai~github";

const tools = {
  ...guildTools,
  ...userInterfaceTools,
  ...pick(gitHubTools, ["github_repos_get", "github_pulls_list"]),
};
```

## guildTools

Platform tools that give agents access to the Guild API — workspaces, agents, triggers, credentials, workspace context, and more. Including `guildTools` also enables [`task.guild`](/sdk/task-object#taskguild--platform-operations).

```typescript theme={null}
import { guildTools } from "@guildai/agents-sdk";

const tools = { ...guildTools };
```

### Tool naming

Every guild tool is named `guild_{endpoint}` where `{endpoint}` is the GuildService method name. For example, `get_workspace_contexts` becomes `guild_get_workspace_contexts`.

### Tools vs hooks

Most guild tools are synchronous: the runtime calls the Guild API and returns the result immediately. A few are **hooks** — they may suspend the agent while waiting for user action or an external callback:

| Hook tool                        | What it waits for                                      |
| -------------------------------- | ------------------------------------------------------ |
| `guild_agent_install_request`    | User approves agent installation into the workspace    |
| `guild_credentials_request`      | User completes an OAuth flow for a third-party service |
| `guild_experimental_fetch_async` | HTTP response arrives asynchronously                   |
| `guild_sleep`                    | Timer expires                                          |

Your agent does not need to handle hook suspension explicitly; the runtime persists the agent's state, and `onToolResults` / automatic resumption continues where you left off.

### Full endpoint listing

All 55 `guild_*` tools correspond 1-to-1 with the GuildService methods documented in the [Task object — `task.guild`](/sdk/task-object#taskguild--platform-operations) section, organized into these groups:

| Group                 | Example tools                                                                           |
| --------------------- | --------------------------------------------------------------------------------------- |
| Current user          | `guild_get_me`, `guild_get_my_workspaces`, `guild_get_my_organizations`                 |
| Users                 | `guild_search_users`, `guild_get_user`                                                  |
| Agents                | `guild_list_agents`, `guild_create_agent`, `guild_search_agent`, `guild_get_agent_code` |
| Agent likes           | `guild_create_agent_like`, `guild_list_agent_likers`                                    |
| Organizations         | `guild_get_organization`, `guild_get_organization_workspaces`                           |
| Workspaces            | `guild_get_workspace`, `guild_get_workspace_contexts`, `guild_create_workspace_context` |
| Triggers              | `guild_create_workspace_trigger`, `guild_activate_trigger`, `guild_deactivate_trigger`  |
| Sessions & tasks      | `guild_get_session`, `guild_get_task_workspace_agents`                                  |
| LLM usage             | `guild_get_daily_llm_usage`, `guild_get_hourly_llm_usage`                               |
| Credentials & install | `guild_credentials_request`, `guild_agent_install_request`                              |
| Flow control & HTTP   | `guild_sleep`, `guild_experimental_fetch`, `guild_experimental_fetch_async`             |

See the [full tables](/sdk/task-object#taskguild--platform-operations) for descriptions of every endpoint.

Both `guild_experimental_fetch` and `guild_experimental_fetch_async` accept an optional `max_bytes` integer parameter that truncates non-JSON text responses to at most that many UTF-8 bytes (appending a `[Response truncated to <max_bytes> bytes]` marker), while returning JSON responses fully intact. See [`task.guild`](/sdk/task-object#taskguild--platform-operations) for details.

## guildai\~get\_self

`guildai~get_self` is a built-in internal platform tool that returns the calling agent's own identity — agent info, running version, session, and workspace — in a single call. No tool set import or credential configuration is required; the runtime provides it automatically to every running agent.

```typescript theme={null}
const self = await task.tools.guildai_get_self({})
```

See [Agent self-identification](/sdk/get-self) for the full response payload and attribution examples.

## userInterfaceTools

Tools for interacting with the user. Including this set also enables [`task.ui`](/sdk/task-object#taskui--user-interaction).

| Tool        | Description                                                                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ui_prompt` | Ask the user a question and block until they respond (hook — suspends execution). The response can include an optional `attachments` array of base64-encoded images or PDFs |
| `ui_notify` | Fire-and-forget notification, progress update, or error message                                                                                                             |
| `ui_ping`   | Health-check the UI surface (mostly for testing)                                                                                                                            |

```typescript theme={null}
import { userInterfaceTools } from "@guildai/agents-sdk";
```

<Tip>
  `llmAgent` wires `ui_notify` internally so progress notifications (`task.ui.notify()`) work, but hides it from the model's tool definitions unless you explicitly add `ui_notify` (or `userInterfaceTools`) to the agent's `tools`. Add `userInterfaceTools` explicitly when an `llmAgent` needs `ui_prompt` or `ui_ping`, and include them in coded agents that need user interaction.
</Tip>

## consoleTools

Debug and diagnostic logging.

| Tool          | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `console_log` | Log a message at a given level (`debug`, `info`, `warn`, `error`) |

```typescript theme={null}
import { consoleTools } from "@guildai/agents-sdk";
```

`task.console` is always available regardless of whether `consoleTools` is included. Include `consoleTools` in `llmAgent` definitions to give the LLM access to debug logging.

## noTools

An explicit empty tool set. Useful when an agent deliberately needs no tools — makes the intent clear instead of passing `{}`.

```typescript theme={null}
import { noTools } from "@guildai/agents-sdk";

export default agent({
  description: "Returns the input unchanged.",
  inputSchema,
  outputSchema,
  tools: noTools,
  run: async (input) => input,
});
```

## Service integrations

Third-party service tools are imported from their own `@guildai-services/*` packages. Add them to `dependencies` in your agent's `package.json`.

| Service      | Import                                                                      |
| ------------ | --------------------------------------------------------------------------- |
| GitHub       | `import { gitHubTools } from "@guildai-services/guildai~github"`            |
| Azure DevOps | `import { azureDevOpsTools } from "@guildai-services/guildai~azure-devops"` |
| Confluence   | `import { confluenceTools } from "@guildai-services/guildai~confluence"`    |
| Cypress      | `import { cypressTools } from "@guildai-services/guildai~cypress"`          |
| New Relic    | `import { newrelicTools } from "@guildai-services/guildai~newrelic"`        |
| TestRail     | `import { testrailTools } from "@guildai-services/guildai~testrail"`        |

Credentials are configured at the organization level in **Settings > Credentials** at [app.guild.ai](https://app.guild.ai) using either OAuth or an API token, depending on the service configuration.

All tools authenticate automatically through the workspace's connected accounts.

For tools backed by a Model Context Protocol server instead of a first-party integration, see [MCP integrations](/sdk/mcp-integrations) — these packages follow a different naming convention.

## Selecting specific tools

Use `pick` to cherry-pick or `omit` to exclude specific tools from a set:

```typescript theme={null}
import {
  pick,
  omit,
  guildTools,
  userInterfaceTools,
} from "@guildai/agents-sdk";
import { gitHubTools } from "@guildai-services/guildai~github";

// Include only what you need
const tools = {
  ...userInterfaceTools,
  ...pick(gitHubTools, [
    "github_repos_get",
    "github_pulls_list",
    "github_issues_create_comment",
  ]),
};

// Or exclude what you don't want
const trimmedGuild = omit(guildTools, [
  "guild_generate_agent_avatar",
  "guild_create_agent_like",
  "guild_delete_agent_like",
]);
```

Keeping the tool list small reduces the chance of an LLM calling unintended tools and lowers token cost in the tool definitions portion of the prompt.