search_users
Search users on Carbon Voice by phone numbers, email addresses, IDs, or names. Find contacts or specific individuals quickly using identifiable details.
Instructions
Search multiple Users by their phone numbers, email addresses, ids or names. (In order to search Users, you must provide phone numbers, email addresses, ids or names.)When searching by name, only users that are part of your contacts will be returned
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| emails | No | Email Addresses | |
| ids | No | User IDs | |
| names | No | The names of the users to search for (Only users that are part of your contacts will be returned) | |
| phones | No | Phone Numbers |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"emails": {
"description": "Email Addresses",
"items": {
"type": "string"
},
"type": "array"
},
"ids": {
"description": "User IDs",
"items": {
"type": "string"
},
"type": "array"
},
"names": {
"description": "The names of the users to search for (Only users that are part of your contacts will be returned)",
"items": {
"type": "string"
},
"type": "array"
},
"phones": {
"description": "Phone Numbers",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
Implementation Reference
- src/server.ts:373-385 (handler)The core handler function for the 'search_users' MCP tool. It takes input args, adds auth header, calls simplifiedApi.searchUsers, formats the response, and handles errors.async (args: SearchUsersBody, { authInfo }): Promise<McpToolResponse> => { try { return formatToMCPToolResponse( await simplifiedApi.searchUsers( args, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error searching users:', { args, error }); return formatToMCPToolResponse(error); } },
- src/server.ts:360-386 (registration)Registration of the 'search_users' tool on the MCP server, including description, input schema reference, annotations, and inline handler.server.registerTool( 'search_users', { description: 'Search multiple Users by their phone numbers, email addresses, ids or names. ' + '(In order to search Users, you must provide phone numbers, email addresses, ids or names.)' + 'When searching by name, only users that are part of your contacts will be returned', inputSchema: searchUsersBody.shape, annotations: { readOnlyHint: true, destructiveHint: false, }, }, async (args: SearchUsersBody, { authInfo }): Promise<McpToolResponse> => { try { return formatToMCPToolResponse( await simplifiedApi.searchUsers( args, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error searching users:', { args, error }); return formatToMCPToolResponse(error); } }, );
- TypeScript interface defining the input parameters for the search_users tool: optional arrays of emails, phones, ids, or names.export interface SearchUsersBody { /** Email Addresses */ emails?: string[]; /** Phone Numbers */ phones?: string[]; /** User IDs */ ids?: string[]; /** The names of the users to search for (Only users that are part of your contacts will be returned) */ names?: string[]; }
- Generated API helper function simplifiedApi.searchUsers that performs a POST request to /simplified/users/search with the search body, called by the MCP handler.const searchUsers = ( searchUsersBody: SearchUsersBody, options?: SecondParameter<typeof mutator>, ) => { return mutator<User[]>( { url: `/simplified/users/search`, method: 'POST', headers: { 'Content-Type': 'application/json' }, data: searchUsersBody, }, options, ); };