List contacts

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 want to find contacts, review them in chat, and take action without leaving the conversation.

What it does

The assistant shows a list of contacts that match your filters. You can filter by:

• Whether the contact is assigned to you.
• Contact status (active or inactive).
• Parent company.
• Contact name.
• Phone number across primary or exhaustive phone-field coverage.

Results appear in an interactive contact list inside chat.

Try prompts like

• Show my contacts.
• List my active contacts.
• Show contacts at Contoso.
• List inactive contacts.
• Show contacts assigned to me.
• Find Jordan Reyes.
• Find the contact with phone number +1-555-0142.
• List all contacts.
• Show contacts at Fabrikam.

What you'll see in chat

The assistant displays an interactive contact list as an app-in-chat component. The list shows matching contacts with key details such as name, email, phone, company, and job title.

Helpful tips

• Say "my contacts" or "assigned to me" to see only contacts you own.
• Use status words like active or inactive to filter results.
• Use a company name to find contacts at a specific organization, for example "show contacts at Contoso."
• Use a phone number to match either the business phone or mobile phone field.
• Ask for exhaustive phone coverage to include readable custom and additional Phone-formatted fields.
• Combine filters by saying something like "show my active contacts at Fabrikam."
• If you want a text summary of a contact, say "summarize contact Jordan Reyes" instead.

Tip

After the contact list appears, you can ask follow-up questions about any contact shown. For example, "open the first contact" or "summarize Jordan Reyes."

What happens next

After the list appears, you can continue with prompts like:

• Open the first contact.
• Summarize this contact.
• Show the account for this contact.
• Update this contact's email address.

Does this change data?

No, listing contacts doesn't change data.

The contact list is read-only. Follow-up actions from the list, such as updating a field, can change data. The assistant asks for confirmation before making changes.

What you can do from the app-in-chat component

From the contact list in chat, you can:

• Scan and review matching contacts in a sortable grid.
• Select a contact to see more details.
• Open the full contact form in Dynamics 365.
• Update supported fields inline when available.
• Continue working with the contact in chat using follow-up prompts.

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	List contacts
Internal tool name	list_contacts
Purpose	Lists customer contacts filtered by status, parent company, owner, name, or phone and renders them in an interactive grid-style app-in-chat experience

Tool behavior

Lists customer contacts filtered by status, parent company, owner, name, or phone and renders them in an interactive grid-style app-in-chat experience. The search parameter performs a contains-match against the contact name. The phone parameter checks business phone (telephone1) and mobile phone (mobilephone) with primary coverage. Exhaustive coverage prioritizes those common fields and searches up to 48 readable Dataverse Phone-formatted fields, including custom fields. Phone matching first checks the stored value exactly, then uses formatting-insensitive comparison for eligible 7-15 digit values. 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. The retired additionalFilter input is rejected; use the documented first-class filters.

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

Search

Input	Description	Required
—	free-text string. Performs a contains-match against the contact name.	No

Company

Input	Description	Required
—	filter by parent company name (contains match). Use when the user specifies a company or organization.	No

Phone

Input	Description	Required
phone	Phone number to match against telephone1 and mobilephone. Duplicate matches are returned for disambiguation.	No

Search coverage

Input	Description	Required
searchCoverage	primary (default) searches business phone and mobile phone. exhaustive searches up to 48 readable Dataverse Phone-formatted fields and reports truncation when more exist.	No

Status

Input	Description	Required
active, inactive	active or inactive. Filters by contact state code.	No

Ownership scope

Input	Description	Required
assignedToMe	assignedToMe (boolean). When true, scopes results to contacts owned by the current user.	No

Result limit

Input	Description	Required
top	top (integer). Maximum number of contacts to return. Defaults to 10, max 200.	No

Response and UI behavior

This tool renders an interactive app-in-chat contact grid.

This MCP tool is supported by an MCP app.

Response type

Interactive grid (list view)

The grid displays contact name, email, phone, company, and job title. Users can select a row to drill into contact detail or take follow-up actions through chat.

Routing notes

Use list_contacts for:

• my contacts, contacts assigned to me, my active contacts.
• Status-based filtering (active, inactive).
• Company-based filtering.
• Contact name search.
• Phone-number lookup.

Don't use list_contacts when the prompt explicitly says:

• A specific contact by name for detail view—route to get_contact.
• "Summarize" a contact (person)—route to summarize_contact.
• Free-text search across multiple entity types—route to search_entities.
• Lookup field association—route to search_lookup_records.

Related tools

Tool	Relationship
get_contact	Opens the full contact form for a selected contact
summarize_contact	Generates an AI-powered contact summary
list_accounts	Lists accounts; often used alongside contact browsing
search_entities	Free-text search across any entity type
search_lookup_records	Searches records for lookup field association
list_entity_records	Generic entity grid for entity types without a dedicated list tool

Data mutation classification

Read-only entry point with downstream mutation potential.

The listing itself doesn't change data. Follow-up actions from the grid (update, edit fields) can trigger write operations through separate tools.