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

# Lookups

> Configure lookup tools from connected integrations.

Lookups are read-only tools from connected integrations. They let the AI Agent
fetch up-to-date information during a conversation: for example, retrieving
customer details or ticket comments.

For CRM knowledge base imports, see [Zendesk](./zendesk-knowledge-base) or
[Salesforce](./salesforce-knowledge-base).

## Lookups vs actions

Lookups and actions behave differently when you connect an integration:

| Tool type   | Behavior                                                                                                            |
| :---------- | :------------------------------------------------------------------------------------------------------------------ |
| **Lookups** | Automatically available from connected integrations. Can be authorized or unauthorized.                             |
| **Actions** | Only available when explicitly configured in [Action Hub](/documentation/actions/overview). Cannot be unauthorized. |

Lookups run automatically once connected. Actions require explicit setup.

## Authorized vs unauthorized lookups

When you connect an integration (MCP server, Composio, etc.), all its lookup
tools become available to the AI Agent:

| Type             | Description                                                                                                     |
| :--------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Authorized**   | Added to Knowledge Hub. No approval required.                                                                   |
| **Unauthorized** | Available but not added to Knowledge Hub. Require Human Agent approval for all subsequent actions and messages. |

Authorized lookups run silently. Unauthorized lookups flag the conversation for
review.

### Why unauthorized lookups exist

Many actions need supporting data to work. For example, an MCP action "Create
support ticket" might require a project ID. The AI Agent can fetch that ID using
a lookup, but if you haven't explicitly added that lookup to Knowledge Hub,
it's unauthorized.

Rather than block the AI or require you to manually configure every dependency,
unauthorized lookups let the AI gather what it needs. The trade-off: a Human
Agent must approve before anything acts on that data.

### How approval works

**Example:** You configure an MCP action called "Create support ticket" that
requires a project ID.

1. Customer asks to log an issue
2. AI Agent calls `get_projects` to find the project ID. This lookup isn't in
   Knowledge Hub, so it's unauthorized
3. The lookup returns the project ID
4. AI Agent prepares to create the ticket
5. Human Agent sees: *"Action approval required: We need your approval since we
   had to perform additional lookups to get information for this action."*
6. Human Agent clicks **Yes** to approve or **Takeover** to handle manually

<Note>
  The lookup completes: the AI gets the data it needs. Approval is required
  before the AI *acts* on that data or sends messages to the customer. This lets
  the AI work while you maintain oversight.
</Note>

## Add a lookup to Knowledge Hub

Adding a lookup authorizes it: the AI Agent can use it without triggering
approval workflows.

<Steps>
  <Step title="Open Knowledge Hub">
    Go to [Knowledge Hub](https://platform.typewise.app/knowledge-hub) and click **Add source**.
  </Step>

  <Step title="Choose integration">
    Select the integration containing your lookup (for example, Linear or
    Salesforce).
  </Step>

  <Step title="Select the lookup">
    Choose the specific lookup tool (for example, `get_customer_details`). If the
    lookup is already used elsewhere, the picker shows a warning with the usage
    count.
  </Step>

  <Step title="Configure and save">
    Set the **Name**, description, access level, and inputs, then click
    **Confirm**.
  </Step>
</Steps>

## Reuse the same lookup multiple times

You can authorize the same lookup tool more than once in Knowledge Hub. Each
source keeps its own **Name**, description, and input mappings so the AI Agent
can choose the right variant (for example, pending vs cancelled order searches).

When you select a lookup that is already configured, the picker shows how many
other sources already use it. The Sources table shows each instance under its
custom **Title**.

<Note>
  Two sources with the same tool, description, and inputs are blocked. A valid
  variant needs a unique **Name** and a different description or input mapping.
</Note>

## When to authorize lookups

**Authorize a lookup when:**

* It retrieves non-sensitive data (project names, status lists)
* You want fully autonomous AI operation
* The lookup supports frequently used actions

**Keep unauthorized when:**

* It retrieves sensitive customer data
* You want Human Agents to review each usage
* You're still evaluating the integration

## Configuration

| Field                  | Description                                                                                                                                                                                                               |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Lookup**             | The lookup tool from the connected integration (for example, `get_customer_details`).                                                                                                                                     |
| **Name**               | Readable name for this lookup instance (shown in Knowledge Hub and used to distinguish variants).                                                                                                                         |
| **Action description** | What the lookup does. Helps the AI Agent decide when to use it.                                                                                                                                                           |
| **Access level**       | Controls whether data can be shared with customers or used only internally. See [Access levels](/documentation/knowledge/access-levels).                                                                                  |
| **Customize inputs**   | Per input, pick a source (Auto, Static, or a context variable). On variable mappings, enable **Trusted only** to require a verified value at runtime. See [Context Variables](/documentation/settings/context-variables). |

## See also

* [Access levels](/documentation/knowledge/access-levels): control data sharing
  and visibility
* [AI actions](/documentation/actions/ai-actions): configure actions that
  modify data
* [MCP](/documentation/integrations/mcp): connect custom MCP servers
* [Context Variables](/documentation/settings/context-variables): declare
  context variables and customize lookup inputs
* [Security & verification](/documentation/actions/security): the trust model
  behind input customization