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

# goody_contacts_search

> Find a workspace contact by name, email, or phone — returns up to 25 matches.

**Permission:** `Read` · **Workspace:** required (from `goody_workspaces_list`)

Searches the contacts in a workspace and returns up to `limit` matches. Use it to find a recipient before pricing or sending a gift. Match a free-text `query` across name, email, and phone — or omit it to list everyone alphabetically.

## Parameters

**workspace\_id** `string` *required*

Workspace UUID — from `goody_workspaces_list`. Search is always scoped to this workspace.

**query** `string`

Free-text search matched across first name, last name, email, and phone. Name matches outrank email matches, which outrank phone matches. Omit to list contacts alphabetically.

**limit** `integer` (default: 25)

Maximum contacts to return. Range 1–25; higher values are clamped to 25. There's no pagination — narrow `query` instead of raising the limit.

## Returns

**contacts** `object[]`

Up to `limit` matching contacts.

**contact**

**id** `string`

Contact UUID — pass as `contact_id` to [`goody_contacts_get`](https://developer.ongoody.com/mcp-reference/tools/contacts-get) or [`goody_contacts_update`](https://developer.ongoody.com/mcp-reference/tools/contacts-update).

**first\_name** `string | null`

Given name.

**last\_name** `string | null`

Family name.

**email** `string | null`

Email address.

**phone** `string | null`

Phone number.

**company** `string | null`

Company name.

**title** `string | null`

Job title.

> [!NOTE]
>
> The search response omits event dates. To get a contact's birthday or work anniversary, call [`goody_contacts_get`](https://developer.ongoody.com/mcp-reference/tools/contacts-get).

## Example

```text 💬 Prompt theme={null}
"Find my contact Sarah at Acme."
```

```json 🔧 Tool call theme={null}
{
  "name": "goody_contacts_search",
  "arguments": { "workspace_id": "3f8a…", "query": "Sarah Acme" }
}
```

```json ↩️ Result theme={null}
{
  "contacts": [
    {
      "id": "7b21…",
      "first_name": "Sarah",
      "last_name": "Chen",
      "email": "sarah@acme.com",
      "phone": "+14155550148",
      "company": "Acme",
      "title": "Head of People"
    }
  ]
}
```

> [!TIP]
>
> Once you have a match, call [`goody_contacts_get`](https://developer.ongoody.com/mcp-reference/tools/contacts-get) for the full detail (including birthday and work anniversary), or
> [`goody_contacts_update`](https://developer.ongoody.com/mcp-reference/tools/contacts-update) to edit it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.