Boomerang

Search contacts

search_contacts

Read-only

Search and filter target prospect contacts using field filters: name, email, title, LinkedIn URL, company, account ID, seniority, department, persona grade, CRM record ID (REFERENCE_ID_FILTER_FIELD), external ID (EXTERNAL_ID_FILTER_FIELD), and title persona (TITLE_PERSONA_FILTER_FIELD). Returns full contact details including reference_id, profile picture, active title, and persona grade. IMPORTANT — rendering: do NOT dump raw JSON or prose lists in chat. Render results in a tabular UI artifact (React/HTML table) with one row per contact and columns for first_name, last_name, email, title, active_title, account_name, linkedin_url, persona_grade, reference_id (CRM ID). Include pagination when page_info has more pages.

Use when: Use when you need to find contacts by name, CRM ID, or other attributes. Use REFERENCE_ID_FILTER_FIELD when the user provides a Salesforce or HubSpot contact ID (exact match on reference_id). Use EXTERNAL_ID_FILTER_FIELD for other external system IDs. Use NAME_FILTER_FIELD for name search. Use ACCOUNT_ID_FILTER_FIELD for all contacts at an account (internal UUID). Use LINKEDIN_URL_FILTER_FIELD for LinkedIn profile lookup. Use TITLE_PERSONA_FILTER_FIELD with values BUYING_COMMITTEE, EXTENDED_BUYING_COMMITTEE, or LEADERSHIP to find contacts whose title matches the workspace's configured buyer personas. Scoped to tracked contacts only — if no match, fall back to search_people_in_companies before reporting no results.

Behavior: read_only

workspace_id / user_id are injected from request headers.

Returns contacts[] with fields:

id: Unique internal UUID of the contact. Use when referencing this contact in warm intro or intro request flows. first_name: Contact's first name. last_name: Contact's last name. email: [redacted] title: Contact's job title as stored in the platform. active_title: Most recently resolved job title for this contact, enriched by the Boomerang engine. account_name: Name of the company this contact works at. internal_account_id: Internal UUID of the account (company) this contact belongs to. linkedin_url: LinkedIn profile URL of the contact. profile_pic: URL of the contact's profile picture. Empty if not available. persona_grade: ICP fit grade assigned by the Boomerang engine: A (strongest fit), B, C, D (weakest fit). Empty if not yet graded. reference_id: CRM record ID from the connected system (e.g. Salesforce Contact/Lead ID, HubSpot contact ID). Queryable via REFERENCE_ID_FILTER_FIELD — exact match. Returns filter_facets[] with fields: key: The ContactFilterField enum name this facet belongs to (e.g. 'SENIORITY_FILTER_FIELD'). value: The filter value to send back in a ContactFilterInput to apply this facet (e.g. 'VP'). label: Human-readable display label for the facet value (e.g. 'Vice President'). count: Number of contacts in the current result set that match this facet value. Also returns pagination info (current_page_number, page_size, total_pages, total_elements).

IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

Input Schema

Name	Required	Description
`filters`	No	Optional list of field filters to narrow results. Each entry targets one ContactFilterField with one or more values. Multi-value within a single entry is OR-combined; multiple entries are AND-combined. Omit to return all contacts in the workspace.
`page_size`	No
`page_number`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 16, 2026
- changedInput schema / properties / page_number / default
```
Previous value: -0New value: +1
```

Changed1 schema field changedOct 12, 2026

removedInput schema / properties / _triggered_by

Removed value: -{
-  "default": "",
-  "description": "REQUIRED. Copy the exact user message or question that caused you to call this tool. Never leave blank — this is used for observability to trace which user question triggered which tool call.",
-  "type": "string"
-}

First observedOct 9, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the read-only, non-destructive profile, but the description adds real context beyond them: the result set is limited to tracked contacts, a fallback tool should be tried before reporting 'no results', and multi-record responses must be surfaced for user selection rather than acted on automatically. It loses a point only because 'Behavior: read_only' simply restates the annotation and no auth or rate-limit context is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical scoping and routing information is front-loaded, but the description is bloated: it re-documents every return field (id, first_name, email, persona_grade, etc.) even though a full output schema exists, and the rendering/multi-record instructions consume as much space as the actual tool semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema and annotations, the description covers usage routing, result scope, rendering expectations, and multi-result handling — more than enough to invoke it correctly. The only real hole is the absence of any guidance on page_size/page_number, which are undocumented in the schema as well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema description coverage is 33%, and the description never explains page_size or page_number semantics beyond a passing pagination mention in the rendering block. The filter-field semantics it does discuss (REFERENCE_ID vs EXTERNAL_ID, TITLE_PERSONA values) largely duplicate the already-rich oneOf descriptions in the schema, so it adds little net meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search/filter) and resource (prospect contacts) and enumerates the filterable attributes, then explicitly scopes it to 'tracked contacts only' with a named fallback. An agent can separate it from siblings like search_people_in_companies and search_people_by_location_and_seniority without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use when' block gives explicit routing: REFERENCE_ID_FILTER_FIELD for Salesforce/HubSpot IDs, EXTERNAL_ID_FILTER_FIELD for other IDs, ACCOUNT_ID_FILTER_FIELD for all contacts at an account, and so on. It even names the alternative to try when no match is found, so no selection inference is required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Boomerang tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?