Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Applies to: Dynamics 365 Customer Service
Note
- The tools and examples in this documentation illustrate current capabilities. Tool names, descriptions, parameters, response formats, and available functionality can change over time.
- When you build agents, integrations, or orchestration logic, don't hard-code dependencies on specific tool names, parameter structures, tool metadata, or response schemas. Instead, design your solution to discover and use available tools at runtime.
- As the platform evolves, Microsoft might add, remove, rename, or modify tools and tool metadata. Designing against capabilities rather than specific tool identifiers helps maintain compatibility across service updates.
Use this capability when you need to find a record to associate with another record, such as setting a customer on a case or assigning an account to an opportunity.
What it does
The assistant searches Dynamics 365 records by name, or accounts and contacts by phone number, so you can pick one to link to another record. This is typically used when you want to:
- Set or change the customer on a case.
- Assign an account or contact to a lookup field.
- Link a record to another record.
- Pick a user, team, or queue for assignment.
After the search results appear, the assistant asks you which record to select, then applies the association using a separate update step.
Try prompts like
- Find a contact to set as the customer on this case.
- Pick an account for this opportunity.
- Assign this case to a user named Alex.
- Set the customer on this case to Jordan Reyes.
- Find an account named Contoso for this lookup.
- Find the contact with phone number +1-555-0142 for this lookup.
- Change the customer to Fabrikam.
What you'll see in chat
The assistant displays a text list of matching records directly in the chat conversation, including the record name and entity type. The assistant then asks you which record to select. There is no interactive widget for this capability.
Helpful tips
- You can search across multiple entity types at once, for example both accounts and contacts for a Customer lookup.
- Phone lookup supports account and contact targets and checks their standard phone fields.
- Phone lookup uses primary common fields by default. Exhaustive coverage prioritizes those fields and searches up to 48 readable Dataverse Phone-formatted fields, including custom fields.
- After you pick a record, the assistant uses a separate step to apply the association.
- For general searching or browsing, say "search for" or "list" instead. This tool is specifically for finding records to link.
- The assistant asks for confirmation before applying the association.
Tip
This capability is most useful when you are in the middle of updating a record and need to find a related record to link.
What happens next
After you select a record, the assistant applies the association. You can then continue with prompts like:
- Show this record.
- Update another field.
- Summarize this case.
- Open the linked record.
Does this change data?
No, the search itself doesn't change data.
The search is read-only. The follow-up step that applies the association changes data. The assistant asks for confirmation before making that change.
Prerequisites
This tool is available on the Dynamics 365 Customer Service MCP server. See the availability note at the top of this page for details. No additional configuration is required.
Tool summary
| Property | Value |
|---|---|
| User-facing name | Search lookup records |
| Internal tool name | search_lookup_records |
| Purpose | Searches Dataverse records by name or phone to find a specific record for association with another record through a lookup field |
Tool behavior
Searches Dataverse records by name, or account and contact records by phone, to find a specific record for association with another record through a lookup field. Supports searching across one or many entity types in a single call. A phone-only request with no entity scope searches both accounts and contacts. Primary phone coverage uses product-curated common fields. Exhaustive coverage prioritizes those fields and searches up to 48 readable Dataverse Phone-formatted fields. When both search and phone are provided, both predicates must match. When metadata or field limits, candidate retrieval, or the requested result limit omits matches, the response includes phoneLookupTruncated: true and the narration warns that additional matches may exist.
Annotations
| Annotation | Value | Meaning |
|---|---|---|
readOnlyHint |
true |
This tool doesn't modify data. |
destructiveHint |
Not set | Not applicable (read-only tool). |
idempotentHint |
Not set | Not applicable (read-only tool). |
openWorldHint |
Not set | Uses default (queries Dataverse). |
Input concepts
Entity scope (single)
| Input | Description | Required |
|---|---|---|
entityLogicalName |
entityLogicalName (string, optional). A single entity type to search. Provide this or entityLogicalNames, not both. |
No |
Entity scope (multiple)
| Input | Description | Required |
|---|---|---|
entityLogicalNames |
entityLogicalNames (string array, optional). Multiple entity types to search simultaneously (for example, ['account', 'contact'] for Customer lookup fields). Maximum 10 entity types. |
No |
Search term
| Input | Description | Required |
|---|---|---|
search |
search (string). Search term to match against the entity primary name. At least one of search or phone is required. |
Conditional |
Phone
| Input | Description | Required |
|---|---|---|
phone |
Phone number for account or contact lookup. When entity scope is omitted, the tool searches both entity types. Accounts check telephone1, telephone2, and telephone3; contacts check telephone1 and mobilephone. At least one of search or phone is required. |
Conditional |
Search coverage
| Input | Description | Required |
|---|---|---|
searchCoverage |
primary (default) searches curated common phone fields. exhaustive searches up to 48 readable Dataverse Phone-formatted fields and reports truncation when more exist. Applies when phone is supplied. |
No |
Result limit
| Input | Description | Required |
|---|---|---|
top |
top (integer, optional, max 100). Maximum records per entity type. Default 25. |
No |
Response and UI behavior
This tool returns a text-only response with no app-in-chat component.
This MCP tool is supported by an MCP app.
Response type
Text list of matching records
The response includes matched records with their ID, entity type, display name, and optional secondary text. Phone results include the matched stored phone value, field, and match type. phoneLookupTruncated: true means metadata or field limits, candidate retrieval, or the requested result limit may have omitted additional matches. The assistant presents results and asks the user which record to select.
Routing notes
Use search_lookup_records for:
- set as, assign as, change to, associate with, link to, set the customer, pick a contact for, find a record to attach.
- Any prompt where the goal is to find a record for lookup field association.
- Account or contact lookup association by phone number.
Don't use search_lookup_records when the prompt explicitly says:
- General entity browsing or search—route to
search_entities. - Listing records by criteria—route to
list_accounts,list_contacts, orlist_cases. - Viewing a record's details—route to
get_entity_record,get_account, orget_contact.
Related tools
| Tool | Relationship |
|---|---|
search_entities |
General entity search; use for browsing, not lookup association |
update_entity_record |
Updates the lookup field after the user selects a record |
update_case |
Updates case-specific fields including customer lookup |
list_accounts |
Lists accounts; use when filtering rather than searching for association |
list_contacts |
Lists contacts; use when filtering rather than searching for association |
Data mutation classification
Read-only.
This tool doesn't change data. It searches for records that can then be associated through a separate update tool.