contacts_find
👤 Search for contacts in your address book by name or username.
When to use:
User asks 'find contact X' or 'who is Y?'
User wants to know someone's username or ID
Before sending a message to verify contact exists
To get contact's channel reference for messaging
Examples: ❓ User: 'find contact named [name]' → contacts_search(query='[name]', limit=5)
❓ User: 'who is [full name]?' → contacts_search(query='[full name]', limit=1)
❓ User: 'search for @username' → contacts_search(query='username', limit=10)
A single first name ('Dima') also finds private chats where the owner wrote that name (match_type='addressed_in_outgoing', with evidence): people are often saved under a nickname but called by name in the chat.
Returns: name, username, channel, channel_ref, similarity_score, match_type. Plus:
entity_id: local DB key — pass to contacts.profile. Null for live-discovered contacts (skip contacts.profile for those).
telegram_user_id (when channel='telegram'): the Telegram user ID — pass to calls.make / messages.send. NOT entity_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| query | Yes | Name or username to search for (supports partial matches) | |
| channel | No | Filter by channel. OMIT to search across all channels. | |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. |