Semantics
Read-only. Given a query string (email or partial name), returns matching contacts with id, name, email, company. Email match is exact + case-insensitive. Name match is substring + case-insensitive.
Invariants
- Pure read. No state change.
- Email match takes priority over name match in ranking.
When to use
Before `log_activity`, `create_deal`, or any operation that needs a contact_id, when the agent doesn't already know whether a contact exists. Cheaper and clearer than calling `create_contact` and relying on idempotency.
Input schema
{
"type": "object",
"required": [
"query"
],
"properties": {
"limit": {
"type": "number",
"maximum": 50,
"minimum": 1
},
"query": {
"type": "string",
"minLength": 1,
"description": "Email (exact match) or name fragment (substring)."
},
"agent_vendor": {
"type": "string"
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"contact_id",
"name",
"email"
],
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"company": {
"type": "string"
},
"contact_id": {
"type": "string"
},
"match_kind": {
"enum": [
"email_exact",
"name_substring"
],
"type": "string"
}
}
}
}
}
}