👤 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)
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.
Connector