# Tools

URL: https://www.agencytitan.com/docs/tag/mcp-tools

The AgencyTitan MCP server advertises a fixed namespaced set of meta-tools (`agencytitan_*`). Internal tools from the start pack are **not** listed individually in `tools/list`; call them through `agencytitan_call_tools`.

## Typical flow

**Every conversation must start with `agencytitan_start`.** Do not begin with `agencytitan_call_api`.

```text
agencytitan_start
        │
        ▼
agencytitan_call_tools  ←── execute tools from the returned pack (concurrent OK)
        │
        ▼
agencytitan_request_additional_tools  ←── when the pack is insufficient
        │
        ▼
agencytitan_call_tools  ←── call newly added tools
```

Optional helpers at any time after start:

- `agencytitan_get_tool_deep_guidance` — extended authoring details for one pack tool
- `agencytitan_investigate` — read-only nested investigation digest (prefer over paging fat REST lists)
- `agencytitan_call_api` — **last-resort** public `/v1` REST pass-through when pack tools cannot do the job

For `agencytitan_call_api`, never invent paths or query params. Look up the contract at `https://www.agencytitan.com/docs/` or `/v1/openapi.json`.

If instructions/knowledge are insufficient, call `agencytitan_start` again with a refined prompt and the same `conversation_id` to refresh the pack.

## agencytitan_start

**Required first call** for every conversation (new or continued). Send the user prompt (or your summary). Returns a router-selected internal tool pack, curated instructions/knowledge, identity, and `conversation_id`. Do normal work with `agencytitan_call_tools` after this.

| Param | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | yes | Natural-language request or summarized intent |
| `client_model` | string | yes | External model id for logging (e.g. `gpt-5.5`, `claude-sonnet-5`) |
| `conversation_id` | string | no | Prior `conversation_id` to continue the same session |
| `client_provider` | string | no | Provider if known (`openai`, `anthropic`, `google`, …) |
| `client_id` | string | no | Optional client UUID to ground the request |
| `task_id` | string | no | Optional task UUID to ground the request |
| `ticket_id` | string | no | Optional ticket UUID to ground the request |
| `enable_rag` | boolean | no | When true (default), include tenant knowledge retrieval |

## agencytitan_call_tools

Execute one or more AgencyTitan internal tools from the pack returned by `agencytitan_start`. Supports concurrent calls. Only tools in the current session allowlist (plus control tools) are permitted.

| Param | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | From `agencytitan_start` |
| `calls` | array | yes | Non-empty list of `{ name, arguments? }` |

Each call item:

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Internal tool name from the start pack |
| `arguments` | object | no | Arguments for that tool |

## agencytitan_request_additional_tools

Ask AgencyTitan to expand the selected tool pack when current tools are insufficient. Returns newly added tool schemas; then call them via `agencytitan_call_tools`.

| Param | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | From `agencytitan_start` |
| `reason` | string | yes | Why the current tools are insufficient and what you still need |
| `missing_capabilities` | string[] | no | Short list of missing capabilities |
| `suggested_tool_names` | string[] | no | Candidate internal tool names |

## agencytitan_get_tool_deep_guidance

Fetch extended authoring guidance for a specific internal tool from the current pack.

| Param | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | From `agencytitan_start` |
| `tool_name` | string | yes | Internal tool name |

## agencytitan_investigate

Run a read-only nested investigation against AgencyTitan data and return a concise digest.

| Param | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | From `agencytitan_start` |
| `prompt` | string | yes | What to investigate |
| `focus_topics` | string[] | no | Optional focus topics |

## agencytitan_call_api

**Last-resort** pass-through to the AgencyTitan public REST API (`/v1`). Provide method, path, and optional query/body. Executes as the authenticated MCP user through the same facades as OpenAPI. Prefer `agencytitan_call_tools` / `agencytitan_request_additional_tools` / `agencytitan_investigate` first. Do not invent paths or params — use `https://www.agencytitan.com/docs/` or `/v1/openapi.json`.

| Param | Type | Required | Description |
|---|---|---|---|
| `method` | string | yes | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |
| `path` | string | yes | Public API path, e.g. `/v1/clients` or `/v1/tickets/{id}` |
| `query` | object | no | Query string parameters |
| `body` | object | no | JSON body for `POST`/`PUT`/`PATCH` |
| `path_params` | object | no | Explicit path params if not embedded in `path` |

## Operations

_This tag has no REST operations (guide / concept page)._

## Useful links

- Interactive page: https://www.agencytitan.com/docs/tag/mcp-tools
- API reference home: https://www.agencytitan.com/docs/
- This page as Markdown: https://www.agencytitan.com/docs/tag/mcp-tools.md
- Full API Markdown: https://api.agencytitan.com/v1/llms.txt